Mantenimiento y Actualizaciones

Esta página explica cómo mantener un despliegue existente de AI Cockpit: Smart Engineering on-premise después de la instalación inicial.

Las tareas operativas más comunes son:

• aplicar una nueva versión del chart
• actualizar la versión de las imágenes de la aplicación
• rotar certificados y configuraciones de ingress
• validar la salud del storage, la base de datos y la cola
• preparar backups antes de cambios
• hacer rollback cuando una actualización falla

Antes de aplicar cambios

Antes de actualizar el despliegue, confirma:

• el clúster está saludable
• PostgreSQL y Valkey funcionan normalmente
• se conoce el nombre de la release y el namespace actuales
• el archivo actual values.yaml está disponible
• existe un backup reciente de la base de datos

Comandos útiles:

kubectl get pods -n aic-modernization
kubectl get jobs -n aic-modernization
helm list -n aic-modernization
helm get values aic-modernization -n aic-modernization

Mantén el archivo de valores bajo control de versiones

No dependas solo del comando original de instalación de AWS Marketplace.

Mantén los valores efectivos del despliegue en control de versiones para:

• revisar qué cambió entre releases
• reproducir el entorno
• comparar la configuración actual con la configuración objetivo
• hacer rollback con más seguridad

Si es necesario, exporta los valores actuales antes de un upgrade:

helm get values aic-modernization -n aic-modernization -o yaml > current-values.yaml

Actualizar el despliegue

Cuando una nueva versión del chart o del producto esté disponible, actualiza el despliegue con helm upgrade.

Ejemplo:

helm upgrade aic-modernization \
  oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/compass-uol/ai-cockpit/smart-engineering-chart/aic-modernization \
  --version <new-chart-version> \
  --namespace aic-modernization \
  -f values.yaml

Para las actualizaciones, la decisión más importante es cómo Helm debe manejar los valores almacenados en la release actual.

Reutilizar los valores actuales

Usa --reuse-values cuando quieras mantener los valores ya almacenados en la release actual y aplicar solo los cambios explícitos pasados en el comando de upgrade.

Ejemplo:

helm upgrade aic-modernization \
  oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/compass-uol/ai-cockpit/smart-engineering-chart/aic-modernization \
  --version <new-chart-version> \
  --namespace aic-modernization \
  --reuse-values

Esto es útil cuando:

• la release ya tiene la configuración correcta de runtime
• solo quieres cambiar la versión del chart
• quieres minimizar el drift accidental de configuración durante el upgrade

Restablecer a los valores por defecto del chart

Usa --reset-values cuando quieras que Helm ignore los valores almacenados en la release y empiece de nuevo desde los valores por defecto del chart objetivo, más los valores que pases en el comando.

Ejemplo:

helm upgrade aic-modernization \
  oci://709825985650.dkr.ecr.us-east-1.amazonaws.com/compass-uol/ai-cockpit/smart-engineering-chart/aic-modernization \
  --version <new-chart-version> \
  --namespace aic-modernization \
  --reset-values \
  -f values.yaml

Esto es útil cuando:

• quieres que la release coincida exactamente con un values.yaml revisado
• los valores antiguos almacenados pueden ya no ser válidos
• estás estandarizando el entorno después de varios cambios manuales

Qué enfoque elegir

Como regla:

• usa --reuse-values para upgrades pequeños y de bajo riesgo
• usa --reset-values junto con un values.yaml revisado para cambios controlados de configuración o transiciones importantes de versión

Qué ocurre durante un upgrade

Durante helm upgrade, el chart puede actualizar:

• deployments de la aplicación
• tags de imagen
• configuración de runtime
• configuración de ingress
• configuración del gateway
• configuraciones de PostgreSQL o Valkey

El chart también ejecuta un job de migración después de la instalación y del upgrade.

Después del upgrade, valida:

kubectl get pods -n aic-modernization
kubectl get jobs -n aic-modernization
kubectl logs job/aic-modernization-migrate -n aic-modernization

Validar la aplicación después de un upgrade

Después de aplicar una actualización, valida:

