Lenovo XClarity Integrator per Proxmox

Lenovo XClarity Integrator per Proxmox è uno strumento basato su Python che consente l’aggiornamento automatico del firmware per ambienti Proxmox Cluster che girano su server Lenovo ThinkSystem. Si integra con Lenovo XClarity Administrator (LXCA) per garantire che la tua infrastruttura sia sempre aggiornata con le ultime novità hardware, riducendo i tempi di inattività e la necessità di interventi manuali.

Questa soluzione è pensata per gli amministratori IT che vogliono semplificare la gestione degli aggiornamenti nei cluster Proxmox.

Funzionalità

Integrazione diretta con le API REST di Lenovo XClarity Administrator.
Aggiornamento automatico del firmware in base alle policy applicate tramite Lenovo XClarity Administrator
Operazioni di aggiornamento consapevoli del cluster per ridurre le interruzioni di servizio.
Log e report dei risultati degli aggiornamenti.
Configurazione personalizzabile tramite config.ini.

Come funziona

Quando esegui il programma, vengono effettuati i seguenti passaggi:

Carica i parametri di runtime dal file config.ini
Richiede la master password, se le password sono archiviate in modo sicuro (cioè criptate)
Verifica che gli host siano gestiti da LXCA e che sia associata una policy di conformità firmware
Verifica se gli host sono conformi alla policy assegnata
- In caso contrario, evacua in sequenza le VM e i CT dall’host, esegue l’aggiornamento firmware tramite LXCA, e riporta le VM sull’host aggiornato

Requisiti

Python: 3.x (testato con Python 3.11 e Python 3.13 (SSL rigoroso))
Le librerie Python elencate in requirements.txt
Un’istanza attiva di Lenovo XClarity Administrator con credenziali API appropriate
Un cluster Proxmox VE o un nodo singolo Proxmox VE che gira su server supportati da Lenovo XClarity Administrator (testato solo su server Lenovo ThinkSystem)
Una Compliance Policy assegnata a ciascun server nel cluster
Un’istanza OS su cui eseguire lo strumento (Linux è preferito ma dovrebbe funzionare anche su Windows). ATTENZIONE: Non è supportato/raccomandato l’esecuzione direttamente sui server Proxmox.

Installazione

Decomprimi il pacchetto sul tuo sistema (preferibilmente Linux)
(Opzionale ma consigliato) Crea un ambiente virtuale Python 2.1. Crea un nuovo ambiente virtuale nella directory del progetto:
```
python -m venv venv
```
2.2. Attiva l’ambiente virtuale:
- Su Linux/Mac:
```
source venv/bin/activate
```
- Su Windows:
```
venv\Scripts\activate
```
Installa le dipendenze:
```
pip install -r requirements.txt
```
Prepara il tuo file di configurazione (vedi File di Configurazione sotto).

File di Configurazione

Esamina il file di configurazione di esempio config.ini.sample. Questo file contiene tutti i parametri configurabili, tra cui:
- Hostname o IP di LXCA
- Credenziali API LXCA
- Lista dei nodi del cluster Proxmox
Copia il file di esempio e personalizzalo:
```
cp config.ini.sample config.ini
```

Modifica config.ini con il tuo editor preferito per dichiarare le impostazioni specifiche dell’ambiente.

Dettaglio dei campi

Sezione Proxmox

PROXMOX_USER - Obbligatorio - Questo campo contiene il nome utente autorizzato ad accedere al cluster Proxmox (ogni nodo del cluster) e a eseguire azioni come la migrazione delle VM. DEVE essere un utente Linux poiché è necessario anche per impostare il nodo in modalità manutenzione. - Default = root@pam (senza virgolette).
PROXMOX_PASS - Obbligatorio - Qui va inserita la password dell’utente dichiarato nel campo PROXMOX_USER. La password può essere salvata, senza virgolette, in chiaro (più semplice, meno sicuro) oppure in modo criptato (più sicuro). Per le istruzioni su come salvare la password criptata nel file di configurazione, vedi la sezione "Sicurezza" sotto.
PROXMOX_VERIFY_SSL - Obbligatorio - Se vuoi saltare la validazione del certificato SSL puoi impostare questo campo su False. Di solito con certificati self-signed questo è il comportamento più comune; se usi certificati self-signed e Python > 3.11 DEVI impostare questo parametro su False. Puoi impostare questo campo su True seguendo le istruzioni nella sezione "Validazione Certificato CA".
CLUSTER_NODES - Obbligatorio - Questo campo contiene gli host che possono essere aggiornati dallo strumento. Il campo è un array dove ogni elemento è un oggetto stile JSON che descrive tre parametri per l’host: -- xcc = l’indirizzo IP dell’host XCC (DEVE essere l’indirizzo IP e non il nome host) -- pve_ip = l’indirizzo IP dell’host PVE -- pve_host = il nome host dell’host PVE

