GitOps — ArgoCD, Flux e o repositório como fonte da verdade

Em 2017, Alexis Richardson (CEO da Weaveworks) cunhou o termo "GitOps" descrevendo como o time operava clusters Kubernetes internamente: toda mudança de infraestrutura era um pull request, um operador dentro do cluster sincronizava o estado real com o estado desejado no git, e qualquer divergência era detectada automaticamente. O insight central era inverter o fluxo de deploy: em vez do pipeline de CI empurrar mudanças para o cluster, o cluster puxava do repositório git.

Essa inversão resolve um problema de segurança sutil: no modelo push, o pipeline de CI tem credenciais de produção (uma kubeconfig ou IAM role com permissão de deploy). No modelo pull, o cluster tem credenciais para ler o repositório git — ninguém de fora tem credenciais de produção. O raio de explosão de um comprometimento do pipeline de CI é eliminado.

Os quatro princípios GitOps

A OpenGitOps (CNCF) define GitOps por quatro princípios:

1. Declarativo: o sistema gerenciado é descrito declarativamente (manifests Kubernetes, não scripts imperativos)
2. Versionado e imutável: o estado desejado é armazenado no git — histórico completo, auditável, e reversível
3. Pull automático: agentes dentro do sistema puxam as declarações do git automaticamente
4. Reconciliação contínua: os agentes comparam continuamente o estado real com o desejado e corrigem divergências

O princípio da reconciliação contínua é o que diferencia GitOps de simplesmente "armazenar manifests no git": um GitOps operator detecta drift (quando alguém modifica um recurso diretamente no cluster sem passar pelo git) e reverte automaticamente. O cluster sempre converge para o estado declarado no repositório.

ArgoCD — o operator mais popular

ArgoCD é o GitOps operator mais adotado, com UI web, CLI, e API. O conceito central é o objeto Application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: meu-servico
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/minha-org/k8s-manifests
    targetRevision: main
    path: apps/meu-servico/producao   # pasta com os manifests Kustomize
  destination:
    server: https://kubernetes.default.svc  # cluster local
    namespace: meu-servico
  syncPolicy:
    automated:
      prune: true      # remove recursos que foram deletados do git
      selfHeal: true   # reverte mudanças manuais no cluster (drift correction)
    syncOptions:
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground

Com automated.selfHeal: true, qualquer mudança feita diretamente no cluster (via kubectl edit ou kubectl apply) é revertida automaticamente em até 3 minutos. Isso pode parecer restritivo — e é. Em emergências, você pode desabilitar o auto-sync temporariamente via argocd app set meu-servico --sync-policy none, fazer a mudança manual, e depois documentar e commitar a mudança no git.

ApplicationSets — gerenciando múltiplos clusters

Para gerenciar muitas Applications de forma programática — por exemplo, um Application por ambiente ou por cluster — o ArgoCD tem ApplicationSet:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: meu-servico-todos-ambientes
spec:
  generators:
    - list:
        elements:
          - cluster: dev
            url: https://dev.k8s.internal
          - cluster: staging
            url: https://staging.k8s.internal
          - cluster: producao
            url: https://prod.k8s.internal
  template:
    metadata:
      name: 'meu-servico-{{cluster}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/minha-org/k8s-manifests
        path: 'apps/meu-servico/{{cluster}}'
        targetRevision: main
      destination:
        server: '{{url}}'
        namespace: meu-servico

Outros generators: git (detecta pastas no repositório), cluster (todos os clusters registrados no ArgoCD), e matrix (produto cartesiano de dois generators). ApplicationSets são a forma de escalar GitOps de 5 para 50 clusters sem duplicar configuração.

Flux — a alternativa composável

Flux (Weaveworks) implementa GitOps através de um conjunto de controllers separados que podem ser compostos. Ao contrário do ArgoCD (que tem uma única instalação com múltiplos componentes), o Flux segue o princípio Unix de ferramentas pequenas e focadas:

• source-controller: observa repositórios git, Helm repositories, e OCI registries — produz artefatos
• kustomize-controller: aplica Kustomizations no cluster a partir dos artefatos
• helm-controller: aplica HelmReleases
• notification-controller: envia alertas para Slack/Teams quando sync falha
• image-automation-controller: atualiza automaticamente a tag de imagem no repositório git

