Lenovo XClarity Integrator para Proxmox

Lenovo XClarity Integrator para Proxmox es una herramienta basada en Python que permite la actualización automática de firmware en entornos de Proxmox Cluster que funcionan sobre servidores Lenovo ThinkSystem. Se integra con Lenovo XClarity Administrator (LXCA) para asegurar que tu infraestructura se mantenga actualizada con las últimas novedades de hardware, minimizando el tiempo de inactividad y reduciendo la intervención manual.

Esta solución está pensada para administradores de TI que buscan simplificar la gestión de actualizaciones en sus clústeres Proxmox.

Funcionalidades

Integración directa con la API REST de Lenovo XClarity Administrator.
Actualización automática de firmware según la política aplicada vía Lenovo XClarity Administrator
Operaciones de actualización conscientes del clúster para reducir interrupciones de servicio.
Registro y reporte de los resultados de las actualizaciones.
Configuración personalizable mediante config.ini.

Cómo funciona

Al ejecutar el programa, realiza los siguientes pasos:

Carga los parámetros de ejecución desde el archivo config.ini
Solicita la contraseña maestra, si las contraseñas están almacenadas de forma segura (es decir, cifradas)
Verifica que los hosts estén gestionados por LXCA y que tengan asociada una política de cumplimiento de firmware
Verifica si los hosts cumplen con la política de cumplimiento asignada
- Si no cumplen, de forma secuencial, evacúa las VMs y CTs del host, realiza la actualización de firmware mediante LXCA, y luego regresa las VMs al host actualizado

Requisitos

Python: 3.x (probado con Python 3.11 y Python 3.13 (SSL estricto))
Las librerías de Python listadas en requirements.txt
Una instancia activa de Lenovo XClarity Administrator con credenciales de API adecuadas
Un clúster Proxmox VE o nodo único Proxmox VE funcionando sobre servidores soportados por Lenovo XClarity Administrator (probado solo en servidores Lenovo ThinkSystem)
Una Política de Cumplimiento asignada a cada servidor del clúster
Un sistema operativo donde ejecutar esta herramienta (se recomienda Linux, aunque debería funcionar también en Windows). ATENCIÓN: No se recomienda ni se soporta ejecutarla directamente en los servidores Proxmox.

Instalación

Descomprime el paquete en tu sistema (preferentemente basado en Linux)
(Opcional pero recomendado) Configura un entorno virtual de Python 2.1. Crea un nuevo entorno virtual en el directorio del proyecto:
```
python -m venv venv
```
2.2. Activa el entorno virtual:
- En Linux/Mac:
```
source venv/bin/activate
```
- En Windows:
```
venv\Scripts\activate
```
Instala las dependencias:
```
pip install -r requirements.txt
```
Prepara tu archivo de configuración (ver Archivo de Configuración abajo).

Archivo de Configuración

Revisa el archivo de configuración de ejemplo config.ini.sample. Este archivo contiene todos los parámetros configurables, incluyendo:
- Hostname o IP de LXCA
- Credenciales de API de LXCA
- Lista de nodos del clúster Proxmox
Copia el ejemplo y personalízalo:
```
cp config.ini.sample config.ini
```

Edita config.ini con tu editor favorito para declarar los ajustes específicos de tu entorno.

Detalle de campos

Sección Proxmox

PROXMOX_USER - Obligatorio - Este campo contiene el nombre de usuario autorizado para acceder al clúster Proxmox (cada nodo del clúster) y para realizar acciones como migrar VMs. DEBE ser un usuario Linux ya que también se necesita para poner el nodo en modo mantenimiento. - Valor por defecto = root@pam (sin comillas).
PROXMOX_PASS - Obligatorio - Aquí debes almacenar la contraseña del usuario declarado en el campo PROXMOX_USER. La contraseña puede guardarse, sin comillas, en texto plano (más fácil, menos seguro) o de forma cifrada (más seguro). Para instrucciones sobre cómo almacenar la contraseña cifrada en el archivo de configuración, consulta la "Sección de Seguridad" más abajo.
PROXMOX_VERIFY_SSL - Obligatorio - Si quieres omitir la validación del certificado SSL puedes poner este campo en False. Normalmente con certificados autofirmados este es el comportamiento más común; si usas certificados autofirmados y Python > 3.11 DEBES poner este parámetro en False. Puedes poner este campo en True siguiendo las instrucciones de la sección "Validación de Certificado CA".
CLUSTER_NODES - Obligatorio - Este campo contiene el/los host(s) que pueden ser actualizados por la herramienta. El campo es un array donde cada elemento es un objeto tipo JSON que describe tres parámetros para el host: -- xcc = la dirección IP del XCC del host (DEBE ser la IP y no el hostname) -- pve_ip = la dirección IP del host PVE -- pve_host = el hostname del host PVE