il formato atteso per l’host è: {"xcc":<IP_xcc_node>, "pve_ip": <IP_node> , "pve_host": <NAME_node>}

TIMEOUT_HOST - Opzionale - Specifica qui il tempo massimo (in secondi) da attendere per il completamento dell’aggiornamento. - Default = 3600
TIMEOUT_VM - Opzionale - Specifica qui il tempo massimo (in secondi) da attendere per le operazioni sulle VM (migrazione, spegnimento) prima di restituire un errore. - Default = 300 sec
VM_LOCAL_DISKS - Obbligatorio - I valori ammessi sono: POWEROFF per autorizzare lo strumento a spegnere le VM con dischi locali (es. cdrom, dischi VM su storage locale), FAIL per fermare la procedura e consentire la risoluzione manuale. - Default = FAIL
VM_LOCAL_RESOURCES - Obbligatorio - I valori ammessi sono: POWEROFF per autorizzare lo strumento a spegnere le VM con risorse locali (es. adattatore PCIe), FAIL per fermare la procedura e consentire la risoluzione manuale. - Default = FAIL
VM_LOCAL_DISKS_EXPERT - Sperimentale - Opzionale - Usare a proprio rischio!! - SOLO PER ESPERTI - Non usare se non si sa cosa si sta facendo. Questo parametro consente la migrazione delle VM con disco locale (no-cdrom). Sta a te verificare che tutti i requisiti siano soddisfatti a runtime (es. stessi nomi storage, spazio disco sufficiente, ecc). I valori ammessi sono: True, il programma tenterà di migrare la VM con disco locale (no cd-rom locale), oppure False, il programma seguirà quanto indicato in VM_LOCAL_DISKS. Default = False

Sezione LXCA

LXCA_HOST - Obbligatorio - Questo campo contiene l’indirizzo IP (o il nome host se risolto dal DNS) dell’istanza Lenovo XClarity Administrator (LXCA) che gestisce i server Proxmox.
LXCA_USER - Obbligatorio - Questo campo contiene il nome utente amministrativo LXCA autorizzato ad eseguire aggiornamenti sui server Proxmox gestiti.
LXCA_PASS - Obbligatorio - Inserisci qui la password dell’utente LXCA specificato nel campo LXCA_USER. La password può essere salvata, senza virgolette, in chiaro (più semplice, meno sicuro) oppure in modo criptato (più sicuro). Per le istruzioni su come salvare la password criptata nel file di configurazione, vedi la sezione "Sicurezza" sotto.
LXCA_VERIFY_SSL - Obbligatorio - Se vuoi saltare la validazione del certificato SSL puoi impostare questo campo su False. Di solito con certificati self-signed questo è il comportamento più comune; se usi certificati self-signed e Python > 3.11 DEVI impostare questo parametro su False. Puoi impostare questo campo su True seguendo le istruzioni nella sezione "Validazione Certificato CA".

Sezione Sicurezza

SALT - Opzionale - Puoi salvare qui il SALT per consentire la memorizzazione delle password criptate.

Nota bene: se sei preoccupato di salvare le password in chiaro nel file config.ini, puoi usare la seguente procedura per salvarle criptate. Se l’opzione SALT è dichiarata nel file di configurazione, il programma chiederà la master password per decriptare i campi password nella configurazione.

Come criptare la password nel file `config.ini` (opzionale)

Puoi eseguire il programma create_encrypted_password.py se vuoi salvare la password criptata nel file di configurazione.

python create_encrypted_password.py

