GitOps na prática - ArgoCD e estrutura de repositório

1. Retomando: do kubectl apply manual a um fluxo automatizado

Nas duas primeiras partes desta série, todo Deployment foi aplicado com kubectl apply -f arquivo.yaml, rodado à mão a partir da máquina de quem estava operando o cluster. Isso funciona para aprender e para clusters pequenos, mas expõe problemas reais em produção: não há registro confiável de quem aplicou o quê e quando, é fácil um manifesto aplicado manualmente divergir silenciosamente do que está versionado no Git, e cada pessoa do time precisa de acesso direto (e credenciais) ao cluster para fazer deploy. Este artigo introduz GitOps, a prática que resolve exatamente isso, e o ArgoCD, uma das ferramentas mais usadas para implementá-la.

2. O que é GitOps

GitOps é a aplicação da ideia de infraestrutura como código a um extremo específico: o Git como única fonte de verdade do estado desejado de um cluster Kubernetes, com um agente rodando dentro do próprio cluster que observa o repositório continuamente e aplica qualquer mudança automaticamente — sem que ninguém precise rodar kubectl apply manualmente.

O fluxo típico é:

1. Alguém abre um pull request alterando um manifesto YAML (por exemplo, mudando replicas: 2 para replicas: 4, ou atualizando a tag de uma imagem).
2. O PR passa por revisão e CI, como qualquer outra mudança de código.
3. Ao ser mesclado (merge) na branch principal, um agente GitOps rodando no cluster detecta a diferença entre o que está no Git e o que está rodando, e aplica a mudança automaticamente.
4. O cluster converge para o estado descrito no repositório — sem que ninguém tenha rodado um comando manual contra o cluster.

Pull Request → Review/CI → Merge no Git
                                  │
                     (agente GitOps observa o repo)
                                  │
                                  ▼
                    Cluster Kubernetes converge
                    automaticamente para o estado
                          descrito no Git

3. Por que isso faz sentido em infraestrutura como código

Comparado a aplicar manifestos manualmente (mesmo que a partir de um pipeline de CI que roda kubectl apply), GitOps traz três ganhos concretos:

• Auditoria natural: o histórico do Git — quem propôs a mudança, quem revisou, quando foi mesclada — já é o registro de auditoria de tudo que aconteceu no cluster, sem precisar de uma ferramenta separada de log de mudanças.
• Reconciliação contínua: o agente GitOps não só aplica mudanças, mas continua comparando o estado real do cluster com o Git em intervalos regulares. Se alguém alterar algo manualmente no cluster (um kubectl edit de emergência, por exemplo), o agente detecta a divergência e pode reverter automaticamente para o que está declarado no Git — ou pelo menos alertar que há um "drift".
• Menos acesso direto ao cluster: times não precisam mais de credenciais de kubectl com permissão de escrita no cluster de produção para fazer deploy — a mudança passa pelo Git, e só o agente GitOps (com suas próprias credenciais, geridas separadamente) tem acesso de escrita direto.

Isso é uma extensão natural do que a série já vinha construindo: Deployments e Services declarativos (Artigo 1), organizados com namespaces e configuração externa via ConfigMaps/Secrets (Artigo 2) — GitOps apenas formaliza que a fonte de verdade desses YAMLs é um repositório Git, e que a aplicação ao cluster é automática, não manual.

4. Introdução ao ArgoCD

O ArgoCD é um dos controladores GitOps mais usados para Kubernetes. Ele roda como uma aplicação dentro do próprio cluster e introduz um novo tipo de recurso, a Application, que aponta para um caminho em um repositório Git e para um cluster/namespace de destino.

Instalação básica em um cluster (local, como o criado com Minikube/Kind no Artigo 1, ou um cluster real):

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

Depois de instalado, uma Application do ArgoCD conecta um repositório a um destino no cluster:

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

• source diz onde está o estado desejado: repositório, branch/tag e caminho dentro do repo.
• destination diz onde aplicar: qual cluster (https://kubernetes.default.svc é o próprio cluster onde o ArgoCD roda) e namespace.
• syncPolicy.automated liga a sincronização automática: selfHeal: true faz o ArgoCD reverter mudanças manuais feitas fora do Git (o "drift" mencionado acima); prune: true remove do cluster recursos que foram removidos do repositório.

Sem syncPolicy.automated, o ArgoCD ainda detecta divergências e mostra o diff entre Git e cluster, mas espera uma sincronização manual (via UI ou argocd app sync) — uma opção mais conservadora para começar, antes de confiar totalmente no modo automático.

5. Alternativa: Flux

O Flux é a alternativa mais usada ao ArgoCD, com a mesma proposta — observar um repositório Git e reconciliar o cluster com o que está nele — mas com uma filosofia mais "nativa" ao modelo de controladores do Kubernetes (sem uma UI própria tão robusta quanto a do ArgoCD, focado em CRDs e composição via kustomize). Este artigo usa o ArgoCD como exemplo principal por ter a curva de entrada mais suave (UI web incluída), mas os conceitos de GitOps — Git como fonte de verdade, reconciliação automática, sync policies — se aplicam igualmente às duas ferramentas, e a escolha entre elas costuma depender mais de preferência de equipe do que de uma diferença técnica decisiva.

6. Estruturando um repositório de manifests

Uma dúvida comum ao adotar GitOps é como organizar o repositório de manifests. Uma estrutura comum, que separa aplicações e ambientes:

minha-app-manifests/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patch-replicas.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── producao/
        ├── kustomization.yaml
        └── patch-replicas.yaml

Essa estrutura usa kustomize (embutido no kubectl e nativamente suportado por ArgoCD e Flux): a pasta base/ tem os manifestos comuns, e cada overlay aplica só as diferenças daquele ambiente (número de réplicas, limites de recursos, variáveis específicas) por cima da base, evitando duplicar o YAML inteiro para cada ambiente. Uma Application do ArgoCD apontando para overlays/producao (como no exemplo da seção anterior) sempre aplica a base mais os ajustes específicos de produção.

Para projetos que usam Helm em vez de manifestos YAML puros, o mesmo princípio se aplica: o repositório versiona o values.yaml de cada ambiente, e a Application do ArgoCD aponta para o chart e para o arquivo de valores correspondente ao ambiente de destino.

7. Conclusão e próximos passos

Neste artigo, vimos o que é GitOps e por que ele resolve problemas reais de auditoria, drift de configuração e acesso direto ao cluster que o kubectl apply manual não resolve, uma introdução prática ao ArgoCD com uma Application real, uma menção ao Flux como alternativa, e uma forma comum de estruturar um repositório de manifests com kustomize para múltiplos ambientes. No próximo e último artigo desta série, os exemplos ficam mais avançados: automação completa de deploy com GitOps, rollback automático, sync policies mais refinadas e boas práticas para rodar isso tudo com confiança em produção.

---

Imagem de capa: Logo oficial do Kubernetes — repositório kubernetes/kubernetes

Referências:

1. ArgoCD Documentation
2. Flux Documentation
3. OpenGitOps — Princípios de GitOps
4. Kustomize Documentation