Lenovo XClarity Integrator for Proxmox

Lenovo XClarity Integrator for Proxmox는 Lenovo ThinkSystem 서버에서 실행되는 Proxmox Cluster 환경을 위한 자동화된 펌웨어 업데이트를 지원하는 Python 기반 도구입니다. 이 도구는 **Lenovo XClarity Administrator (LXCA)**와 연동되어 인프라가 최신 하드웨어 업데이트를 유지할 수 있도록 하며, 다운타임을 최소화하고 수동 작업을 줄여줍니다.

이 솔루션은 Proxmox 클러스터 전반의 업데이트 관리를 간소화하고자 하는 IT 관리자들을 위해 설계되었습니다.

주요 기능

Lenovo XClarity Administrator REST API와의 완벽한 통합
Lenovo XClarity Administrator에서 적용한 정책에 따라 자동 펌웨어 업데이트
클러스터 인식 업데이트 작업으로 서비스 중단 최소화
업데이트 결과에 대한 로그 및 리포트 제공
config.ini를 통한 맞춤형 설정 지원

동작 방식

프로그램을 실행하면 다음과 같은 단계로 동작합니다:

config.ini 파일에서 실행 파라미터를 불러옴
비밀번호가 안전하게(암호화되어) 저장된 경우 마스터 비밀번호를 요청함
호스트가 LXCA에서 관리되고 펌웨어 컴플라이언스 정책이 연결되어 있는지 확인
호스트가 할당된 컴플라이언스 정책을 준수하는지 확인
- 준수하지 않을 경우, 순차적으로 해당 호스트에서 VM과 CT를 대피시키고, LXCA를 통해 펌웨어 업데이트를 수행한 뒤, 업데이트된 호스트로 VM을 다시 이동시킴

요구 사항

Python: 3.x (Python 3.11 및 Python 3.13(엄격한 SSL)에서 테스트됨)
requirements.txt에 명시된 Python 라이브러리
적절한 API 자격 증명이 있는 Lenovo XClarity Administrator 인스턴스
Lenovo XClarity Administrator가 지원하는 서버에서 실행 중인 Proxmox VE 클러스터 또는 Proxmox VE 단일 노드 (Lenovo ThinkSystem 서버에서만 테스트됨)
클러스터 내 각 서버에 할당된 컴플라이언스 정책
이 도구를 실행할 OS 인스턴스 (Linux 권장, Windows에서도 동작 가능). 주의: Proxmox 서버에서 직접 실행하는 것은 지원/권장하지 않습니다.

설치 방법

시스템에 패키지를 압축 해제하세요 (Linux 기반 환경 권장)
(선택 사항이지만 권장) Python 가상 환경을 설정하세요 2.1. 프로젝트 디렉터리에서 새 가상 환경을 생성하세요:
```
python -m venv venv
```
2.2. 가상 환경을 활성화하세요:
- Linux/Mac에서:
```
source venv/bin/activate
```
- Windows에서:
```
venv\Scripts\activate
```
의존성 패키지를 설치하세요:
```
pip install -r requirements.txt
```
설정 파일을 준비하세요 (설정 파일 항목 참고).

설정 파일

샘플 설정 파일 config.ini.sample을 검토하세요. 이 파일에는 다음과 같은 모든 설정 가능한 파라미터가 포함되어 있습니다:
- LXCA 호스트명 또는 IP
- LXCA API 자격 증명
- Proxmox 클러스터 노드 목록
샘플 파일을 복사하여 수정하세요:
```
cp config.ini.sample config.ini
```

환경에 맞는 설정을 위해 config.ini를 원하는 편집기로 수정하세요.

필드 상세 설명

Proxmox 섹션

PROXMOX_USER - 필수 - Proxmox 클러스터(클러스터 내 모든 노드)에 접근 및 VM 마이그레이션 등 작업을 수행할 수 있는 사용자 이름을 입력합니다. 노드를 유지보수 모드로 설정해야 하므로 반드시 Linux 사용자여야 합니다. - 기본값 = root@pam (따옴표 없이).
PROXMOX_PASS - 필수 - PROXMOX_USER 필드에 선언한 사용자의 비밀번호를 저장합니다. 비밀번호는 따옴표 없이 평문(가장 쉽고 보안 취약) 또는 암호화 방식(더 안전)으로 저장할 수 있습니다. 암호화된 비밀번호 저장 방법은 아래 "보안 섹션"을 참고하세요.
PROXMOX_VERIFY_SSL - 필수 - SSL 인증서 검증을 건너뛰려면 이 필드를 False로 설정하세요. 일반적으로 셀프 서명 인증서를 사용할 때 가장 많이 사용되며, 셀프 서명 인증서와 Python > 3.11을 사용하는 경우 반드시 이 값을 False로 설정해야 합니다. 인증서 검증을 원할 경우 "CA 인증서 검증" 섹션의 안내를 따라 True로 설정할 수 있습니다.
CLUSTER_NODES - 필수 - 이 필드에는 도구로 업데이트 가능한 호스트(들)를 입력합니다. 각 요소는 호스트의 세 가지 파라미터를 설명하는 JSON 형식의 객체입니다: -- xcc = 호스트 XCC의 IP 주소 (반드시 호스트명이 아닌 IP 주소여야 함) -- pve_ip = PVE 호스트의 IP 주소 -- pve_host = PVE 호스트의 호스트명