Ti verrà chiesta una master password (necessaria poi per eseguire l’integratore) e verranno criptate le password PVE e LXCA, stampando le righe da inserire nel file di configurazione (esempio):

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==

Validazione Certificato CA

Se usi certificati personalizzati nel tuo ambiente puoi scegliere di verificare i certificati degli host Proxmox e/o dell’istanza LXCA per essere compliant con le policy di sicurezza.

Per farlo, devi creare, nella stessa directory dello strumento, un file chiamato custom_cacert.pem dove dovrai inserire manualmente il/i certificato/i CA del tuo ambiente in formato pem (vedi esempio sotto):

Nota bene: Da Python 3.13 sono stati introdotti alcuni default più restrittivi nella gestione SSL. Questi fanno sì che l’implementazione OpenSSL sottostante si comporti in modo più conforme all’RFC 5280, a scapito di una piccola incompatibilità con vecchi certificati X.509. Il contesto SSL ora usa VERIFY_X509_PARTIAL_CHAIN e VERIFY_X509_STRICT come flag di verifica di default. Questo significa che il certificato CA deve rispettare tutte le regole più restrittive (es. X509v3 Key Usage, X509v3 Basic Constraints = Critical, ecc).

Utilizzo

python lxca_proxmox_integrator.py

Senza parametri, otterrai questo aiuto sull’utilizzo:

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

DEVI specificare il parametro -d | --dry-run oppure -x | --execute.

I parametri dry-run (-d | --dry-run) ti permettono di simulare l’intero ciclo senza eseguire alcuna azione sul cluster. Durante il dry-run verrà effettuata una simulazione, elencando tutte le rilevazioni nell’ambiente (consigliato con l’opzione -v).

Si consiglia vivamente di eseguire sempre un dry-run (-d | --dry-run) prima di lanciare con il parametro -x | --execute, poiché quest’ultimo esegue gli aggiornamenti firmware.

Il parametro -v | --verbose aumenta la verbosità dell’output (sia su console che su log).

Il parametro -c | --clearlog crea un backup del log corrente e inizializza un nuovo file di log vuoto.

Il tool (workflow principale):

Chiede la master password se necessario (opzionale)
Si connette alla tua istanza LXCA.
Controlla i nodi ThinkSystem per aggiornamenti disponibili.
Orquestra l’aggiornamento firmware su cluster/nodi.

Nota bene: Al momento, la migrazione online dei container CT non è supportata; quindi la migrazione verrà effettuata spegnendo il container e riavviandolo immediatamente sull’host di destinazione.

Logging

Tutte le operazioni vengono registrate sia su console che su un file di log (lxca_proxmox_integrator.log). Consulta i log per verificare il successo degli aggiornamenti e risolvere eventuali problemi.

Disclaimer

Come best practice, consigliamo vivamente di testare sempre gli aggiornamenti firmware e driver in un ambiente di staging o non produttivo prima di distribuirli su tutto il cluster. Puoi anche sfruttare l’esecuzione DRY_RUN per simulare le altre operazioni senza applicare gli aggiornamenti firmware.
Qualsiasi errore riscontrato durante la procedura comporterà l’arresto dello strumento, consentendo all’amministratore IT di verificare e risolvere il problema. L’unica eccezione riguarda l’accensione delle VM/CT che verrà mostrata nel log ma la procedura continuerà. Potrebbe essere necessario un intervento manuale per ripristinare lo stato corretto.
Salvo quanto richiesto dalla legge applicabile o concordato per iscritto, il software distribuito sotto la Licenza è fornito "COSÌ COM’È", SENZA GARANZIE DI ALCUN TIPO, espresse o implicite. Vedi la Licenza per le specifiche condizioni che regolano permessi e limitazioni.

Licenza

Distribuito sotto licenza Apache, Versione 2.0 (la "Licenza"): http://www.apache.org/licenses/LICENSE-2.0

Funzionalità​

Come funziona​

Requisiti​

Installazione​

File di Configurazione​

Dettaglio dei campi​

Sezione Proxmox​

Sezione LXCA​

Sezione Sicurezza​

Come criptare la password nel file config.ini (opzionale)​

Validazione Certificato CA​

Utilizzo​

Logging​

Disclaimer​

Licenza​