ArgoCD: GitOps en tu cluster de Kubernetes paso a paso

Actualizado en marzo 2026: Este artículo usa ArgoCD v3.3.x (la última versión estable) con la instalación por manifiestos oficiales.

¿Qué es ArgoCD?

Si seguiste la serie de posts de Kubernetes (montar el cluster, recursos, HPA, Prometheus + Grafana), ya sabes desplegar y monitorear apps. Pero hay un problema: cada vez que cambias algo, tienes que correr kubectl apply manualmente. ¿Y si se te olvida? ¿Y si alguien aplica un cambio directo en el cluster que no está en ningún repo?

ArgoCD resuelve exactamente esto. Es una herramienta de Continuous Delivery declarativa para Kubernetes que implementa el patrón GitOps: tu repositorio de Git es la fuente de verdad del estado de tu cluster. ArgoCD vigila el repo, compara lo que hay en Git contra lo que hay en el cluster, y si hay diferencias, las sincroniza automáticamente.

Piensa en ArgoCD como un vigilante incansable: está escuchando tu repo 24/7. Cuando alguien hace merge de un PR con nuevos manifiestos, ArgoCD lo detecta en segundos y actualiza el cluster. Si alguien modifica algo directamente en el cluster con kubectl, ArgoCD lo revierte al estado que dice Git.

¿Por qué GitOps?

Antes de instalar nada, entendamos por qué esto importa:

• Auditoría completa: cada cambio en el cluster tiene un commit con autor, fecha y descripción. git log es tu historial de deployments.
• Rollback instantáneo: si algo se rompe, git revert y ArgoCD vuelve al estado anterior.
• Cero acceso directo al cluster: los desarrolladores no necesitan kubectl. Hacen PR, se revisa, se aprueba, ArgoCD despliega.
• Consistencia garantizada: el cluster siempre refleja lo que hay en el repo. No hay “drift” ni cambios fantasma.
• Disaster recovery: si pierdes el cluster, solo necesitas reinstalar ArgoCD y apuntarlo al repo. Reconstruye todo solo.

Pre-requisitos

Para este tutorial necesitas tener lo que instalamos en el post de Kubernetes:

Si seguiste el post de Kubernetes, ya tienes todo esto instalado. Solo verifica que tu cluster esté corriendo:

macOS (con OrbStack)

# OrbStack ya debería estar corriendo (icono en la barra de menú)
kind get clusters
# Si no tienes cluster:
kind create cluster --name mi-cluster

Windows (con Docker Desktop + WSL2)

Asegúrate de que Docker Desktop esté corriendo con el backend de WSL2. Abre tu terminal WSL2:

# Verificar que Docker funciona
docker info

# Verificar el cluster
kind get clusters
# Si no lo tienes:
kind create cluster --name mi-cluster

Linux

# Verificar que Docker está corriendo
sudo systemctl status docker

# Verificar el cluster
kind get clusters
# Si no lo tienes:
kind create cluster --name mi-cluster

Paso 1: Instalar ArgoCD en el cluster

La instalación es directa — un namespace y los manifiestos oficiales:

# Crear el namespace
kubectl create namespace argocd

# Instalar ArgoCD (versión estable)
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Esperar a que todo esté listo
kubectl wait --for=condition=available --timeout=120s deployment/argocd-server -n argocd

Verifica que todos los pods estén corriendo:

kubectl get pods -n argocd

NAME                                  READY   STATUS    RESTARTS   AGE
argocd-application-controller-0       1/1     Running   0          60s
argocd-dex-server-xxx                 1/1     Running   0          60s
argocd-notifications-controller-xxx   1/1     Running   0          60s
argocd-redis-xxx                      1/1     Running   0          60s
argocd-repo-server-xxx                1/1     Running   0          60s
argocd-server-xxx                     1/1     Running   0          60s

Paso 2: Instalar el CLI de ArgoCD

El CLI te permite interactuar con ArgoCD desde tu terminal:

macOS

brew install argocd

Linux

curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x argocd
sudo mv argocd /usr/local/bin/

Windows

# Con Scoop
scoop install argocd

# O con Chocolatey
choco install argocd-cli

Verifica la instalación:

argocd version --client

Paso 3: Acceder a la UI de ArgoCD

ArgoCD tiene una interfaz web bastante buena. Para acceder desde tu máquina local:

# Port-forward al servidor de ArgoCD
kubectl port-forward svc/argocd-server -n argocd 8080:443

Ahora abre https://localhost:8080 en tu navegador (acepta el certificado auto-firmado).

Obtener la contraseña de admin

# La contraseña inicial se guarda en un secret
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 --decode

El usuario es admin y la contraseña es lo que devolvió el comando anterior.

Login desde el CLI

argocd_pass=$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 --decode)

argocd login localhost:8080 --insecure --username admin --password $argocd_pass

argocd account update-password
kubectl -n argocd delete secret argocd-initial-admin-secret

Paso 4: Preparar el repositorio de manifiestos

Para este ejemplo, vamos a usar un repositorio con la siguiente estructura:

k8s-configs/
├── apps/
│   ├── nginx-demo/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── hpa.yaml

