jesus manrique

Posted on May 20 • Originally published at guayoyo.tech

De Cero a Kubernetes Parte 3: ArgoCD, GitOps y App-of-Apps

#kubernetes #terraform #devops #tutorial

Serie: De Cero a Kubernetes — Parte 1 · Parte 2 · Parte 3 · Parte 4 · Parte 5

Hasta ahora construimos la plataforma con Terraform. Pero Terraform no es un CD pipeline — correr terraform apply cada vez que cambia una imagen de contenedor es una tortura. Aquí entra ArgoCD.

ArgoCD implementa GitOps: el estado deseado de tu cluster vive en un repositorio de git. ArgoCD monitorea ese repo y garantiza que el cluster refleje exactamente lo que está commiteado. Si alguien hace kubectl edit manual, ArgoCD lo revierte. Si un deploy falla, ArgoCD te dice exactamente qué recurso está roto y por qué.

GitOps en 30 segundos

┌──────────┐   git push    ┌──────────┐
│  GitHub   │◄──────────────│  Tú       │
│  (repo)   │               └──────────┘
└────┬─────┘
     │ ArgoCD lee el repo cada 3 min
     ▼
┌──────────┐    sync    ┌──────────────────┐
│ ArgoCD   │───────────►│  k8s cluster      │
│ (en el   │◄───────────│  (tus apps)       │
│ cluster) │   status   └──────────────────┘
     │
     ▼  (UI opcional en argocd.tudominio.com)
┌──────────────┐
│  🌳 Árbol de │ → ves el diff, health, logs
│     apps      │ → sync manual o automático
│               │ → rollback con revertir commit
└──────────────┘

Las tres propiedades que diferencian GitOps de un script de deploy:

Reconciliation loop: Cada 3 minutos ArgoCD compara el cluster contra git. Si hay drift, lo corrige.
Self-healing: Alguien borró un Deployment por error → ArgoCD lo recrea.
Auditabilidad: Cada cambio al cluster tiene un commit asociado. Sabes quién, qué, cuándo y por qué.

Paso 1: Instalar ArgoCD con Terraform

resource "helm_release" "argocd" {
  name       = "argocd"
  namespace  = kubernetes_namespace.argocd.metadata[0].name
  repository = "https://argoproj.github.io/argo-helm"
  chart      = "argo-cd"
  version    = "7.6.7"

  set {
    name  = "server.service.type"
    value = "ClusterIP"  # Lo exponemos vía ingress, no NodePort
  }

  set {
    name  = "server.ingress.enabled"
    value = "true"
  }

  set {
    name  = "server.ingress.hosts[0]"
    value = "argocd.tudominio.com"
  }

  set {
    name  = "server.ingress.annotations.nginx\\.ingress\\.kubernetes\\.io/ssl-redirect"
    value = "true"
  }

  set {
    name  = "server.ingress.annotations.cert-manager\\.io/cluster-issuer"
    value = "letsencrypt-production"
  }

  set {
    name  = "server.ingress.tls[0].hosts[0]"
    value = "argocd.tudominio.com"
  }

  set {
    name  = "server.ingress.tls[0].secretName"
    value = "argocd-tls"
  }

  # Desactivamos TLS interno ya que el ingress maneja TLS externo
  set {
    name  = "server.extraArgs[0]"
    value = "--insecure"
  }

  depends_on = [helm_release.cert_manager]
}

Accedes a la UI en https://argocd.tudominio.com. La contraseña inicial de admin:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

Paso 2: La contraseña admin como código (buena práctica)

No queremos passwords generados aleatoriamente en cada terraform apply. Usamos bcrypt:

# Generas el hash una vez:
# htpasswd -nbBC 10 "" "tu-password-segura" | tr -d ':\n'

resource "kubernetes_secret" "argocd_admin_password" {
  metadata {
    name      = "argocd-secret"
    namespace = "argocd"
  }

  data = {
    "admin.password"   = "$2a$10$..." # hash bcrypt
    "admin.passwordMtime" = "2026-05-20T00:00:00Z"
  }
}

Paso 3: Estructura del repositorio GitOps

Creamos un repo separado (o un directorio en el monorepo) con esta estructura:

gitops/
├── apps/
│   ├── backend/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── ingress.yaml
│   │   ├── configmap.yaml
│   │   └── kustomization.yaml
│   ├── frontend-app1/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── ingress.yaml
│   │   ├── configmap.yaml
│   │   └── kustomization.yaml
│   ├── frontend-app2/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── ingress.yaml
│   │   ├── configmap.yaml
│   │   └── kustomization.yaml
│   └── database/
│       ├── postgresql-cluster.yaml
│       └── kustomization.yaml
└── clusters/
    └── production/
        └── app-of-apps.yaml    ← LA LLAVE MAESTRA

Paso 4: App-of-Apps — el patrón que lo escala todo

En vez de crear 15 Applications manualmente en ArgoCD, creas una Application raíz que apunta a apps/. Cada subdirectorio se convierte automáticamente en una Application. Añadir una app nueva es crear una carpeta. Sin tocar ArgoCD.

clusters/production/app-of-apps.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-of-apps
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://github.com/tu-org/gitops-repo
    targetRevision: main
    path: apps
    directory:
      recurse: true
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true      # borra recursos que eliminaste del repo
      selfHeal: true   # revierte cambios manuales en el cluster
    syncOptions:
      - CreateNamespace=true