• health de la API
• health del gateway, si está habilitado
• acceso al frontend
• flujo de subida a S3
• acceso a Bedrock
• ejecución de tareas en segundo plano

Verificaciones recomendadas:

kubectl port-forward svc/aic-modernization-api -n aic-modernization 3000:3000
curl http://localhost:3000/health
curl http://localhost:3000/config/runtime

Si el gateway está habilitado:

kubectl port-forward svc/aic-modernization-gateway -n aic-modernization 8080:8080
curl http://localhost:8080/health

Backups y protección de datos

Antes de cambiar versiones del chart, versiones de imagen, configuraciones de base de datos o configuraciones de storage, haz un backup de la base PostgreSQL.

Como mínimo, mantén:

• backups regulares de PostgreSQL
• procedimientos de snapshot de volúmenes persistentes, si tu plataforma de storage lo soporta
• una copia del values.yaml actual

Si usas PostgreSQL externo o Valkey externo, sigue la política de backup de esos servicios gestionados.

advertencia

No consideres Helm por sí solo como una estrategia de backup. Helm almacena el estado de la release, pero no sustituye los backups de base de datos.

Rollback

Si un upgrade falla y la nueva versión no debe permanecer en producción, consulta el historial de la release:

helm history aic-modernization -n aic-modernization

Después haz rollback a la revisión anterior conocida como estable:

helm rollback aic-modernization <revision> -n aic-modernization

Después del rollback, valida nuevamente los mismos endpoints de health y runtime.

Si el fallo incluyó una migración parcial de base de datos, revisa los logs de migración antes de intentar otro upgrade.

Tareas comunes de mantenimiento

Rotación de certificados de ingress

Si cambia el certificado TLS:

• actualiza el secret TLS de Kubernetes usado por ingress
• confirma que ingress sigue referenciando el secret correcto
• valida los hosts del frontend, la API y el gateway después del cambio

Actualizar orígenes permitidos

Si cambia el origen del navegador, actualiza:

• runtime.commonEnv.ALLOWED_ORIGINS
• gateway.env.CORS_ALLOW_ORIGINS, si el gateway se expone directamente

Aplica el cambio con helm upgrade.

Cambiar configuración de cifrado en S3

Si cambia la política del bucket S3 de destino:

• mantén S3_UPLOAD_SERVER_SIDE_ENCRYPTION=AES256 para el camino por defecto con cifrado administrado por S3
• cambia a aws:kms solo si el bucket requiere KMS y el rol IAM de runtime puede usar la clave KMS

Actualizar modelos de Bedrock

Si cambias los modelos, actualiza:

• bedrock.modelId
• bedrock.modelIdSmall

Después valida que:

• los model IDs de destino estén disponibles en la cuenta del cliente
• el rol IAM de runtime pueda invocar esos modelos

Checklist operativo de troubleshooting

Si el sistema queda inestable después de una actualización, revisa:

• loops de reinicio de pods
• jobs de migración fallidos
• configuraciones incorrectas de ingress
• cambios en service account o IRSA
• cambios de permisos en S3
• cambios de acceso a modelos de Bedrock
• cambios en el secret de conexión a la base
• problemas de conectividad con Valkey

Comandos útiles:

kubectl describe pod <pod-name> -n aic-modernization
kubectl logs deployment/aic-modernization-api -n aic-modernization --tail=200
kubectl logs deployment/aic-modernization-worker -n aic-modernization --tail=200
kubectl logs deployment/aic-modernization-gateway -n aic-modernization --tail=200

Rutina recomendada de mantenimiento

Una rutina práctica de mantenimiento es:

1. Exportar los valores actuales de Helm
2. Confirmar que los backups están actualizados
3. Revisar la versión objetivo del chart y los cambios de configuración
4. Ejecutar helm upgrade
5. Revisar el job de migración
6. Validar /health y /config/runtime
7. Ejecutar una pequeña tarea de documentación end-to-end

Esto hace que los upgrades sean más previsibles y simplifica el rollback cuando algo cambia de forma inesperada.