GitOps: cuando Git manda más que tu jefe

Intro con gancho

El deploy era “rápido”. Un cambio chiquito, según el jefe. Y alguien (a veces tú, a veces el compa) se aventó un kubectl apply -f directo en production. Viernes en la tarde, laptop viejita, ventilador sonando como dron y 4% de batería.

Media hora después: crashloop, alertas, Slack echando humo y el cliente preguntando por WhatsApp si “ya quedó”. Y tú con el clásico “ahorita lo arreglo” mientras buscas qué rayos cambió.

GitOps aparece cuando ya te hartaste de que production sea ese lugar místico donde “nadie tocó nada”… pero algo se movió.

Qué te vas a llevar

• Qué es GitOps en términos de chamba real (no de slide bonito).
• Cómo se ve un setup típico: repo, manifests/Helm, controller (Argo CD o Flux) y workflow con pull request.
• Un paso a paso para montar GitOps en Kubernetes con Argo CD.
• Cómo manejar secretos, ambientes (dev/stage/prod) y rollbacks sin entrar en pánico.
• Errores comunes de la primera semana (y cómo salir sin quemarte).

Por qué GitOps pega en la vida real

Cuando un equipo crece de 2 a 8 personas, o hay rotación, lo manual se vuelve ruleta:

• “¿Qué versión está en prod?” Alguien jura que es v1.8.3, pero el pod trae otra etiqueta.
• “¿Quién cambió eso?” No hay auditoría útil; puro screenshot y “yo no fui”.
• “Revertimos” Y el rollback depende de memoria, café y suerte.

GitOps es una decisión práctica: Git como fuente de verdad. El cluster no es “la verdad”; el cluster es el reflejo de lo que está en Git. Si el runtime se desvía (drift), el sistema lo corrige o mínimo lo grita.

Tradeoff neta: GitOps te da control y trazabilidad, pero te cobra disciplina. Si tu repo es un basurero, GitOps solo automatiza el basurero.

Paso a paso: GitOps con Kubernetes usando Argo CD

Asumo esto:

• Ya tienes un cluster Kubernetes (minikube, kind, EKS/GKE/AKS, o el corporativo).
• Tu kubectl apunta bien.
• Tienes un repo en GitHub/GitLab (puede ser privado).

1) Decide tu modelo: mono-repo vs multi-repo

Esto suena filosófico… hasta que se te atraviesa un deadline.

Opción A: Mono-repo (recomendado para arrancar)

• Un repo para apps y/o infra de Kubernetes.
• Más fácil de entender y operar.
• Contras: si metes todo sin orden, se vuelve pesado.

Opción B: Multi-repo (más “enterprise”)

• Repo por app y un repo de “environments” que arma el rompecabezas.
• Pro: separas responsabilidades.
• Contras: más moving parts, onboarding más rudo.

Si vas empezando (o traes talacha acumulada), vete por mono-repo con estructura clara.

Ejemplo simple:

repo-gitops/
  apps/
    mi-api/
      base/
      overlays/
        dev/
        prod/
  clusters/
    dev/
    prod/

2) Define tu desired state (manifests, Helm o Kustomize)

Tres caminos típicos:

• YAML “a pelo”: arrancas rápido, pero se ensucia con el tiempo.
• Helm: bien para parametrizar; aguas con valores por ambiente.
• Kustomize: overlays por ambiente sin templating. Muy GitOps-friendly.

Ejemplo mínimo con Kustomize:

apps/mi-api/base/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mi-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mi-api
  template:
    metadata:
      labels:
        app: mi-api
    spec:
      containers:
        - name: mi-api
          image: ghcr.io/tu-org/mi-api:1.0.0
          ports:
            - containerPort: 8080

apps/mi-api/base/kustomization.yaml

resources:
  - deployment.yaml

apps/mi-api/overlays/prod/kustomization.yaml

resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: mi-api
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 4

Decisión con filo: si tu equipo vive apagando fuegos por “en mi máquina sí” entre dev/prod, overlays de Kustomize te ayudan a dejar claro qué cambia y por qué.

3) Instala Argo CD en tu cluster

Instalación estándar (namespace argocd):

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

En clusters corporativos a veces te bloquean LoadBalancer o el Ingress trae políticas raras. No es Argo “fallando”, es la red y sus permisos.

Acceso local:

kubectl -n argocd port-forward svc/argocd-server 8080:443

Contraseña inicial:

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

Entra a https://localhost:8080 con usuario admin.

4) Conecta tu repo (la parte donde el permiso te humilla)

Si tu repo es privado, Argo necesita credenciales.

• GitHub: token con permisos mínimos (read-only al repo).
• GitLab: token equivalente.

Regla de oro: usa un “bot user”/token de plataforma, no el de tu cuenta personal. El día que te cambien el SSO, te corran o cambies de jale, production no debería irse al piso por eso.

5) Crea una Application en Argo CD

Se puede por UI o por YAML. En YAML se versiona mejor y se revisa en PR.

Ejemplo apuntando a prod:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: mi-api-prod
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/tu-org/repo-gitops.git
    targetRevision: main
    path: apps/mi-api/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: mi-api
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Aplica:

kubectl apply -f app-mi-api-prod.yaml

Aquí ya se siente GitOps en el workflow:

• Cambias image: ...:1.0.1 en Git
• Abres pull request
• Se aprueba
• Merge a main
• Argo detecta drift y sincroniza

6) Define tu workflow de cambios (PR o caos)