# GitRepository — de onde Flux observa o estado desejado
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: k8s-manifests
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/minha-org/k8s-manifests
  ref:
    branch: main
  secretRef:
    name: github-credentials

---
# Kustomization — o que aplicar e onde
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: meu-servico
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/meu-servico/producao
  prune: true
  sourceRef:
    kind: GitRepository
    name: k8s-manifests
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: meu-servico
      namespace: meu-servico

Image Update Automation — GitOps para imagens

Um problema do GitOps puro: quando o CI faz push de uma nova imagem, como o repositório git é atualizado com o novo digest? Sem automação, alguém precisa fazer commit manualmente. O Flux resolve com Image Automation:

# ImageRepository — qual registry observar
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: meu-servico
  namespace: flux-system
spec:
  image: ghcr.io/minha-org/meu-servico
  interval: 5m

---
# ImagePolicy — qual tag selecionar automaticamente
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: meu-servico
  namespace: flux-system
spec:
  imageRepositoryRef:
    name: meu-servico
  policy:
    semver:
      range: '>=1.0.0'   # ou regex para selecionar a última

---
# ImageUpdateAutomation — commitar a nova tag no git
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: k8s-manifests
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: fluxcdbot@github.com
        name: fluxcdbot
      messageTemplate: 'chore: update {{range .Updated.Images}}{{.}}{{end}}'
    push:
      branch: main

Com image update automation, o fluxo completo é: CI faz push de nova imagem → Flux detecta nova tag → Flux commita o manifest atualizado no git → Flux aplica o manifest no cluster. O git sempre reflete o estado real do cluster.

Drift detection — quando o cluster diverge do git

Drift acontece quando o estado real do cluster diverge do estado declarado no git. Causas comuns:

• Alguém fez kubectl edit em produção durante um incidente e esqueceu de commitar
• Um Operator (como HPA) modificou um campo que o GitOps operator sobrescreve
• Uma mudança manual foi feita via console do cloud provider

Com selfHeal: true no ArgoCD ou prune: true no Flux, drift é corrigido automaticamente. O problema é quando a mudança manual foi intencional — como ajustar réplicas temporariamente durante um incidente. Para esse caso, o processo correto é:

1. Desabilitar auto-sync temporariamente: argocd app set meu-app --sync-policy none
2. Fazer a mudança manual necessária
3. Commitar a mudança no repositório git (com contexto no commit message)
4. Reabilitar auto-sync: argocd app set meu-app --sync-policy automated

Ferramentas como kubeconform e kube-score podem ser integradas no pipeline de CI para validar manifests antes que entrem no repositório — evitando que manifests inválidos causem falha de sync no cluster.

Repositório de manifests — estrutura recomendada

k8s-manifests/
├── infrastructure/         # infra compartilhada (ingress, cert-manager, ESO)
│   ├── base/
│   └── overlays/
│       ├── staging/
│       └── producao/
├── apps/
│   ├── api-gateway/
│   │   ├── base/           # manifests base com Kustomize
│   │   │   ├── deployment.yaml
│   │   │   ├── service.yaml
│   │   │   └── kustomization.yaml
│   │   └── overlays/
│   │       ├── staging/    # patches específicos de staging
│   │       └── producao/   # patches específicos de prod (mais réplicas, etc)
│   └── meu-servico/
│       └── ...
└── clusters/
    ├── staging/            # FluxCD Kustomizations por cluster
    │   └── flux-system/
    └── producao/
        └── flux-system/

A separação entre repositório de código (onde o CI roda) e repositório de manifests (onde o GitOps operator observa) é opcional mas recomendada para organizações maiores. A vantagem: audit trail separado para mudanças de infra, permissões separadas (nem todo dev pode mudar produção), e histórico de mudanças de configuração independente do código.

Decisões de engenharia

Perguntas de entrevista

spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas   # ArgoCD ignora diferenças neste campo
  syncPolicy:
    automated:
      selfHeal: true       # ainda corrige drift em todos os outros campos

Exercícios práticos