Saltar a contenido

Primer despliegue

Esta guía organiza la preparación y el orden de ejecución. Está pensada para una cuenta y un grupo cuyo propietario haya decidido reproducir el laboratorio. Los ejemplos de identidad del proyecto sirven para relacionar las piezas; deben adaptarse al namespace y a los recursos propios. La infraestructura actual debe evaluarse con los hallazgos conocidos antes de su primer plan.

1. Elegir proveedor y alcance

Decisión AWS Google Cloud
Selector del pipeline IaC CLOUD_PROVIDER=aws CLOUD_PROVIDER=gcp
Selector del pipeline de aplicación DEPLOY_TARGET=eks DEPLOY_TARGET=gke
Kubernetes / base de datos EKS / RDS MySQL GKE / Cloud SQL MySQL
Región declarada por defecto eu-west-1 europe-west1
Exposición web versionada Ingress ALB y referencia ACM Requiere adaptación: el Ingress existente es de AWS

Elige también un entorno de estado y una política de nombres antes de crear recursos. ENVIRONMENT no parametriza por sí solo todos los nombres cloud ni las etiquetas. Si se quiere separar desarrollo y producción, hay que revisar esa separación en estado e identidad de recursos.

Seleccionar la acción de forma explícita

El fichero IaC examinado tiene PIPELINE_ACTION=destroy y ENVIRONMENT=pro como valores iniciales. Para una primera creación selecciona explícitamente PIPELINE_ACTION=create, el proveedor y el entorno revisado. No ejecutes el pipeline aceptando sus valores sin comprobarlos.

2. Preparar repositorios y permisos

  1. Conserva las responsabilidades del inventario de repositorios: dos aplicaciones, dos repositorios de manifiestos, plantillas CI e IaC. Este repositorio de documentación se añade como proyecto independiente.
  2. Si copias o renombras el grupo, actualiza include.project, CD_PROJECT_PATH, contextos de agente, autorizaciones ci_access/user_access y referencias de imágenes. Cambiar sólo el nombre visible no cambia esas rutas.
  3. Revisa la protección de main y el acceso de los operadores. Los jobs de despliegue de aplicación sólo existen para main protegida; los apply de infraestructura se limitan a main y son manuales.
  4. Configura runners capaces de ejecutar las imágenes de CI. La construcción usa Docker-in-Docker y necesita una configuración compatible. Un runner que compile documentación no necesariamente puede construir las imágenes de aplicación.
  5. Configura un mecanismo de autenticación que pueda clonar y hacer push a los repositorios de manifiestos. El nombre CD_DEPLOY_TOKEN no prueba que se trate de un GitLab Deploy Token ni que tenga permiso de escritura. Consulta variables y despliegue.

3. Preparar credenciales y acceso a las APIs

Configuración Uso Comprobación previa
Credenciales AWS o identidad admitida por el provider Crear red, EKS, IAM y RDS Cuenta, permisos y región previstos
GCP_PROJECT_ID y GCP_SERVICE_ACCOUNT_KEY cuando se usa la ruta JSON del pipeline Identificar proyecto y autenticar Google Facturación, permisos y APIs necesarias habilitadas
TF_STATE_TOKEN Leer outputs de otras raíces Acceso al proyecto que aloja los estados
REST_DB_USER y REST_DB_PASSWORD Crear usuario de base y secreto rest Mismos valores para las raíces que los consumen
AGENT_TOKEN o GKE_AGENT_TOKEN, y KAS_ADDRESS Conectar GitLab Agent Token del agente correspondiente al destino
CD_DEPLOY_USER y CD_DEPLOY_TOKEN Actualizar el repo de manifiestos Lectura y escritura en el proyecto correcto

Usa variables de CI con protección y visibilidad coherentes con el flujo. El pipeline escribe el contenido de GCP_SERVICE_ACCOUNT_KEY como JSON; no trata esa variable como una ruta a un fichero GitLab. No pegues secretos en commits, ejemplos de documentación o logs. El catálogo de variables diferencia variables de entrada, defaults y credenciales.

