O ArgoCD é uma ferramenta de entrega contínua declarativa baseada em GitOps para Kubernetes que mantém o estado do cluster permanentemente sincronizado com as configurações armazenadas no Git. Se você já gastou tempo executando manualmente kubectl apply após cada alteração de código ou rastreando deriva de configuração entre ambientes, o ArgoCD resolve isso tornando o Git a única fonte de verdade para cada recurso implantado. Este guia percorre a instalação do ArgoCD, a conexão de repositórios, a criação de recursos Application e a configuração de políticas de sincronização para implantações de nível produtivo.

Pré-requisitos

  • Um cluster Kubernetes em execução (v1.22+) com kubectl configurado
  • Permissões de administrador do cluster para criar namespaces e CRDs
  • Um repositório Git contendo manifests Kubernetes, charts Helm ou overlays Kustomize
  • CLI do ArgoCD (argocd) instalada localmente (opcional, mas recomendada)
  • Familiaridade básica com Deployments, Services e namespaces do Kubernetes

O que é GitOps e por que ArgoCD?

GitOps é um modelo operacional onde o estado desejado da infraestrutura e aplicações é declarado no Git. Um operador rodando dentro do cluster compara continuamente o estado real com o desejado e reconcilia as diferenças. O ArgoCD é o operador GitOps nativo do Kubernetes mais adotado, com status de projeto graduado da CNCF desde 2022.

As principais vantagens em relação aos pipelines de CI/CD tradicionais baseados em push:

CaracterísticaArgoCD (GitOps pull)Jenkins / GitLab CI (push)
Armazenamento de credenciaisSomente dentro do clusterNos secrets do sistema CI
Detecção de derivaContínua, automáticaApenas no momento da implantação
Mecanismo de reversãoRevert do Git para qualquer commitRe-executar pipeline anterior
Trilha de auditoriaHistórico do GitLogs de CI
Suporte multi-clusterNativo, por ApplicationConfiguração manual de pipeline
Auto-recuperaçãoLoop de sincronização integradoNão disponível

O modelo pull é uma melhoria significativa de segurança: seu pipeline de CI não precisa mais de credenciais do cluster. O ArgoCD roda dentro do cluster e puxa mudanças do Git, sempre apenas no sentido de saída.

Instalando o ArgoCD

Crie o namespace dedicado e aplique o manifesto oficial de instalação:

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

Aguarde todos os pods atingirem o estado Running:

kubectl wait --for=condition=available deployment --all -n argocd --timeout=120s
kubectl get pods -n argocd

Acessando a Interface Web

Por padrão, o serviço argocd-server é do tipo ClusterIP. Para acesso local, use port-forwarding:

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

Recupere a senha de administrador gerada automaticamente:

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

Faça login via CLI:

argocd login localhost:8080 --username admin --password <senha> --insecure

Para produção, configure um Ingress com TLS e integre SSO (Dex com GitHub/OIDC) em vez da conta admin.

Conectando um Repositório Git

O ArgoCD precisa de acesso ao seu repositório Git para buscar manifests. Para repositórios públicos não são necessárias credenciais. Para repositórios privados:

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

Para SSH:

argocd repo add git@github.com:sua-org/seu-repo-k8s.git \
  --ssh-private-key-path ~/.ssh/id_rsa

Você também pode gerenciar repositórios de forma declarativa como Secrets do Kubernetes com o label argocd.argoproj.io/secret-type: repository se preferir gerenciamento GitOps completo do próprio ArgoCD.

Criando Applications no ArgoCD

Uma Application é o recurso central do ArgoCD. Ela define o que implantar, de onde e em qual cluster e namespace.

Manifesto de Application declarativo

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

Aplique:

kubectl apply -f minha-web-app-application.yaml

Applications com Helm

O ArgoCD suporta Helm nativamente sem precisar do Helm instalado nos sistemas de CI:

source:
  repoURL: https://github.com/sua-org/seu-repo-k8s
  targetRevision: main
  path: charts/minha-web-app
  helm:
    valueFiles:
      - values-production.yaml
    parameters:
      - name: image.tag
        value: "v1.4.2"

Applications com Kustomize

source:
  repoURL: https://github.com/sua-org/seu-repo-k8s
  targetRevision: main
  path: kustomize/overlays/production

O ArgoCD detecta automaticamente o kustomization.yaml e executa kustomize build de forma transparente.

Políticas de Sincronização e Auto-Recuperação

A política de sincronização é a decisão de configuração mais importante no ArgoCD.

Sincronização manual — O ArgoCD detecta a deriva mas requer uma pessoa (ou etapa de CI) para acionar a sincronização. Útil para ambientes de produção onde se deseja aprovação explícita antes de implantar mudanças.

Sincronização automática — O ArgoCD sincroniza automaticamente quando detecta diferenças entre o Git e o cluster. Combine com auto-recuperação e poda para automação completa:

syncPolicy:
  automated:
    selfHeal: true   # reverte edições manuais com kubectl
    prune: true      # remove recursos deletados do Git
  retry:
    limit: 5
    backoff:
      duration: 5s
      maxDuration: 3m
      factor: 2

selfHeal: true significa que se alguém editar manualmente um recurso com kubectl, o ArgoCD o reverterá em segundos. Isso impõe disciplina GitOps estrita.

prune: true significa que recursos deletados do repositório Git também são deletados do cluster. Sem poda, recursos órfãos se acumulam ao longo do tempo.

Cenário Real: Promoção Multi-Ambiente

Você tem três ambientes — dev, staging e production — cada um em um namespace separado, com overlays Kustomize específicos por ambiente. Seu pipeline de CI constrói e publica uma imagem Docker, depois atualiza a tag de imagem no arquivo dev/kustomization.yaml e faz commit no Git.

repo/
  kustomize/
    base/           ← manifests compartilhados
    overlays/
      dev/          ← App ArgoCD para namespace dev
      staging/      ← App ArgoCD para namespace staging
      production/   ← App ArgoCD para namespace production (sync manual)

O ArgoCD para dev usa automated: {} (implantação automática a cada commit). O ArgoCD para staging e production usa sincronização manual — um engenheiro revisa o diff na UI e clica em sincronizar, ou uma aprovação de PR aciona uma chamada argocd app sync no pipeline de CI.

Esse padrão mantém a promoção controlada e auditável pelo histórico do Git, não pelos logs de build do Jenkins.

Armadilhas e Casos Especiais

Problemas de ordem com CRDs — Se seu app instala Custom Resource Definitions junto com recursos que as usam, o ArgoCD pode falhar na primeira sincronização porque os CRDs ainda não estão estabelecidos. Use sync waves com argocd.argoproj.io/sync-wave: "-1" nos manifests de CRD para garantir que sejam aplicados primeiro.

Poda e Jobs — A poda do ArgoCD deletará Jobs concluídos e seus Pods se forem removidos do Git. Use argocd.argoproj.io/hook: PostSync e argocd.argoproj.io/hook-delete-policy: HookSucceeded para Jobs de migração de execução única.

Estratégia de tags de imagem — Evite usar latest como tag. O ArgoCD compara manifests, não digests de imagem, então um novo push para latest não acionará sincronização. Use tags imutáveis (SHA do git ou semver). O projeto ArgoCD Image Updater pode automatizar a atualização de tags no Git.

RBAC e Projects — O projeto default permite todos os repositórios e clusters. Para configurações multi-time, crie AppProjects com escopo limitado a repositórios fonte, namespaces destino e tipos de recursos permitidos.

Gerenciamento de secrets — Nunca armazene manifests de Secrets do Kubernetes com dados em texto simples no Git. Use Sealed Secrets, External Secrets Operator ou secrets criptografados com SOPS commitados no Git.

Timeout de sincronização — Hooks Helm de longa execução podem exceder o timeout de sincronização padrão (300s). Aumente com --timeout na CLI ou configure timeout.reconciliation no ConfigMap argocd-cm.

Problemas Comuns

App presa em Progressing — Verifique a saída de argocd app get <nome> para recursos degradados. Normalmente é um rollout de Deployment com falha ou um PVC pendente. Execute kubectl describe pod -n <namespace> no Pod afetado.

ComparisonError ou saúde Unknown — O ArgoCD não consegue buscar os manifests. Verifique a conectividade do repositório com argocd repo list e as credenciais.

Loop de auto-recuperação — Se o ArgoCD continua revertendo um recurso, um webhook de validação ou operador está modificando o recurso após o ArgoCD aplicá-lo. Use ignoreDifferences na spec da Application para ignorar campos específicos.

Poda deleta recursos inesperados — Garanta que todos os recursos que deseja que o ArgoCD gerencie tenham o label correto app.kubernetes.io/instance.

Resumo

  • O ArgoCD implementa GitOps reconciliando continuamente o estado do cluster com o estado desejado definido no Git
  • Instala-se com um único kubectl apply no namespace argocd; acesse via port-forward ou Ingress
  • Applications são definidas declarativamente e suportam manifests raw, charts Helm e Kustomize
  • Use sincronização automática com selfHeal e prune para dev/staging; sincronização manual para aprovações em produção
  • Organize configurações multi-ambiente com overlays Kustomize ou arquivos de valores Helm por ambiente
  • Proteja secrets com Sealed Secrets ou External Secrets Operator — nunca em texto simples no Git
  • Use sync waves para ordenação de CRDs e ArgoCD Image Updater para promoção automática de tags
  • RBAC Projects limitam o acesso a repositórios e clusters em implantações multi-time

Artigos Relacionados