ArgoCD: GitOps para sincronizar Kubernetes com repositório Git

O que é GitOps e por que o ArgoCD existe

Git como fonte única de verdade para infraestrutura

GitOps é uma abordagem operacional onde o estado desejado de toda a infraestrutura e aplicação é declarado em arquivos versionados no Git. Qualquer mudança no cluster passa pelo repositório Git — nunca diretamente via kubectl ou dashboards. O ArgoCD é o operador Kubernetes que implementa esse princípio: ele monitora continuamente repositórios Git e reconcilia o estado do cluster com o que está declarado nos manifests. Isso cria um audit trail completo de toda mudança operacional, facilita rollback (git revert) e elimina o problema de configuração manual que diverge silenciosamente da documentação.

Applications — como o ArgoCD representa deployments

A unidade fundamental de gerenciamento

No ArgoCD, uma Application é um recurso Kubernetes que define onde está o código-fonte (repositório Git, branch, path) e onde deve ser implantado (cluster de destino, namespace). Múltiplas Applications podem existir no mesmo cluster, cada uma gerenciando um microserviço ou componente diferente. ApplicationSets estendem esse conceito para geração dinâmica de Applications — útil para criar automaticamente uma Application por ambiente (dev, staging, prod) ou por tenant em sistemas multi-tenant. O status de cada Application é visível no dashboard do ArgoCD com indicadores visuais de sincronização e saúde.

Sync e diff — comparando cluster vs Git

Detectando e visualizando divergências

O ArgoCD compara continuamente o estado live do cluster com o estado desejado no Git, produzindo um diff visual no dashboard. Quando há divergência, a Application entra no estado OutOfSync — isso pode acontecer porque alguém aplicou um manifest manualmente, porque um controller Kubernetes modificou o recurso, ou porque houve um commit no repositório. O diff mostra exatamente quais campos mudaram em quais recursos, permitindo auditoria precisa antes de sincronizar. Essa visibilidade é um dos principais valores do ArgoCD: torna o estado real do cluster transparente para todo o time de platform engineering.

Auto-sync e manual sync

Controlando quando o ArgoCD aplica mudanças

Com auto-sync habilitado, o ArgoCD aplica automaticamente qualquer mudança detectada no repositório Git. Isso é ideal para ambientes de desenvolvimento e staging onde velocidade importa mais que controle. Para produção, muitos times preferem sync manual: o ArgoCD detecta o OutOfSync mas aguarda um operador humano confirmar a sincronização no dashboard ou via CLI. Self-heal é uma opção complementar: quando habilitado, o ArgoCD reverte automaticamente mudanças feitas diretamente no cluster via kubectl, reforçando o princípio de que o Git é a única fonte de mudanças válidas. Prune controla se recursos que foram removidos do Git são deletados do cluster.

Helm, Kustomize e manifests no ArgoCD

Suporte nativo a ferramentas de templating

O ArgoCD suporta nativamente Helm charts, Kustomize overlays e manifests YAML simples como fontes de verdade. Para Helm, o ArgoCD renderiza o chart com os values definidos na Application e aplica os recursos resultantes. Com Kustomize, combina base e overlays por ambiente (dev, staging, prod) para gerar configurações específicas sem duplicação. O ArgoCD também suporta Config Management Plugins para ferramentas customizadas como Jsonnet ou Carvel. A abordagem recomendada é manter um repositório separado para manifests (app-manifests-repo) desacoplado do repositório de código da aplicação, evitando que pipelines de CI modifiquem o mesmo repo que o ArgoCD monitora.

RBAC e controle de acesso

Governança em clusters multi-time

O ArgoCD tem um sistema de RBAC próprio baseado em policies Casbin que define quais usuários ou grupos SSO podem ver, sincronizar ou deletar Applications. As permissões são definidas em ConfigMap argocd-rbac-cm com regras granulares: um time pode ter permissão para sincronizar suas próprias Applications mas não visualizar as de outro time. Integração com SSO (OIDC, GitHub, GitLab, LDAP) permite que as permissões sejam baseadas em grupos do provedor de identidade corporativo. Projects no ArgoCD adicionam uma camada de isolamento adicional, restringindo quais repositórios e clusters uma Application pode acessar.

Notificações e webhooks

Mantendo o time informado sobre o estado do cluster

O ArgoCD Notifications Controller envia alertas para Slack, Teams, email e outros canais quando o estado de uma Application muda. Templates configuráveis permitem mensagens ricas com links diretos para o diff no dashboard, nome do autor do commit e lista de recursos afetados. Webhooks do GitHub ou GitLab podem ser configurados para notificar o ArgoCD imediatamente ao receber um push, eliminando a latência do polling periódico e fazendo o sync iniciar em segundos após o merge. Essa integração bidirecional cria um loop de feedback rápido: commit no Git, notificação ao ArgoCD, sync aplicado, notificação de sucesso ou falha ao time.

Multi-cluster com ArgoCD

Gerenciando múltiplos clusters a partir de um ponto central

O ArgoCD pode gerenciar múltiplos clusters Kubernetes a partir de uma única instância de controle. Cada cluster externo é registrado com credenciais via argocd cluster add, e Applications podem ser direcionadas para qualquer cluster registrado. Essa arquitetura hub-and-spoke é comum em empresas com clusters separados por região geográfica, ambiente ou criticidade. ApplicationSets com ClusterGenerator criam automaticamente Applications em todos os clusters correspondentes a um selector, eliminando a necessidade de criar Applications manualmente para cada cluster. O painel central do ArgoCD oferece visibilidade unificada do estado de todos os clusters.

ArgoCD vs Flux — comparação

Os dois principais operadores GitOps para Kubernetes

Flux e ArgoCD são os dois operadores GitOps mais adotados para Kubernetes, mas têm filosofias diferentes. ArgoCD tem uma UI rica com visualização de árvore de recursos, diff visual e aprovação manual — mais amigável para times que valorizam observabilidade visual. Flux é mais minimalista, opinionado sobre separação de repositórios e mais alinhado com o modelo de operators nativos do Kubernetes. ArgoCD é preferido quando o time usa Helm extensivamente e valoriza o dashboard. Flux é preferido quando o time quer uma abordagem mais GitOps-pura com menor footprint de operação. Ambos têm suporte a multi-cluster, RBAC e notificações.

Conclusão

ArgoCD como fundação para deploys Kubernetes confiáveis

Continue em: Fundamentos obrigatórios antes de produção.