el formato esperado para el host es: {"xcc":<IP_xcc_node>, "pve_ip": <IP_node> , "pve_host": <NAME_node>}

TIMEOUT_HOST - Opcional - Especifica aquí el tiempo máximo (en segundos) para esperar que el proceso de actualización termine. - Valor por defecto = 3600
TIMEOUT_VM - Opcional - Especifica aquí el tiempo máximo (en segundos) para esperar que las operaciones de VM (migrar, apagar) terminen antes de devolver un error. - Valor por defecto = 300 segundos
VM_LOCAL_DISKS - Obligatorio - Los valores permitidos son: POWEROFF para autorizar a la herramienta a apagar las VMs con discos locales (por ejemplo, cdrom, discos de VM en almacenamiento local), FAIL para detener el procedimiento y permitir la remediación manual. - Valor por defecto = FAIL
VM_LOCAL_RESOURCES - Obligatorio - Los valores permitidos son: POWEROFF para autorizar a la herramienta a apagar las VMs con recursos locales (por ejemplo, adaptador PCIe), FAIL para detener el procedimiento y permitir la remediación manual. - Valor por defecto = FAIL
VM_LOCAL_DISKS_EXPERT - Experimental - Opcional - ¡Usar bajo tu propio riesgo! - SOLO EXPERTOS - No lo uses a menos que sepas lo que haces. Este parámetro permite la migración de VMs con disco local (sin cdrom). Depende de ti verificar que todos los requisitos se cumplen en tiempo de ejecución (por ejemplo, mismos nombres de almacenamiento, suficiente espacio en disco, etc). Los valores permitidos son: True, el programa intentará migrar la VM con disco local (sin cd-rom local), o False, el programa seguirá lo indicado en VM_LOCAL_DISKS. Valor por defecto = False

Sesión LXCA

LXCA_HOST - Obligatorio - Este campo contiene la dirección IP (o el hostname si es resuelto por DNS) de la instancia de Lenovo XClarity Administrator (LXCA) que gestiona los servidores Proxmox.
LXCA_USER - Obligatorio - Este campo contiene el nombre de usuario administrativo de LXCA autorizado para realizar actualizaciones en los servidores gestionados por Proxmox.
LXCA_PASS - Obligatorio - Ingresa aquí la contraseña del usuario LXCA especificado en el campo LXCA_USER. La contraseña puede guardarse, sin comillas, en texto plano (más fácil, menos seguro) o de forma cifrada (más seguro). Para instrucciones sobre cómo almacenar la contraseña cifrada en el archivo de configuración, consulta la "Sección de Seguridad" más abajo.
LXCA_VERIFY_SSL - Obligatorio - Si quieres omitir la validación del certificado SSL puedes poner este campo en False. Normalmente con certificados autofirmados este es el comportamiento más común; si usas certificados autofirmados y Python > 3.11 DEBES poner este parámetro en False. Puedes poner este campo en True siguiendo las instrucciones de la sección "Validación de Certificado CA".

Sección de Seguridad

SALT - Opcional - Puedes guardar aquí el SALT para permitir el almacenamiento de contraseñas cifradas.

Nota: si te preocupa guardar contraseñas en texto plano en el archivo config.ini, puedes usar el siguiente procedimiento para almacenarlas cifradas. Si la opción SALT está declarada en el archivo config.ini, entonces el programa pedirá la contraseña maestra para descifrar los campos de contraseña en la configuración.

Cómo cifrar la contraseña en el `config.ini` (opcional)

Puedes ejecutar el programa create_encrypted_password.py si quieres guardar la contraseña cifrada en el archivo de configuración.

python create_encrypted_password.py

