ArgoCD na prática: GitOps para quem usa CI

Se sua esteira de CI já builda, testa e empacota bem, mas o deploy ainda depende de kubectl apply manual, script solto ou um job de CD que só você entende, o ArgoCD resolve exatamente essa lacuna. Ele não substitui seu CI — assume a parte de entrega contínua (CD) no Kubernetes, usando Git como fonte de verdade.

Premissas deste artigo

Este texto foi escrito a partir de um resumo de pesquisa baseado exclusivamente na documentação oficial do Argo CD (argo-cd.readthedocs.io/en/stable/). Isso tem implicações importantes:

• Não há número de versão específico do ArgoCD citado na fonte — trate os comandos abaixo como válidos para a linha stable no momento da consulta, e confira a versão atual antes de aplicar em produção.
• Não há exemplos de manifesto Application (o CRD central do ArgoCD), nem detalhes de RBAC, nem comparação com Flux ou outras ferramentas GitOps. Se você precisa decidir entre ArgoCD e Flux, este artigo não é suficiente — é só uma introdução ao ArgoCD.
• Os comandos de instalação abaixo vêm da documentação oficial e não foram executados neste ambiente. Valide em um cluster de teste antes de rodar em produção.

O que é GitOps e onde o ArgoCD entra

GitOps é um padrão operacional: o repositório Git guarda o estado desejado da sua aplicação — manifests, configs, versões de imagem — e uma ferramenta de controle garante que o cluster convirja para esse estado. O ArgoCD é essa ferramenta para Kubernetes: um controller que roda dentro do cluster, monitora continuamente as aplicações e compara live state (o que está rodando) com target state (o que está no Git).

Quando os dois divergem, a aplicação fica marcada como OutOfSync, e o ArgoCD oferece dois caminhos: sincronizar automaticamente ou esperar aprovação manual. Essa distinção importa na prática — em ambientes de produção regulados, sync manual com aprovação costuma ser a escolha mais defensável; em dev/staging, auto-sync reduz atrito.

Como o ArgoCD funciona por baixo dos panos

Diferente de um pipeline de CD tradicional que faz push de mudanças para o cluster, o ArgoCD trabalha em modelo pull: ele roda como controller dentro do Kubernetes e periodicamente reconcilia o estado observado contra o Git. Isso muda a superfície de segurança — o cluster não precisa expor credenciais de deploy para o CI, é o ArgoCD (rodando dentro do cluster, com suas próprias permissões) que puxa a mudança.

Essa arquitetura também explica a detecção de drift: se alguém rodar um kubectl edit direto no cluster, o ArgoCD detecta a divergência e a reporta (ou reverte, se auto-sync com selfHeal estiver ativo).

Instalação rápida (visão geral)

A documentação oficial lista a instalação básica assim:

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

As flags --server-side --force-conflicts não são opcionais: a documentação as aponta como necessárias por causa do tamanho dos CRDs do ArgoCD, que excede limites de aplicação client-side padrão do kubectl. Se você automatizar essa instalação via Terraform, Helm ou Argo CD Autopilot, garanta que o mecanismo escolhido replique esse comportamento de server-side apply.

Antes de ir para produção, vale consultar o guia de getting started e, se já existir uma instalação anterior, o upgrade guide — ambos referenciados na documentação oficial, mas fora do escopo do resumo usado aqui.

Formatos de manifesto suportados

O ArgoCD não força um único jeito de descrever aplicações. Ele aceita:

• Kustomize — bom quando você já tem overlays por ambiente (dev/staging/prod) sem duplicar YAML.
• Helm charts — faz sentido se seu ecossistema já usa Helm para empacotar aplicações internas ou de terceiros.
• Jsonnet — útil em cenários com lógica de templating mais complexa que YAML puro não resolve bem.
• Diretório simples de YAML/JSON — a opção mais direta, sem camada de templating.
• Config management plugins customizados — para quando nenhuma das opções acima cobre sua ferramenta interna.

Não existe "formato certo" universal. Se seu time já usa Helm em produção, continue usando Helm — o ArgoCD se encaixa em cima, não força migração de ferramenta de templating.