El código no aprovisiona todo el bootstrap de las cuentas cloud. La activación de APIs GCP, los roles iniciales y el acceso de red del runner deben existir antes de llamar a los providers. Los planes y los estados pueden contener valores sensibles: restringe su acceso igual que el de las credenciales que representan.

4. Registrar los agentes antes de instalar la plataforma

La configuración de agentes vive en .gitlab/agents/eks-agent/config.yaml y .gitlab/agents/gke-agent/config.yaml del proyecto IaC. Registra el agente correspondiente en GitLab y prepara su token antes de llegar a la raíz platform. Esa raíz instala el chart Helm con el token; después el agente puede aparecer conectado.

Revisa las autorizaciones de grupo y los permisos efectivos del ServiceAccount. Los ficheros examinados autorizan el grupo entero y user_access usa la identidad del agente. El acceso a clústeres explica este alcance y los contextos que reciben los jobs.

5. Crear infraestructura por capas

En el proyecto IaC, selecciona main, PIPELINE_ACTION=create, proveedor y entorno explícitos. El pipeline sigue este orden:

Raíz Revisar el plan antes del apply manual Resultado necesario para continuar
network CIDR, subredes, salida a Internet y nombres Estado de red y sus outputs
kubernetes Versión, endpoint, nodos, identidad y coste Clúster operativo y estado de Kubernetes
database Base privada, credenciales, backups y protección de borrado Endpoint privado y estado de datos
platform Namespace, secretos, agentes y controladores Namespace app, secreto rest, agente conectado

Los planes guardados se aplican en jobs posteriores y sus artifacts caducan. Si la configuración o el estado cambian antes de aprobar, vuelve a generar el plan; no reutilices uno que ya no represente la intención. La guía del pipeline detalla validaciones, dependencias y exclusión mutua.

6. Completar el contrato de la aplicación

Antes de permitir el deploy comprueba:

  • El secreto de descarga registry existe en app con acceso al Registry adecuado. Los Deployments lo referencian, pero no está creado por los módulos revisados.
  • El secreto rest contiene las claves esperadas por el backend y alcanza la base correcta.
  • Las referencias de imagen usan el grupo destino y las imágenes se pueden descargar.
  • El Ingress tiene una clase compatible con el proveedor. En AWS sustituye la identidad del certificado y el host por valores propios; en GKE prepara una configuración específica antes de considerar publicado el servicio.
  • DEPLOY_TARGET coincide con el proveedor preparado. Los dos repos de aplicación revisados apuntan a gke, aunque la plantilla compartida declara eks por defecto.

Para un primer despliegue funcional conviene entregar el backend antes que el frontend y validar su dependencia de MySQL. Esta es una secuencia operativa recomendada; no existe un pipeline multiproyecto que imponga ese orden automáticamente.

7. Ejecutar y verificar la entrega

Un cambio o ejecución sobre main protegida puede promocionar y desplegar automáticamente. Revisa la imagen publicada, el commit en el repositorio de manifiestos y el contexto indicado en los logs del job. Después comprueba el resultado desde la vista Kubernetes o un entorno autorizado con kubeconfig:

kubectl --context "$KUBE_CONTEXT" -n app get deployments,pods,services,ingress
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 events --sort-by=.lastTimestamp

KUBE_CONTEXT debe apuntar al agente elegido. Estos comandos son verificaciones posteriores; no están todos incluidos en el job actual. Completa una comprobación funcional de consulta y modificación de usuarios y revisa errores de conexión antes de dar la entrega por terminada. Consulta observabilidad y troubleshooting.

8. Preparar mantenimiento y retirada

Conserva las referencias de imagen necesarias para rollback, decide la retención de copias de datos y evita mantener recursos de laboratorio sin una revisión de coste. El runbook de retirada cubre el orden inverso y el job especial de Private Service Access. Un rollback de imagen y una restauración de datos son operaciones distintas.

Fuentes