GitOps com Argo CD no GKE: do repositório ao cluster sem surpresas

Deploys manuais em produção ainda assombram times de engenharia. Um kubectl apply errado, uma variável esquecida, um rollback que ninguém sabe fazer — e lá se vai a SLA.

GitOps muda esse jogo: o Git vira a única fonte de verdade, e o cluster converge automaticamente para o estado declarado no repositório. Sem SSH no nó, sem scripts de deploy frágeis.

Neste artigo você vai ver como instalar e configurar o Argo CD no GKE, criar seus primeiros Application objects, habilitar sync automático com segurança e estruturar a promoção entre ambientes — tudo com exemplos reais que você pode usar hoje.

Por que GitOps em vez de pipelines tradicionais de CD?

Pipelines clássicos fazem push para o cluster: o CI/CD aplica manifests e torce para que funcionou. O problema é que o cluster pode derivar desse estado ao longo do tempo — alguém escala um Deployment na mão, um HPA muda réplicas, um ConfigMap é editado diretamente.

GitOps inverte o modelo para pull: um agente dentro do cluster (o Argo CD) monitora o repositório e reconcilia continuamente. Qualquer desvio é detectado e pode ser corrigido automaticamente ou reportado.

Benefícios práticos para times que rodam no GKE:

• Auditoria gratuita: toda mudança no cluster tem um commit rastreável
• Rollback trivial: reverter = fazer git revert
• Multi-cluster gerenciável: um Argo CD pode gerenciar dezenas de clusters GKE a partir de um hub central
• Menos permissões nos pipelines: o CI deixa de precisar de acesso direto ao cluster

Pré-requisitos

• Cluster GKE (Standard ou Autopilot) com kubectl configurado
• Helm 3 instalado localmente
• Repositório Git com seus manifests Kubernetes (ou Helm charts)
• gcloud autenticado com permissões de cluster-admin no projeto

Instalando o Argo CD no GKE

A instalação mais limpa usa o manifesto oficial, aplicado em um namespace dedicado:

kubectl create namespace argocd

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

Aguarde os pods ficarem Running:

kubectl get pods -n argocd -w

Para expor a UI via Load Balancer (em ambientes de desenvolvimento ou quando você tem controle de rede):

kubectl patch svc argocd-server -n argocd \
  -p '{"spec": {"type": "LoadBalancer"}}'

Em produção, prefira um Ingress com certificado gerenciado pelo GKE ou acesso via kubectl port-forward restrito ao time de plataforma.

Recupere a senha inicial do admin:

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

Acesse https://<EXTERNAL-IP> com usuário admin e a senha acima. Troque a senha imediatamente após o primeiro login.

Conectando seu repositório Git

Via CLI do Argo CD (recomendado para automação):

argocd login <ARGOCD-SERVER> --username admin --password <SENHA>

argocd repo add https://github.com/sua-org/seu-repo \
  --username git \
  --password <GITHUB-TOKEN>

Para repositórios privados no GCP, use Workload Identity com uma service account que tem acesso ao Cloud Source Repositories — evita tokens estáticos e é a abordagem mais segura no ecossistema Google.

Criando sua primeira Application

O objeto Application é o coração do Argo CD. Ele diz: “monitore este path neste repositório e sincronize com este cluster/namespace.”

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-pagamentos
  namespace: argocd
  labels:
    env: production
    team: backend
spec:
  project: default
  source:
    repoURL: https://github.com/sua-org/k8s-manifests
    targetRevision: main
    path: apps/api-pagamentos/production
  destination:
    server: https://kubernetes.default.svc
    namespace: pagamentos
  syncPolicy:
    automated:
      prune: true # remove recursos que saíram do Git
      selfHeal: true # corrige desvios detectados no cluster
    syncOptions:
      - CreateNamespace=true
      - PrunePropagationPolicy=foreground

Aplique:

kubectl apply -f application-api-pagamentos.yaml

Na UI, você verá a aplicação em estado Synced (verde) quando o cluster bater com o Git, ou OutOfSync se houver divergência.

Entendendo prune e selfHeal

• prune: true: se um recurso foi removido do Git, o Argo CD o deleta do cluster. Essencial para evitar “fantasmas” — recursos que ninguém sabe de onde vieram.
• selfHeal: true: se alguém editar um recurso diretamente no cluster (via kubectl edit ou console GCP), o Argo CD sobrescreve com o estado do Git em segundos.

Em ambientes de produção, avalie habilitar o selfHeal mas deixar o prune como revisão manual (prune: false + notificação), especialmente se StatefulSets ou PVCs estiverem envolvidos.

Estruturando múltiplos ambientes

A forma mais pragmática para times intermediários é a estrutura por diretórios:

k8s-manifests/
├── apps/
│   └── api-pagamentos/
│       ├── base/                  # manifests compartilhados
│       │   ├── deployment.yaml
│       │   ├── service.yaml
│       │   └── kustomization.yaml
│       ├── staging/
│       │   ├── kustomization.yaml # patches de staging
│       │   └── replica-patch.yaml
│       └── production/
│           ├── kustomization.yaml # patches de produção
│           └── replica-patch.yaml

Com Kustomize (suportado nativamente pelo Argo CD), o patch de produção pode ser simples assim:

# production/replica-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-pagamentos
spec:
  replicas: 5
  template:
    spec:
      containers:
        - name: api
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              cpu: "1000m"
              memory: "1Gi"

Crie uma Application por ambiente — staging apontando para path: apps/api-pagamentos/staging, produção para path: apps/api-pagamentos/production.

Promoção entre ambientes sem risco

O fluxo GitOps de promoção é intencional e rastreável:

1. CI faz build da imagem e atualiza a tag no manifesto de staging (via kustomize edit set image ou sed no pipeline)
2. Pull Request de staging → production é revisado pelo time
3. Merge = Argo CD sincroniza produção automaticamente

Para atualização automática de imagem, o Argo CD Image Updater monitora o Container Registry (ou Artifact Registry no GCP) e abre PRs automaticamente quando uma nova tag chega — mantendo o fluxo GitOps sem automação frágil no CI.

# Instalação do Image Updater
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj-labs/argocd-image-updater/stable/manifests/install.yaml

Anote a Application para ativá-lo:

annotations:
  argocd-image-updater.argoproj.io/image-list: api=gcr.io/seu-projeto/api-pagamentos
  argocd-image-updater.argoproj.io/api.update-strategy: semver
  argocd-image-updater.argoproj.io/write-back-method: git

Observabilidade e alertas

O Argo CD expõe métricas Prometheus nativamente. Com o Managed Prometheus do GKE (Google Cloud Managed Service for Prometheus), você coleta sem instalar nada extra:

# PodMonitoring para coletar métricas do Argo CD
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: argocd-metrics
  namespace: argocd
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: argocd-application-controller
  endpoints:
    - port: metrics
      interval: 30s

Métricas essenciais para monitorar:

Configure alertas no Cloud Monitoring para health_status = "Degraded" ou sync_status = "OutOfSync" por mais de 15 minutos — isso cobre a maioria dos cenários críticos sem gerar ruído.

Precisa de ajuda para estruturar seu GitOps no GKE?

Implementar GitOps bem vai além de instalar o Argo CD. Envolve decisões de estrutura de repositório, estratégia de promoção, controle de acesso com RBAC, integração com Secret Manager e observabilidade adequada para o seu contexto.

Na Kadima Cloud, ajudamos times de engenharia a implementar GitOps de forma sólida — com arquitetura pensada para o longo prazo, não só para o demo funcionar.

→ Fale com a Kadima e veja como podemos acelerar a maturidade da sua plataforma Kubernetes.