Solicitará una contraseña maestra (necesaria luego para ejecutar el integrador) y cifrará las contraseñas de PVE y LXCA, mostrando las líneas que debes poner en el archivo de configuración (ejemplo):

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

Validación de Certificado CA

Si usas certificados personalizados en tu entorno puedes elegir verificar los certificados de los hosts Proxmox y/o de la instancia LXCA para cumplir con los requisitos de seguridad.

Para esto, debes crear, en el mismo directorio de la herramienta, un archivo llamado custom_cacert.pem donde debes guardar manualmente el/los certificado(s) CA de tu entorno en formato pem (ver ejemplo abajo):

Nota: A partir de Python 3.13 se implementan algunos valores predeterminados estrictos en la gestión de SSL. Esto hace que la implementación subyacente de OpenSSL se comporte más conforme a la RFC 5280, a cambio de una pequeña incompatibilidad con certificados X.509 antiguos. El contexto SSL ahora usa VERIFY_X509_PARTIAL_CHAIN y VERIFY_X509_STRICT en sus flags de verificación por defecto. Esto significa que el certificado CA debe cumplir con todas las reglas estrictas (por ejemplo, X509v3 Key Usage, X509v3 Basic Constraints = Critical, etc).

Uso

python lxca_proxmox_integrator.py

Si no se pasa ningún parámetro, verás esta ayuda de uso:

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

DEBES especificar el parámetro -d | --dry-run o el -x | --execute.

El parámetro dry-run (-d | --dry-run) te permite simular el ciclo completo sin realizar ninguna acción en el clúster. Durante la ronda de dry-run se hará una simulación, listando todos los hallazgos en el entorno (recomendado usar con la opción -v).

Se recomienda siempre realizar un dry-run (-d | --dry-run) antes de ejecutar con el parámetro -x | --execute, ya que este sí aplicará las actualizaciones de firmware.

El parámetro -v | --verbose añade más detalle a la salida (tanto en consola como en el log).

El parámetro -c | --clearlog creará una copia de seguridad del log actual e inicializará un nuevo archivo de log vacío.

El flujo principal de la herramienta:

Solicita la contraseña maestra si es necesario (opcional)
Se conecta a tu instancia LXCA.
Verifica tus nodos ThinkSystem para actualizaciones disponibles.
Orquesta la actualización de firmware en el clúster/nodos.

Nota: Actualmente, la migración online de contenedores CT no está soportada; por lo tanto, la migración se realiza apagando el contenedor y reiniciándolo inmediatamente en el host destino.

Registro de actividad (Logging)

Todas las operaciones se registran en la consola y también en un archivo de log (lxca_proxmox_integrator.log). Revisa los logs para verificar el éxito de las actualizaciones y solucionar cualquier problema.

Avisos legales

Como buena práctica, recomendamos siempre probar las actualizaciones de firmware y drivers en un entorno de pruebas o no productivo antes de aplicarlas en todo el clúster. También puedes aprovechar la ejecución DRY_RUN para simular las demás operaciones sin aplicar actualizaciones de firmware.
Cualquier error encontrado durante el procedimiento hará que la herramienta se detenga, permitiendo al administrador de TI revisar y corregir el problema. La única excepción está relacionada con el "encendido" de las VMs/CTs, que se mostrará en el log pero el procedimiento continuará. Puede ser necesario realizar una recuperación manual para restaurar el estado correcto.
Salvo que la ley aplicable lo requiera o se acuerde por escrito, el software distribuido bajo la Licencia se distribuye "TAL CUAL", SIN GARANTÍAS NI CONDICIONES DE NINGÚN TIPO, ya sean expresas o implícitas. Consulta la Licencia para conocer las condiciones específicas que rigen permisos y limitaciones bajo la Licencia.

Licencia

Licenciado bajo la Apache License, Version 2.0 (la "Licencia"): http://www.apache.org/licenses/LICENSE-2.0

Funcionalidades​

Cómo funciona​

Requisitos​

Instalación​

Archivo de Configuración​

Detalle de campos​

Sección Proxmox​

Sesión LXCA​

Sección de Seguridad​

Cómo cifrar la contraseña en el config.ini (opcional)​

Validación de Certificado CA​

Uso​

Registro de actividad (Logging)​

Avisos legales​

Licencia​