Crea un repositorio en GitHub (por ejemplo k8s-configs) y agrega estos archivos:

apps/nginx-demo/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-demo
  namespace: staging
  labels:
    app: nginx-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx-demo
  template:
    metadata:
      labels:
        app: nginx-demo
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "200m"
              memory: "128Mi"

apps/nginx-demo/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx-demo
  namespace: staging
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 80
  selector:
    app: nginx-demo

apps/nginx-demo/hpa.yaml

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-demo-hpa
  namespace: staging
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-demo
  minReplicas: 2
  maxReplicas: 6
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

No olvides crear el namespace:

kubectl create namespace staging

Paso 5: Crear tu primera Application en ArgoCD

Ahora viene la parte mágica. Vamos a decirle a ArgoCD que vigile nuestro repositorio:

Opción A: Desde el CLI

argocd app create nginx-demo \
  --repo https://github.com/TU_USUARIO/k8s-configs.git \
  --path apps/nginx-demo \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace staging \
  --sync-policy automated \
  --auto-prune \
  --self-heal

Opción B: Con un manifiesto YAML (recomendada)

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: nginx-demo
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/TU_USUARIO/k8s-configs.git
    targetRevision: main
    path: apps/nginx-demo
  destination:
    server: https://kubernetes.default.svc
    namespace: staging
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - Validate=true
      - ServerSideApply=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

kubectl apply -f application.yaml

¿Qué significan esas opciones?

Paso 6: Verificar el despliegue

Si todo salió bien, ArgoCD habrá sincronizado los manifiestos automáticamente:

# Ver el estado de la app
argocd app get nginx-demo

# O desde kubectl
kubectl get all -n staging

En la UI de ArgoCD (https://localhost:8080) deberías ver la app con estado Synced y Healthy.

Probar el self-heal

Vamos a hacer una prueba: cambia algo directamente en el cluster y mira cómo ArgoCD lo revierte:

# Escalar a 5 réplicas manualmente
kubectl scale deployment nginx-demo -n staging --replicas=5

# Espera unos segundos... ArgoCD detecta el drift
kubectl get pods -n staging
# Verás que vuelve a 2 réplicas (lo que dice el Git)

Probar el sync automático

Ahora cambia algo en el repositorio:

1. Edita deployment.yaml y cambia replicas: 2 a replicas: 3.
2. Haz commit y push a main.
3. En ~3 minutos (o menos), ArgoCD detectará el cambio y escalará a 3 réplicas.

# Verificar
kubectl get pods -n staging
# Ahora verás 3 pods

Alternativas a ArgoCD

ArgoCD no es la única opción para GitOps. Acá va una comparación honesta:

ArgoCD vs FluxCD vs otros

¿Cuándo usar cada uno?

Elige ArgoCD si:

• Quieres una UI completa para visualizar el estado de tus deployments.
• Necesitas SSO y RBAC granular out-of-the-box.
• Tu equipo prefiere una herramienta visual y accesible.
• Vas a integrar con Backstage (hay plugin oficial).

Elige FluxCD si:

• Prefieres un enfoque CLI-first y Kubernetes-native puro.
• El consumo de recursos es crítico (FluxCD usa menos RAM).
• Necesitas image automation (actualizar automáticamente el tag de una imagen cuando sale una nueva versión).
• Ya usas el ecosistema de CNCF/AWS para Flux.

Elige Rancher Fleet si:

• Manejas muchos clusters (100+) y necesitas gestión centralizada.
• Ya usas Rancher como tu plataforma de gestión de Kubernetes.

El patrón App of Apps

Cuando tienes más de un par de servicios, gestionar cada Application manualmente se vuelve tedioso. El patrón App of Apps resuelve esto: creas una “app padre” que apunta a un directorio con muchas “apps hijas”.

La app padre:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: production-apps
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/mi-org/k8s-configs.git
    targetRevision: main
    path: apps/production
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Dentro de apps/production/ pones los YAML de cada Application hija. ArgoCD los descubre y gestiona automáticamente. Agregas un servicio nuevo = agregas un YAML al directorio, haces PR, merge, y ArgoCD despliega todo.

Conectando con Backstage

Si seguiste el post anterior de Backstage Series #2, ya tienes un template que genera manifiestos y crea PRs. Ahora puedes cerrar el ciclo:

1. El desarrollador llena un formulario en Backstage → se genera un PR.
2. El equipo revisa y hace merge.
3. ArgoCD detecta el cambio y despliega en el cluster.
4. El desarrollador ve el estado del deployment en la pestaña de Kubernetes de Backstage.

Existe un plugin de ArgoCD para Backstage (@roadiehq/backstage-plugin-argo-cd) que agrega una tarjeta con el estado de sync, health y el historial de deployments directamente en la página de cada servicio.

Resumen

Recursos

• ArgoCD — Documentación oficial
• ArgoCD — Getting Started
• FluxCD — Documentación oficial
• Rancher Fleet
• Plugin de ArgoCD para Backstage
• Post: Kubernetes — Montar tu primer cluster
• Post: Backstage Series #2 — Templates + PRs