Estratégias de tracking: branch, tag ou commit fixo

Uma aplicação no ArgoCD pode rastrear um branch (ex.: main), uma tag (ex.: releases semânticas) ou ficar fixada (pinned) em um commit específico. Essa escolha tem consequência direta em governança de deploy:

• Rastrear branch é conveniente para ambientes de desenvolvimento, mas menos rastreável para auditoria de "o que exatamente subiu quando".
• Fixar em tag ou commit dá rastreabilidade forte — cada deploy corresponde a um commit identificável — e é o padrão mais comum em produção.

A documentação referencia uma página dedicada de tracking strategies com mais detalhes, não incluída no resumo consultado aqui.

ArgoCD e sua esteira de CI: quem faz o quê

Este é o ponto que costuma gerar confusão em times que já têm CI maduro. A divisão de responsabilidade típica é:

1. CI (Jenkins, GitLab CI, GitHub Actions etc.) continua fazendo build, teste e publicação de imagem/artefato.
2. O CI (ou um passo separado) atualiza o manifesto no repositório Git — por exemplo, o campo de tag de imagem em um overlay Kustomize ou values.yaml do Helm.
3. O ArgoCD detecta essa mudança no Git e sincroniza o cluster para refletir o novo estado desejado.

A documentação confirma que existe CLI do ArgoCD voltada a automação e integração com CI, e suporte a webhooks (GitHub, BitBucket, GitLab) para acelerar a detecção de mudanças em vez de depender só do polling padrão. O que a fonte consultada não detalha são exemplos concretos dessa integração — isso fica como lacuna a resolver com a documentação de referência ou testes próprios.

Recursos que importam no dia a dia operacional

Além do ciclo básico de sync, alguns recursos citados na documentação pesam na decisão de adoção:

• Multi-cluster: uma instalação de ArgoCD pode gerenciar deploys em múltiplos clusters Kubernetes, útil em topologias com cluster por ambiente ou por região.
• SSO integrado: OIDC, OAuth2, LDAP, SAML 2.0, além de provedores como GitHub, GitLab, Microsoft e LinkedIn — relevante se você já centraliza identidade corporativa e não quer gerenciar usuários locais.
• RBAC e multi-tenancy: permite segregar quem pode sincronizar o quê, importante em clusters compartilhados entre times.
• Hooks PreSync, Sync, PostSync: suportam rollouts mais complexos, como blue/green e canary, coordenando passos antes/depois da sincronização.
• Métricas Prometheus e audit trails: dão visibilidade operacional e histórico de eventos de aplicação e chamadas de API — insumo direto para dashboards de observabilidade e investigação pós-incidente.
• Rollback "roll-anywhere": qualquer configuração já commitada no Git pode ser alvo de rollback, o que reforça a prática de nunca aplicar mudança fora do fluxo Git-first.

Nenhum desses recursos é exclusivo do ArgoCD no universo GitOps, mas juntos formam um conjunto consistente para quem já opera Kubernetes em escala e precisa de auditoria e controle de acesso, não só automação de deploy.

O que este resumo não cobre

Vale ser explícito sobre os limites do material usado para este artigo:

• Sem exemplos de manifesto Application (o recurso que você de fato cria para registrar uma app no ArgoCD).
• Sem comparação técnica com Flux ou outras ferramentas GitOps — se essa é sua dúvida, ela exige pesquisa adicional.
• Sem detalhamento de arquitetura interna (componentes como application-controller, repo-server, api-server), apenas a menção de que o ArgoCD atua como controller Kubernetes.
• Sem dados de adoção por organizações específicas, apenas a referência de que existe uma lista crescente (USERS.md no repositório oficial).

Próximo passo

Se você já tem CI funcionando e o gargalo é entrega para o Kubernetes, o próximo passo prático é instalar o ArgoCD em um cluster de teste, criar uma Application apontando para um repositório com Kustomize ou Helm que você já usa, e observar o ciclo OutOfSync → Synced acontecendo com uma mudança real de commit. Isso mostra mais sobre o modelo pull do ArgoCD do que qualquer descrição teórica — e evita decisão de arquitetura baseada só em documentação, sem fricção de ambiente real.