GitOps con GitLab y ArgoCD en ANDES DX

Esta página explica la parte GitOps del despliegue con ArgoCD en ANDES DX: qué repositorio observa ArgoCD, qué archivos espera encontrar y cómo el pipeline deja el estado deseado listo para sincronizar.

Para entender el modelo completo de services, pipelines, components, topics y .gitlab-ci.yml, revisa primero Pipelines para ANDES DX. Aquí solo se describe el contrato entre ese pipeline y ArgoCD.

Qué Hace GitOps en este Flujo

En ANDES DX, el repositorio de la aplicación no es el repositorio que ArgoCD sincroniza directamente. El pipeline renderiza manifiestos de Kubernetes usando KCL y los publica en un repositorio GitOps del dominio correspondiente. ArgoCD observa ese repositorio GitOps y aplica en el cluster lo que está declarado ahí.

Esta separación permite que:

el App Repo mantenga código fuente y configuración de CI/CD;
el GitOps Repo mantenga solo manifiestos de Kubernetes renderizados y metadata de despliegue;
ArgoCD tenga un origen de verdad estable, versionado y separado por dominio.

Repositorios GitOps por Dominio

Los manifiestos de aplicaciones se almacenan bajo repositorios del grupo latam-applications/{dominio}. Por ejemplo:

latam-applications/andes
latam-applications/ecargo
latam-applications/test

El dominio no se decide dentro de ArgoCD. Lo resuelve ANDES DX a partir de la configuración del proyecto y del pipeline central. ArgoCD consume el resultado: un repositorio GitOps con manifiestos de Kubernetes y metadata.json.

Estructura que ArgoCD Descubre

Los ApplicationSet de ANDES buscan archivos metadata.json dentro de los repositorios GitOps del dominio. La ruta esperada tiene esta forma:

{producto}/{aplicación}/{ambiente}/metadata.json

Cada carpeta descubierta se convierte en una Application de ArgoCD. La misma carpeta contiene los manifiestos YAML que ArgoCD aplica recursivamente.

latam-applications/ecargo/
└── payment-product/
    └── payment-gateway/
        └── intg/
            ├── metadata.json
            ├── deployment-payment-gateway.yaml
            ├── service-payment-gateway.yaml
            └── hpa-payment-gateway.yaml

Qué Contiene `metadata.json`

El archivo metadata.json es el contrato GitOps que permite al ApplicationSet crear la Application correcta. No es lo mismo que la metadata de aplicación que entrega ANDES DX al pipeline: esa metadata se usa como entrada para generar manifiestos con KCL; metadata.json es una salida más pequeña, pensada para que ArgoCD pueda ubicar y sincronizar la aplicación.

Contiene datos como:

nombre de la aplicación;
producto;
ambiente;
namespace;
cluster destino;
instancia de ArgoCD;
URL del repositorio fuente cuando está disponible.

Con esa información, ArgoCD define el nombre de la Application, el AppProject, el destino y la ruta que debe sincronizar.

Sincronización desde el Pipeline

Después de publicar los manifiestos en el GitOps Repo, el componente deploy/gitops/argo solicita a ArgoCD que sincronice la aplicación. Esta operación no corresponde a un login manual de usuarios; el job usa credenciales técnicas administradas por ANDES.

El flujo interno es:

clonar el repositorio GitOps del dominio;
copiar los manifiestos de Kubernetes generados con KCL y metadata.json en la ruta de la aplicación;
commitear y pushear los cambios si existen;
consultar el estado actual de la Application en ArgoCD;
ejecutar sync cuando hay cambios o cuando la aplicación no está Synced + Healthy;
esperar hasta confirmar el resultado del despliegue.

argocd app sync "${app_id}" \
  --revision "${sync_revision}" \
  --prune \
  --async \
  --grpc-web

El pipeline también realiza refresh y validaciones de estado para reducir falsos negativos por problemas transitorios entre CLI, API y repo-server.

Interpretación del Resultado del Despliegue

En la práctica, el desarrollador no modifica el GitOps Repo manualmente. Para entender qué pasó con un despliegue, parte por los mensajes principales del pipeline:

Manifest generado correctamente. En el job de manifiestos busca mensajes como Generated <n> resources, Generated metadata.json file y Generated files:. Eso indica que KCL pudo generar los manifiestos de Kubernetes y la metadata GitOps.
GitOps actualizado o sin cambios. En el job GitOps busca GitOps: Manifests updated successfully cuando hubo cambios, o GitOps: No changes detected cuando los YAML ya estaban alineados.
Application encontrada en ArgoCD. Si aparece Timeout: Application '<app>' not found, ArgoCD todavía no creó o no encontró la Application desde el ApplicationSet.
Resultado final simple. DEPLOYMENT SUCCESSFUL significa que ArgoCD dejó la app sincronizada. APPLICATION ALREADY ALIGNED significa que no había nada nuevo que aplicar y la app ya estaba alineada.
Si falla. DEPLOYMENT FAILED muestra el estado general (Sync, Health) y, cuando ArgoCD lo informa, el recurso específico con problema. Ahí conviene mirar el recurso marcado como Degraded, OutOfSync o con error de health check.

Siguiente Paso

Si necesitas entender cómo se define el pipeline que genera estos archivos, continúa en Pipelines para ANDES DX.

Qué Hace GitOps en este Flujo​

Repositorios GitOps por Dominio​

Estructura que ArgoCD Descubre​

Qué Contiene metadata.json​

Sincronización desde el Pipeline​

Interpretación del Resultado del Despliegue​

Siguiente Paso​