호스트의 예상 형식은 다음과 같습니다: {"xcc":<IP_xcc_node>, "pve_ip": <IP_node> , "pve_host": <NAME_node>}

TIMEOUT_HOST - 선택 - 업그레이드 프로세스가 완료될 때까지 기다릴 최대 시간(초)을 지정합니다. - 기본값 = 3600
TIMEOUT_VM - 선택 - VM 작업(마이그레이션, 종료)이 완료될 때까지 오류 반환 전 대기할 최대 시간(초)을 지정합니다. - 기본값 = 300초
VM_LOCAL_DISKS - 필수 - 허용 값: POWEROFF (로컬 디스크가 있는 VM(cdrom, 로컬 스토리지의 VM 디스크 등)을 종료하도록 도구에 허용), FAIL (프로시저를 중단하고 수동 조치를 허용). - 기본값 = FAIL
VM_LOCAL_RESOURCES - 필수 - 허용 값: POWEROFF (로컬 리소스(예: PCIe 어댑터)가 있는 VM을 종료하도록 도구에 허용), FAIL (프로시저를 중단하고 수동 조치를 허용). - 기본값 = FAIL
VM_LOCAL_DISKS_EXPERT - 실험적 - 선택 - 위험 부담 있음!! - 전문가 전용 - 본인이 무엇을 하는지 확실히 알지 못한다면 사용하지 마세요. 이 파라미터는 로컬 디스크(노-시디롬)가 있는 VM의 마이그레이션을 허용합니다. 실행 시 모든 요구 사항(예: 동일한 스토리지 이름, 충분한 디스크 공간 등)을 직접 확인해야 합니다. 허용 값: True (프로그램이 로컬 디스크(노-로컬 시디롬)가 있는 VM을 마이그레이션 시도), 또는 False (프로그램이 VM_LOCAL_DISKS의 설정을 따름). 기본값 = False

LXCA 세션

LXCA_HOST - 필수 - Proxmox 서버를 관리하는 Lenovo XClarity Administrator(LXCA) 인스턴스의 IP 주소(또는 DNS로 해석되는 호스트명)를 입력합니다.
LXCA_USER - 필수 - Proxmox 관리 서버에 업데이트를 수행할 수 있는 LXCA 관리자 사용자 이름을 입력합니다.
LXCA_PASS - 필수 - LXCA_USER 필드에 지정한 LXCA 사용자의 비밀번호를 입력합니다. 비밀번호는 따옴표 없이 평문(가장 쉽고 보안 취약) 또는 암호화 방식(더 안전)으로 저장할 수 있습니다. 암호화된 비밀번호 저장 방법은 아래 "보안 섹션"을 참고하세요.
LXCA_VERIFY_SSL - 필수 - SSL 인증서 검증을 건너뛰려면 이 필드를 False로 설정하세요. 일반적으로 셀프 서명 인증서를 사용할 때 가장 많이 사용되며, 셀프 서명 인증서와 Python > 3.11을 사용하는 경우 반드시 이 값을 False로 설정해야 합니다. 인증서 검증을 원할 경우 "CA 인증서 검증" 섹션의 안내를 따라 True로 설정할 수 있습니다.

보안 섹션

SALT - 선택 - 암호화된 비밀번호 저장을 위해 SALT 값을 입력할 수 있습니다.

참고: config.ini 파일에 평문 비밀번호 저장이 걱정된다면, 아래 절차를 통해 암호화하여 저장할 수 있습니다. config.ini 파일에 SALT 옵션이 선언되어 있으면, 프로그램은 설정 파일의 비밀번호 필드를 복호화하기 위해 마스터 비밀번호를 요청합니다.

`config.ini`에서 비밀번호를 암호화하는 방법 (선택 사항)

설정 파일에 암호화된 비밀번호를 저장하려면 create_encrypted_password.py 프로그램을 실행하세요.

python create_encrypted_password.py

실행하면 마스터 비밀번호를 요청(통합기 실행 시 필요)하고, PVE 및 LXCA 비밀번호를 암호화하여 설정 파일에 넣어야 할 라인을 출력합니다(예시):

Add the following three lines to your config.ini:

LXCA_PASS = gAAAAABonuj0JNenRko_DS-HTcZkFfoho_ZID6RcwLTFPNn7A2QYsNgtE3-wjzCE8R0_bpVquZLDGpe9ARpJdZ7tSEWoNXTOQg==
PROXMOX_PASS = gAAAAABonuj0aXh5IYUhClWjBaOBh9HgcvtmwyB9rYzlvnSO-NAS51rNQXaBH0CjlgvF4lkwpPsXSIi2SLpozKmueTtpV_uQJQ==
SALT = E3T1B/Ty6nk3RJq7dQq8Pg==