Las 3 banderas que importan:

prune: true → Si borras apps/backend/deployment.yaml del repo, ArgoCD borra el Deployment del cluster. Sin esto, el recurso queda huérfano para siempre.
selfHeal: true → Si alguien hace kubectl edit deployment backend y cambia réplicas de 2 a 5, ArgoCD lo revierte a 2 en el siguiente reconciliation (≤3 min).
CreateNamespace=true → Si el namespace no existe, lo crea. Evita el error de "namespace not found".

Paso 5: Registrar el repo en ArgoCD

ArgoCD necesita acceso de lectura al repo. Usamos un token de GitHub con scope repo:

kubectl create secret generic github-repo-creds \
  -n argocd \
  --from-literal=url=https://github.com/tu-org/gitops-repo \
  --from-literal=username=gitops-bot \
  --from-literal=password=ghp_tuTokenDeGitHub \
  --from-literal=type=git \
  --dry-run=client -o yaml | kubectl apply -f -

Y etiquetamos el secret para que ArgoCD lo use:

kubectl label secret github-repo-creds -n argocd \
  argocd.argoproj.io/secret-type=repository

Paso 6: Crear la Application raíz

La app-of-apps se crea una sola vez. Puedes hacerlo con Terraform o directamente:

resource "kubernetes_manifest" "app_of_apps" {
  manifest = {
    apiVersion = "argoproj.io/v1alpha1"
    kind       = "Application"
    metadata = {
      name      = "app-of-apps"
      namespace = "argocd"
    }
    spec = {
      project = "default"
      source = {
        repoURL        = "https://github.com/tu-org/gitops-repo"
        targetRevision = "main"
        path           = "apps"
        directory = {
          recurse = true
        }
      }
      destination = {
        server    = "https://kubernetes.default.svc"
        namespace = "argocd"
      }
      syncPolicy = {
        automated = {
          prune    = true
          selfHeal = true
        }
        syncOptions = ["CreateNamespace=true"]
      }
    }
  }
}

Paso 7: Ver el árbol de apps

A los pocos segundos de aplicar, la UI de ArgoCD muestra:

🌳 app-of-apps
  ├── 🟢 backend        (Healthy · Synced)
  ├── 🟢 frontend-app1  (Healthy · Synced)
  ├── 🟢 frontend-app2  (Healthy · Synced)
  └── 🟢 database       (Healthy · Synced)

Los círculos verdes indican que el recurso está Healthy (pods corriendo, probes pasando) y Synced (el cluster coincide con git).

Si algo falla:

Amarillo (Progressing): Pods arrancando, aún no pasan health checks.
Rojo (Degraded): CrashLoopBackOff, ImagePullBackOff, probes fallando.
OutOfSync: Alguien cambió algo manualmente → ArgoCD lo marcará para corrección o lo corregirá solo (selfHeal).

Paso 8: ArgoCD CLI — para los que prefieren terminal

# Instalar
brew install argocd

# Login
argocd login argocd.tudominio.com --username admin --password ...

# Listar apps
argocd app list

# Ver diff entre git y cluster
argocd app diff backend

# Sincronizar manualmente (si no usas auto-sync)
argocd app sync backend

# Rollback (revertir el commit en git es mejor)
argocd app rollback backend

# Ver logs de un pod específico sin kubectl
argocd app logs backend --tail=50

También hay una extensión de VS Code que muestra el estado de ArgoCD en el editor. Muy útil cuando estás codeando y quieres ver si el deploy pasó sin cambiar de ventana.

El flujo de trabajo diario con GitOps

1. Cambias algo en el código de la app (main.py, App.tsx, etc.)
2. Build de Docker → nueva imagen (ghcr.io/tu-org/backend:v1.2.3)
3. Actualizas gitops/apps/backend/deployment.yaml:
      image: ghcr.io/tu-org/backend:v1.2.3
4. git add && git commit && git push
5. ArgoCD detecta el cambio → sync automático
6. Si algo falla → rollback: git revert && git push

Todo el historial de deploys es el historial de git. Todos los rollbacks son git revert. No hay "procedimiento de rollback" — es el mismo procedimiento que cualquier cambio de código.

Qué aprendiste en esta parte

GitOps como filosofía: git es la fuente única de verdad del cluster
ArgoCD instalado con Terraform, expuesto vía ingress con TLS
El patrón app-of-apps: una Application raíz que gestiona N aplicaciones
syncPolicy: prune + selfHeal + auto-sync para deployments automáticos
Cómo ArgoCD detecta drift y lo corrige sin intervención humana
ArgoCD CLI y UI para debugging
El flujo completo: git push → ArgoCD sync → deploy en segundos

En la Parte 4, desplegaremos la base de datos PostgreSQL y el backend API. Con código real, health checks, migraciones automáticas y secretos gestionados correctamente.

En Guayoyo Tech implementamos GitOps en equipos que aún están haciendo deploys manuales. ArgoCD, Flux, pipelines CI/CD — te ayudamos a pasar de "funciona en mi máquina" a "está en producción y se corrige solo". Habla con nosotros gratis 15 minutos y te contamos cómo.

DEV Community