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（strict SSL）で動作確認済み）
requirements.txt に記載された Python ライブラリ
適切な API 認証情報を持つ Lenovo XClarity Administrator の稼働インスタンス
Proxmox VE クラスター または Proxmox VE シングルノード（Lenovo XClarity Administrator がサポートするサーバー上で稼働、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 File」参照）

設定ファイル（Config File）

サンプル設定ファイル 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 で指定したユーザーのパスワードをここに保存します。パスワードは引用符なしでプレーンテキスト（最も簡単で安全性は低い）または暗号化（より安全）で保存可能です。暗号化パスワードの保存方法は「Security section」を参照してください。
PROXMOX_VERIFY_SSL - 必須 - SSL証明書の検証をスキップしたい場合はこの項目を False に設定します。自己署名証明書を使う場合はこの設定が一般的で、Python > 3.11 を使用している場合は必ず False にしてください。証明書検証を有効にする場合は「CA Certificate validation」セクションの手順に従い True に設定してください。
CLUSTER_NODES - 必須 - この項目にはツールでアップデート可能なホストを記載します。配列形式で、各要素はホストの3つのパラメータを 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 で、ローカルディスク（例：cdrom、ローカルストレージ上の VM ディスク）を持つ VM のシャットダウンをツールに許可します。FAIL で手動対応を促し処理を停止します。デフォルト = FAIL
VM_LOCAL_RESOURCES - 必須 - 許可値は POWEROFF で、ローカルリソース（例：PCIe アダプタ）を持つ VM のシャットダウンをツールに許可します。FAIL で手動対応を促し処理を停止します。デフォルト = FAIL
VM_LOCAL_DISKS_EXPERT - 実験的・任意 - 利用は自己責任で！EXPERT 専用。理解している場合のみ使用してください。このパラメータはローカルディスク（cdrom 以外）を持つ VM の移行を許可します。実行時に要件（同じストレージ名、十分なディスク容量など）が満たされているかはご自身で確認してください。許可値は True で、ローカルディスク（cdrom 以外）を持つ VM の移行を試みます。False で VM_LOCAL_DISKS の設定に従います。デフォルト = False

LXCA セッション

LXCA_HOST - 必須 - Lenovo XClarity Administrator（LXCA）インスタンスの IP アドレス（または DNS で解決可能なホスト名）を指定します。
LXCA_USER - 必須 - Proxmox 管理サーバーのアップデート権限を持つ LXCA 管理者ユーザー名を指定します。
LXCA_PASS - 必須 - LXCA_USER で指定した LXCA ユーザーのパスワードをここに記載します。パスワードは引用符なしでプレーンテキスト（最も簡単で安全性は低い）または暗号化（より安全）で保存可能です。暗号化パスワードの保存方法は「Security section」を参照してください。
LXCA_VERIFY_SSL - 必須 - SSL証明書の検証をスキップしたい場合はこの項目を False に設定します。自己署名証明書を使う場合はこの設定が一般的で、Python > 3.11 を使用している場合は必ず False にしてください。証明書検証を有効にする場合は「CA Certificate validation」セクションの手順に従い 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

特長​

動作概要​

必要条件​

インストール方法​

設定ファイル（Config File）​

項目詳細​

Proxmox セクション​

LXCA セッション​

セキュリティセクション​

config.ini でパスワードを暗号化する方法（任意）​

CA 証明書の検証​

使い方​

ログ記録​

免責事項​

ライセンス​

特長