Verificando autenticación…

Skip to main content

GitOps with GitLab and ArgoCD in ANDES DX

This page explains the GitOps part of ArgoCD deployments in ANDES DX: which repository ArgoCD watches, which files it expects to find, and how the pipeline leaves the desired state ready to synchronize.

To understand the complete model of services, pipelines, components, topics, and .gitlab-ci.yml, review Pipelines for ANDES DX first. This page only describes the contract between that pipeline and ArgoCD.

What GitOps Does in this Flow​

In ANDES DX, the application repository is not the repository that ArgoCD synchronizes directly. The pipeline renders Kubernetes manifests using KCL and publishes them into the GitOps repository for the corresponding domain. ArgoCD watches that GitOps repository and applies in the cluster what is declared there.

This separation allows:

  • the App Repo to keep source code and CI/CD configuration;
  • the GitOps Repo to keep only rendered Kubernetes manifests and deployment metadata;
  • ArgoCD to have a stable, versioned source of truth separated by domain.

GitOps Repositories by Domain​

Application manifests are stored under repositories in the latam-applications/{domain} group. For example:

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

The domain is not decided inside ArgoCD. ANDES DX resolves it from the project configuration and the central pipeline. ArgoCD consumes the result: a GitOps repository with Kubernetes manifests and metadata.json.

Structure Discovered by ArgoCD​

ANDES ApplicationSet resources look for metadata.json files inside the domain GitOps repositories. The expected path has this shape:

{product}/{application}/{environment}/metadata.json

Each discovered folder becomes an ArgoCD Application. The same folder contains the YAML manifests that ArgoCD applies recursively.

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

What metadata.json Contains​

The metadata.json file is the GitOps contract that allows the ApplicationSet to create the correct Application. It is not the same as the application metadata that ANDES DX provides to the pipeline: that metadata is used as input to generate manifests with KCL; metadata.json is a smaller output designed so ArgoCD can locate and synchronize the application.

It contains data such as:

  • application name;
  • product;
  • environment;
  • namespace;
  • target cluster;
  • ArgoCD instance name;
  • source repository URL when available.

With that information, ArgoCD defines the Application name, AppProject, destination, and path to synchronize.

Synchronization from the Pipeline​

After publishing the manifests into the GitOps Repo, the deploy/gitops/argo component asks ArgoCD to sync the application. This is not a manual user login flow; the job uses technical credentials managed by ANDES.

The internal flow is:

  1. clone the domain GitOps repository;
  2. copy the Kubernetes manifests generated with KCL and metadata.json into the application path;
  3. commit and push changes when they exist;
  4. query the current Application status in ArgoCD;
  5. run sync when there are changes or when the application is not Synced + Healthy;
  6. wait until the deployment result is confirmed.
argocd app sync "${app_id}" \
  --revision "${sync_revision}" \
  --prune \
  --async \
  --grpc-web

The pipeline also performs refresh and status checks to reduce false negatives caused by transient issues between the CLI, API, and repo-server.

Deployment Result Interpretation​

In practice, developers do not modify the GitOps Repo manually. To understand what happened in a deployment, start with the main pipeline messages:

  1. Manifest generated correctly. In the manifest job, look for messages like Generated <n> resources, Generated metadata.json file, and Generated files:. That means KCL generated the Kubernetes manifests and GitOps metadata.
  2. GitOps updated or unchanged. In the GitOps job, look for GitOps: Manifests updated successfully when there were changes, or GitOps: No changes detected when the YAML files were already aligned.
  3. Application found in ArgoCD. If you see Timeout: Application '<app>' not found, ArgoCD has not created or found the Application from the ApplicationSet yet.
  4. Simple final result. DEPLOYMENT SUCCESSFUL means ArgoCD left the app synchronized. APPLICATION ALREADY ALIGNED means there was nothing new to apply and the app was already aligned.
  5. If it fails. DEPLOYMENT FAILED shows the overall state (Sync, Health) and, when ArgoCD reports it, the specific resource with the problem. Start with the resource marked as Degraded, OutOfSync, or with a health-check error.

Next Step​

If you need to understand how the pipeline that generates these files is defined, continue with Pipelines for ANDES DX.