Saltar a contenido

Runbooks de operación

Los siguientes procedimientos complementan el comportamiento versionado. Están preparados para ejecutarse desde jobs de mantenimiento en GitLab con el contexto del agente autorizado. No se han ejecutado contra una cuenta cloud durante la elaboración de esta documentación.

1. Verificar una entrega

Registrar el pipeline, el SHA de aplicación, la imagen y el commit del repositorio de manifiestos. Comprobar el destino antes de consultar recursos; AWS y GCP pueden tener un namespace y nombres iguales.

kubectl --context "$KUBE_CONTEXT" -n app get deployments,pods,services,ingresses
kubectl --context "$KUBE_CONTEXT" -n app rollout status deployment/rest --timeout=180s
kubectl --context "$KUBE_CONTEXT" -n app rollout status deployment/web --timeout=180s
kubectl --context "$KUBE_CONTEXT" -n app get deployment rest web   -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.spec.template.spec.containers[*].image}{"\n"}{end}'

Si se entrega sólo uno de los servicios, verificar ese Deployment y después su interacción con la versión existente del otro. El timeout es una propuesta operativa, no una garantía de que todos los arranques concluyan en tres minutos.

Con la exposición HTTP ya resuelta y APP_BASE_URL definido para ese destino, comprobar / y una consulta de lectura a /api/v1/users. Además del código HTTP, verificar que se carga la interfaz y que el navegador consulta el backend correcto. El snapshot no automatiza estas comprobaciones.

2. Recuperar una versión de aplicación

  1. Detener temporalmente nuevas entregas del servicio y seleccionar la última imagen conocida como válida. Confirmar que permanece en el registro.
  2. Revisar si los cambios de esquema/datos de esa versión permiten volver a la anterior. ddl-auto=update no ofrece migraciones inversas.
  3. Crear un revert o una modificación revisada en el repositorio de manifiestos que fije la imagen elegida. Conservar el commit resultante como MANIFEST_COMMIT.
  4. Aplicar ese commit exacto mediante un job de mantenimiento autorizado. Un commit en el repositorio de manifiestos no dispara un pipeline propio.
  5. Esperar el rollout, probar la ruta de lectura y registrar la causa y la versión recuperada.

Ejemplo del núcleo del job, después de disponer de CD_PROJECT_PATH, KUBE_CONTEXT y un SHA revisado:

test -n "$MANIFEST_COMMIT"
git clone --quiet "$CD_PROJECT_PATH" rollback-manifests
git -C rollback-manifests checkout --detach "$MANIFEST_COMMIT"
kubectl --context "$KUBE_CONTEXT" -n app apply -f rollback-manifests/

Utilizar un directorio de trabajo nuevo por job y variables secretas protegidas. Completar el ejemplo con las comprobaciones del primer runbook. Reejecutar el pipeline completo de la aplicación puede volver a escribir la imagen del commit de esa aplicación, deshaciendo la recuperación elegida; no confundir esa acción con aplicar el commit de manifiestos.

Un rollout undo de emergencia cambia el clúster sin modificar Git. Si se usa, reconciliar después el repositorio de manifiestos y comprobar la imagen efectiva para no dejar una recuperación que el siguiente pipeline sobrescriba.

3. Comprobar acceso al registro

kubectl --context "$KUBE_CONTEXT" -n app get secret registry   -o jsonpath='{.type}{"\n"}'
kubectl --context "$KUBE_CONTEXT" -n app describe deployment rest
kubectl --context "$KUBE_CONTEXT" -n app get events --sort-by=.lastTimestamp

El Secret registry es un prerrequisito externo del snapshot. Si falta, prepararlo mediante el procedimiento de credenciales del entorno con un token de lectura del registro; no usar la contraseña efímera de un job como secreto permanente del clúster. Comprobar también que la ruta y la etiqueta existen. Evitar publicar el contenido de .dockerconfigjson en logs o incidencias.

Bootstrap propuesto del Secret de registro

En un job manual de mantenimiento autorizado, guardar un dockerconfigjson válido en una variable CI tipo File llamada REGISTRY_AUTH_FILE. La credencial debe poder leer las imágenes de ambos proyectos, porque rest y web utilizan el mismo Secret. Este procedimiento complementa el snapshot y no forma parte del pipeline original.

test -s "$REGISTRY_AUTH_FILE"
kubectl --context "$KUBE_CONTEXT" -n app create secret generic registry \
  --type=kubernetes.io/dockerconfigjson \
  --from-file=.dockerconfigjson="$REGISTRY_AUTH_FILE" \
  --dry-run=client -o yaml |
  kubectl --context "$KUBE_CONTEXT" -n app apply -f -

Ejecutar después de crear el namespace, con las herramientas y el contexto disponibles. Mantener el archivo fuera de Git, artefactos y trazas de depuración. La salida del primer comando se envía directamente al segundo; no añadir un volcado del Secret al log. Al rotar la credencial, comprobar que los nuevos pods pueden descargar ambas imágenes.

4. Rotar credenciales de base de datos

Identificar qué estado administra la cuenta de BD y qué capa genera el Secret rest. Preparar la rotación en el proveedor de base de datos y aplicar el cambio coherente en database y platform, respetando sus dependencias. Reiniciar de forma controlada los consumidores que leen el Secret como variables de entorno, y comprobar una consulta de lectura.

Con una sola cuenta de aplicación, la modificación de contraseña puede interrumpir conexiones durante la transición. El repositorio no implementa rotación de doble credencial ni reload automático; acordar el procedimiento y la ventana de cambio. Restaurar un valor antiguo sólo si también sigue siendo válido en la BD.

5. Recuperar un pipeline de infraestructura interrumpido

Comprobar primero la última operación, el nombre de estado, los jobs todavía activos y la presencia de recursos. Comparar el plan guardado con el estado actual y generar otro plan si el anterior ha caducado o quedó obsoleto. Reanudar desde la primera capa pendiente sólo después de verificar las salidas de las anteriores.

El job force_unlock_gcp_database_private_service_access retira una asociación del estado; no desbloquea un lock. No debe ejecutarse sólo para desbloquear visualmente un pipeline. Estado y retirada describen sus efectos y límites.

6. Cambiar el namespace del grupo

Inventariar las referencias antes del cambio: includes, URL Git de manifiestos, registros, contextos de agentes y ci_access, backend de estado y enlaces de documentación. Mantener una lista de los IDs numéricos para distinguir un cambio de ruta de una copia a nuevos proyectos.

Después del cambio, validar los includes y permisos, construir una imagen de prueba, comprobar un contexto y actualizar el manifiesto en una entrega controlada. Actualizar source-manifest.json cuando se revise la nueva ubicación. Este sitio utiliza la URL de Pages proporcionada por CI para evitar fijar la ruta histórica del grupo como URL de publicación.

Fuentes y trazabilidad