CA 인증서 검증

환경에서 커스텀 인증서를 사용하는 경우, Proxmox 호스트 및/또는 LXCA 인스턴스의 인증서를 검증하여 보안 준수를 선택할 수 있습니다.

이를 위해, 도구 디렉터리 내에 custom_cacert.pem 파일을 생성하고, 환경에 맞는 CA 인증서를 pem 형식으로 직접 저장해야 합니다(아래 예시 참고):

참고: Python 3.13부터 SSL 관리에 엄격한 기본값이 적용됩니다. 이로 인해 OpenSSL 구현이 RFC 5280을 더 엄격하게 준수하게 되며, 이전 X.509 인증서와 약간의 호환성 문제가 발생할 수 있습니다. SSL 컨텍스트는 기본 검증 플래그에 VERIFY_X509_PARTIAL_CHAIN 및 VERIFY_X509_STRICT를 사용합니다. 즉, CA 인증서는 모든 엄격한 규칙(예: X509v3 Key Usage, X509v3 Basic Constraints = Critical 등)을 준수해야 합니다.

사용법

python lxca_proxmox_integrator.py

파라미터 없이 실행하면 다음과 같은 사용법 안내가 출력됩니다:

usage: lxca_proxmox_integrator.py [-h] (-d | -x) [-v] [-c] [-V]

LXCA Proxmox integrator command line parameters

options:
  -h, --help      show this help message and exit
  -d, --dry-run   Simulate the upgrade
  -x, --execute   Perform the upgrade
  -v, --verbose   Add verbosity to the ouput
  -c, --clearlog  Move current log to backup and start a clean log file
  -V, --version   Show program version

반드시 -d | --dry-run 또는 -x | --execute 파라미터 중 하나를 지정해야 합니다.

드라이런 파라미터(-d | --dry-run)는 클러스터에 아무런 작업을 수행하지 않고 전체 사이클을 시뮬레이션할 수 있습니다. 드라이런 실행 시 환경 내 모든 항목을 시뮬레이션하여 나열하며, -v 옵션과 함께 사용하면 더욱 좋습니다.

펌웨어 업데이트를 실행하기 전에 항상 드라이런(-d | --dry-run)을 먼저 수행하는 것을 강력히 권장합니다.

-v | --verbose 파라미터는 출력(콘솔 및 로그)의 상세도를 높여줍니다.

-c | --clearlog 파라미터는 현재 로그의 백업을 생성하고 새로운 빈 로그 파일을 초기화합니다.

도구의 주요 워크플로우:

필요 시 마스터 비밀번호 요청(선택 사항)
LXCA 인스턴스에 연결
ThinkSystem 노드의 업데이트 가능 여부 확인
클러스터/노드 전체에 펌웨어 업데이트 오케스트레이션

참고: 현재 CT 컨테이너의 온라인 마이그레이션은 지원되지 않으므로, 컨테이너를 종료한 뒤 즉시 대상 호스트에서 재시작하는 방식으로 마이그레이션이 진행됩니다.

로그

모든 작업은 콘솔과 로그 파일(lxca_proxmox_integrator.log)에 기록됩니다. 업데이트 성공 여부 확인 및 문제 해결을 위해 로그를 검토하세요.

면책 사항

최선의 방법으로, 펌웨어 및 드라이버 업데이트는 클러스터 전체에 적용하기 전에 반드시 스테이징 또는 비운영 환경에서 테스트할 것을 적극 권장합니다. DRY_RUN 실행을 통해 펌웨어 업데이트를 적용하지 않고 다른 작업을 시뮬레이션할 수도 있습니다.
절차 중 오류가 발생하면 도구가 중단되어 IT 관리자가 문제를 확인하고 수정할 수 있습니다. 단, VM/CT의 "전원 켜기"와 관련된 예외만 로그에 표시되고 절차는 계속 진행됩니다. 올바른 상태 복구를 위해 수동 조치가 필요할 수 있습니다.
관련 법률에 의해 요구되거나 서면으로 합의된 경우를 제외하고, 라이선스 하에 배포되는 소프트웨어는 "있는 그대로" 제공되며, 명시적 또는 묵시적 어떠한 종류의 보증이나 조건도 제공하지 않습니다. 라이선스에 명시된 소프트웨어의 권한 및 제한 사항을 참고하세요.

라이선스

Apache License, Version 2.0(이하 "라이선스")에 따라 라이선스됨: http://www.apache.org/licenses/LICENSE-2.0

주요 기능​

동작 방식​

요구 사항​

설치 방법​

설정 파일​

필드 상세 설명​

Proxmox 섹션​

LXCA 세션​

보안 섹션​

config.ini에서 비밀번호를 암호화하는 방법 (선택 사항)​

CA 인증서 검증​

사용법​

로그​

면책 사항​

라이선스​