GitOps com ArgoCD: sincronização automática entre repositório e cluster Kubernetes

1. Introdução ao GitOps e seus princípios fundamentais

GitOps é uma metodologia de operações que utiliza o repositório Git como a fonte única da verdade para infraestrutura e aplicações. Diferente da entrega contínua tradicional (CI/CD), onde pipelines automatizados empurram alterações para o ambiente, o GitOps adota uma abordagem baseada em pull: o cluster Kubernetes se mantém constantemente sincronizado com o estado declarado no Git.

Os princípios fundamentais do GitOps incluem:

  • Estado declarativo: toda a configuração do sistema é descrita declarativamente em arquivos versionados
  • Fonte única da verdade: o repositório Git contém o estado desejado completo do sistema
  • Sincronização automática: um operador no cluster garante que o estado real corresponda ao estado desejado
  • Reversão instantânea: qualquer alteração indesejada pode ser desfeita revertendo commits no Git

Os benefícios são significativos: rastreabilidade completa de todas as mudanças, capacidade de reversão imediata para qualquer versão anterior, e maior segurança por eliminar acessos diretos ao cluster.

2. Visão geral do ArgoCD e sua arquitetura

ArgoCD é um operador GitOps para Kubernetes que implementa o ciclo de sincronização entre repositório e cluster. Sua arquitetura é composta por três componentes principais:

  • API Server: expõe a API REST e a interface web, gerencia autenticação e autorização
  • Repository Server: clona e processa repositórios Git, gerando manifests Kubernetes
  • Application Controller: monitora continuamente o cluster e o repositório, aplicando correções quando detecta drift

O fluxo de sincronização funciona da seguinte forma:

  1. O Application Controller compara o estado atual do cluster com o estado desejado no Git
  2. Se detecta diferenças (drift), inicia o processo de sincronização
  3. O Repository Server processa os manifests (aplicando Kustomize ou Helm se configurado)
  4. O controller aplica as alterações necessárias no cluster

O ArgoCD oferece três modos de operação:

  • Manual: o usuário inicia explicitamente a sincronização
  • Automático: o cluster sincroniza automaticamente quando detecta mudanças no Git
  • Auto-healing: corrige automaticamente alterações manuais feitas diretamente no cluster

3. Configuração inicial do ArgoCD no cluster Kubernetes

A instalação pode ser feita via manifestos YAML ou Helm chart. O método mais comum utiliza o Helm:

helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd argo/argo-cd --namespace argocd --create-namespace

Após a instalação, acesse a interface web:

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

Obtenha a senha inicial do admin:

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

Configure o CLI do ArgoCD:

argocd login localhost:8080 --username admin --password <senha>
argocd repo add https://github.com/seu-usuario/seu-repositorio.git --username seu-usuario --password seu-token

4. Criação e gerenciamento de Applications no ArgoCD

Uma Application no ArgoCD define a relação entre uma fonte (repositório Git) e um destino (cluster/namespace). Exemplo de definição:

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

As opções de sincronização automática incluem:

  • auto-sync: sincroniza automaticamente quando detecta mudanças no Git
  • prune: remove recursos que não existem mais no Git
  • self-heal: reverte alterações manuais feitas no cluster

Estratégias avançadas incluem sync waves (execução ordenada de recursos) e janelas de sincronização para controlar quando as atualizações podem ocorrer.

5. Trabalhando com múltiplos ambientes e clusters

Projects no ArgoCD permitem isolar equipes e ambientes:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: producao
  namespace: argocd
spec:
  sourceRepos:
    - https://github.com/seu-usuario/seu-repositorio.git
  destinations:
    - namespace: producao
      server: https://kubernetes.default.svc
  roles:
    - name: admin
      policies:
        - p, proj:producao:admin, applications, *, producao/*, allow

Para gerenciamento de secrets, utilize External Secrets Operator ou Sealed Secrets:

apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
  name: db-credentials
  namespace: producao
spec:
  encryptedData:
    password: AgBy3i4... (dados criptografados)

A promoção entre ambientes pode ser feita via branches (dev, staging, main) ou tags no Git, com regras de aprovação no repositório.

6. Monitoramento, rollback e resolução de conflitos

O ArgoCD exibe status detalhados para cada Application:

  • Synced: cluster está igual ao Git
  • OutOfSync: cluster difere do Git
  • Degraded: recursos estão com problemas

Para realizar rollback:

argocd app rollback minha-app --prune

Isso reverte a aplicação para o estado de um commit anterior no Git.

Quando ocorre drift (alteração manual no cluster), o ArgoCD oferece duas abordagens:

  • Override: aceitar a alteração manual como novo estado desejado
  • Resync: forçar a reversão para o estado do Git

7. Boas práticas e integração com pipelines CI

A estrutura do repositório deve considerar:

  • Monorepo: todos os manifests em um único repositório, organizados por diretórios
  • Multi-repo: repositórios separados para cada aplicação ou ambiente

Integração com pipelines CI para validação:

name: Validar Manifests
on:
  push:
    branches: [main]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validar Kustomize
        run: |
          kustomize build overlays/producao | kubectl apply --dry-run=client -f -

Para parametrização, utilize Kustomize ou Helm:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: minha-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5

8. Casos de uso reais e limitações do ArgoCD

Exemplo prático: deploy de aplicação web com auto-healing

Crie um deployment simples e configure o ArgoCD para sincronização automática. Se alguém alterar manualmente o número de réplicas no cluster, o ArgoCD reverterá automaticamente para o valor definido no Git em segundos.

Limitações:

  • Latência em clusters grandes com muitas Applications (centenas ou milhares)
  • Dependências entre aplicações requerem sync waves ou ferramentas auxiliares
  • Consumo de recursos do cluster pelo operador

Alternativas:

  • Flux CD: mais leve e integrado ao ecossistema CNCF
  • Jenkins X: focado em ambientes cloud-native com pipelines automatizados
  • Rancher Fleet: gerenciamento GitOps em escala para múltiplos clusters

O ArgoCD é a ferramenta mais madura e amplamente adotada para GitOps em Kubernetes, oferecendo um equilíbrio entre simplicidade de uso e recursos avançados para ambientes de produção.

Referências