Si permites cambios fuera de Git, GitOps se vuelve “Git de adorno”.

Flujo recomendado:

1. Dev cambia app y CI genera imagen.
2. CI actualiza el manifest (o abre PR que actualiza el tag).
3. PR requiere review (mínimo 1 aprobador).
4. Merge.
5. Argo sincroniza.

Tip práctico para tags:

• Usa tags inmutables (1.0.1 o SHA), no latest.
• Si quieres automatizar updates: Argo CD tiene Image Updater; Flux tiene Image Automation.

7) Rollback sin drama

Si el deploy salió mal y tu jefe pide “déjalo como estaba” en corto:

• Revierte el commit (o haz git revert).
• Merge.
• Argo regresa el cluster al estado anterior.

Lo valioso no es “Argo hace rollback”. Lo valioso es que el rollback queda auditado. Puedes decir: “volvimos al commit abc123 por un bug de memoria”. Y ahí se queda, con fecha y responsables.

Screenshots sugeridos

• Argo CD UI: vista de la Application (árbol de recursos y estado “Synced/Healthy”).
• Diff de Argo CD mostrando drift (qué cambió vs Git).
• PR en GitHub/GitLab donde se actualiza el tag de imagen.
• Historial de Syncs y el commit asociado.

Errores comunes + cómo salir sin romper algo

1) “Se sincroniza… pero se desincroniza sola”

Causa típica: alguien sigue aplicando YAML a mano en el cluster (o un job externo modifica recursos).

Qué haces:

• Cultura: “si no está en Git, no existe”.
• Permisos: no todos deberían tener cluster-admin.
• Habilita selfHeal: true y rastrea quién genera el drift.

2) “Argo no puede jalar mi repo privado”

Causa: token sin permisos, repoURL mal, o bloqueos de red/egress.

Qué haces:

• Confirma permisos read-only.
• Si hay proxy/VPN corporativo, revisa egress desde el cluster.
• Maneja credenciales por secret y rota tokens.

3) “Me volé media app con prune”

Causa: prune: true borra recursos que ya no están declarados en Git. Si moviste archivos o cambiaste path, Argo entiende “ya no existen”.

Qué haces:

• Al principio, usa sync manual mientras ordenas estructura.
• Cambios grandes en dos pasos: primero creas/duplicas, luego borras.
• Valida que el path sea el correcto antes de activar automations agresivas.

4) “Secretos en GitOps: ¿los commiteo o qué?”

Causa: la tentación de subir secretos “porque es más fácil”. Luego alguien clona el repo en una compu personal, se filtra, y te compras un incidente.

Qué haces (práctico):

• External Secrets Operator (AWS/GCP/Azure Secret Manager, Vault, etc.).
• O Sealed Secrets (cifras para que solo el cluster pueda descifrar).
• Si estás arrancando sin presupuesto: mínimo Sealed Secrets + controles de acceso al repo.

5) “Dev y prod se pisan”

Causa: no separar overlays/values, o usar el mismo namespace/cluster para todo.

Qué haces:

• Overlays por ambiente (Kustomize) o values separados (Helm).
• Namespaces distintos.
• Ideal: clusters distintos si el negocio lo amerita. Sí cuesta. Un incidente en production también.

Checklist final (para saber si tu GitOps está decente)

• Git es la fuente de verdad: nada de cambios “a mano” en production.
• PRs con review (aunque sea 1 persona) antes de tocar main.
• Tags inmutables para imágenes (no latest).
• Argo/Flux con permisos mínimos y credenciales que no dependen de tu cuenta.
• Ambientes separados (al menos overlays/namespaces).
• Secretos fuera del repo en claro (Sealed Secrets / External Secrets).
• Rollback vía Git (revert) y sabes cuánto tarda en reflejarse.
• Si alguien pregunta “¿qué está corriendo en prod?”, respondes con un commit.

FAQ

1) ¿GitOps es lo mismo que CI/CD?

No. CI/CD construye, prueba y entrega artefactos. GitOps es el modelo de operación donde Git define el estado y un controller reconcilia Kubernetes para cumplirlo.

2) ¿Necesito Kubernetes para hacer GitOps?

El concepto aplica a más cosas, pero donde más brilla es en Kubernetes: el reconciliador (Argo/Flux) vive cómodo ahí y el estado deseado se describe bien.

3) ¿Argo CD o Flux?

• Argo CD: UI muy usable, onboarding fácil, buena visibilidad.
• Flux: más Git-first, fuerte en automatizaciones (image updates), vibra más de plataforma.

Si tu equipo es mixto (devs + ops) y necesitas que la banda lo entienda rápido, Argo suele ganar por la UI.

4) ¿Qué pasa si Git dice una cosa pero el cluster no puede aplicarla?

El controller intenta sincronizar y marca la app como OutOfSync o Degraded. Y eso es justo lo que quieres: enterarte. Lo peligroso es que “se aplicó a medias” y nadie lo vio.

5) ¿Cómo arranco GitOps sin reventar mi prod actual?

Empieza con un servicio no crítico o un staging. Importa el estado actual a manifests, deja Argo en modo manual primero, y cuando veas que no hay drift raro, prendes sync automático.

Siguiente episodio

Ya que Git manda, toca hablar de lo inevitable: observabilidad en cloud-native. Porque el día que algo falle, necesitas ver qué pasó sin rezarle al kubectl describe.

Teaser: métricas, logs y trazas sin perderte en dashboards infinitos.