Curso Kubernetes 22 — GitOps com ArgoCD

A pergunta que define GitOps: se alguém apagar um Deployment às 3h da manhã, o cluster volta sozinho?

Se a resposta é "não", você tem CI com kubectl apply, não GitOps. A diferença é quem manda no estado desejado.

Selo do curso: testado em Kubernetes 1.35 com ArgoCD 2.x.

O modelo

Git (estado desejado) ──► ArgoCD (comparação) ──► Cluster (estado real)
                              ▲                        │
                              └──── drift detectado ───┘

• Fonte de verdade: repositório Git.
• Agente: ArgoCD roda no cluster e compara continuamente.
• Resultado: Synced/OutOfSync e Healthy/Degraded.

Ninguém aplica com kubectl em produção. Se aplicar, o ArgoCD reverte — e isso é o comportamento correto.

Instalação

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

Acesso:

kubectl -n argocd port-forward svc/argocd-server 8080:443
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

Em produção: Ingress com TLS, SSO (OIDC) e RBAC do ArgoCD. O admin local é só para bootstrap.

Uma Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: portal-homolog
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/portal-gitops.git
    targetRevision: main
    path: apps/portal/overlays/homolog
  destination:
    server: https://kubernetes.default.svc
    namespace: portal
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true
    retry:
      limit: 3
      backoff:
        duration: 10s
        factor: 2
        maxDuration: 3m

Pontos que importam:

• prune: true remove o que saiu do Git.
• selfHeal: true corrige alteração manual.
• retry evita ficar em Degraded por erro transitório de imagem.

App-of-apps

Um repositório, muitas Applications:

gitops/
  bootstrap/
    root-app.yaml
  apps/
    portal/
      base/
      overlays/homolog
      overlays/prod
    observability/
    operators/

A root-app aponta para apps/ e o ArgoCD descobre o resto. Adicionar ambiente novo = abrir PR.

Sincronização: manual ou automática

Modo	Quando usar
Manual (syncPolicy vazio)	produção regulada, janela aprovada
Automated	homolog, staging, serviços internos
Automated + selfHeal	tudo que precisa resistir a mudança manual
Automated + prune	ambientes descartáveis e GitOps maduro

prune em produção exige cuidado: um erro de path no PR pode remover recursos. Use Prune=false annotation em objetos críticos e proteja o repositório com revisão obrigatória.

Drift: o inimigo silencioso

Drift acontece quando alguém:

• edita o Deployment no painel;
• roda kubectl set image;
• aplica um manifest avulso;
• altera um HPA que muda réplicas (réplicas gerenciadas por HPA não devem estar no Git).

argocd app diff portal-homolog
argocd app history portal-homolog

HPA + réplicas no Git é uma briga eterna: o ArgoCD quer 2, o HPA quer 6. Remova replicas do manifest gerenciado quando houver HPA.

Segredos no GitOps

Não commite Secret. Opções:

• Sealed Secrets: criptografa e pode ir para o Git.
• External Secrets Operator: busca no Vault/secret manager.
• SOPS + age: criptografia no repositório.

O ArgoCD só precisa enxergar o recurso final; a origem do segredo fica fora.

Laboratório

1. Instale o ArgoCD e acesse a UI.
2. Crie um repositório GitOps com um Deployment simples.
3. Crie a Application e sincronize.
4. Altere o Deployment na mão (kubectl scale) e veja o selfHeal voltar ao valor do Git.
5. Delete o Deployment e confirme a recriação.
6. Faça um commit com replicas: 3 e acompanhe o sync automático.
7. Remova o recurso do Git e veja o prune agir.
8. Provogue um erro (imagem inexistente) e observe Degraded + retry.

Erros comuns

Sintoma	Causa
OutOfSync eterno	campo gerenciado por outro controller (HPA, webhook)
ComparisonError	repo/path/branch errado ou credencial
Degraded após sync	image pull, quota, PVC pending
Recurso órfão	prune: false
Sync sobrescreve HPA	replicas no manifest
Segredo no Git	falta de Sealed/External Secrets
Loop de sync	default do cluster difere do manifest (ignoreDifferences)

ignoreDifferences é paliativo: use quando o campo é realmente gerenciado por outro componente, não para esconder drift real.

Checklist

• [ ] ArgoCD com SSO e RBAC (admin local só no bootstrap).
• [ ] Repositório GitOps separado do código da aplicação.
• [ ] selfHeal e prune conscientes por ambiente.
• [ ] replicas fora do manifest onde há HPA.
• [ ] Segredos via Sealed/External Secrets.
• [ ] argocd app diff faz parte do processo de PR.
• [ ] Alertas para Degraded e OutOfSync.
• [ ] Backup do repositório GitOps.

Glossário

• Application: CRD que liga repo/path a um destino.
• sync: aplicar o estado desejado.
• prune: remover recursos ausentes no Git.
• selfHeal: reverter drift automaticamente.
• drift: divergência entre Git e cluster.
• app-of-apps: padrão de Applications que gerenciam Applications.

Próximo

Com o deploy versionado e reconciliado, falta o detalhe que o usuário sente: zero downtime. Probes, rolling update, PDB e HPA no próximo capítulo.

Próximo: Curso Kubernetes 23 — Deploy sem downtime: probes, rolling update e HPA