O que é ArgoCD e Por que GitOps?
ArgoCD é uma ferramenta declarativa de entrega contínua (CD) construída especificamente para Kubernetes. Diferentemente de pipelines tradicionais que fazem "push" de mudanças (você envia o código para o cluster), ArgoCD implementa o padrão GitOps onde o próprio cluster "puxa" as configurações desejadas de um repositório Git. Isso significa que seu repositório Git se torna a fonte única da verdade para o estado da aplicação.
GitOps é um paradigma onde todo o estado da infraestrutura e aplicações é versionado em Git. Quando você precisa fazer deploy, não executa comandos kubectl apply manualmente — em vez disso, você faz um commit no Git e o ArgoCD detecta a mudança, sincroniza o cluster com a configuração desejada e relata o status. Isso oferece rastreabilidade completa, auditoria integrada, rollback automático e recuperação de desastres simplificada. Em um ambiente produção, isso é transformador.
Arquitetura Fundamental do ArgoCD
Como ArgoCD Funciona
O ArgoCD roda como um conjunto de controladores dentro do seu cluster Kubernetes. O componente central é o controlador de reconciliação que periodicamente (padrão: 3 minutos) sincroniza o estado desejado (definido em Git) com o estado atual do cluster. Se alguém deletar um pod acidentalmente, o ArgoCD o recria automaticamente — porque a declaração em Git é a verdade absoluta.
A arquitetura consiste em três partes principais: (1) o API Server que gerencia as aplicações e seus estados, (2) o Repository Server que clona e analisa seu repositório Git, e (3) o Application Controller que executa a sincronização entre Git e cluster. Existe também uma interface web e CLI para visualizar e gerenciar aplicações.
Instalação Prática
Vamos instalar o ArgoCD em seu cluster. Primeiro, certifique-se de que você tem kubectl configurado e conectado ao seu cluster:
# Criar namespace do ArgoCD
kubectl create namespace argocd
# Instalar ArgoCD usando manifesto oficial
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# Verificar se todos os pods estão rodando
kubectl get pods -n argocd
# Expor o API Server (você pode usar port-forward ou criar um Ingress)
kubectl port-forward svc/argocd-server -n argocd 8080:443
Acesse https://localhost:8080 no navegador. A senha padrão do usuário admin é armazenada em um secret:
# Recuperar senha inicial
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
Após fazer login, mude a senha imediatamente usando a CLI do ArgoCD. Instale a CLI primeiro:
# No macOS
brew install argocd
# No Linux
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64
# Fazer login via CLI
argocd login localhost:8080
Criando e Gerenciando Aplicações com ArgoCD
Definindo uma Aplicação GitOps
Uma aplicação no ArgoCD é definida por um manifesto YAML que aponta para um repositório Git e diz qual configuração sincronizar. Vamos criar um exemplo prático. Suponha que você tem um repositório Git com esta estrutura:
meu-repo/
├── k8s/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── configmap.yaml
└── README.md
Aqui está um exemplo de deployment.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-app
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.24
ports:
- containerPort: 80
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
Agora, crie um manifesto da Aplicação ArgoCD (chamado argocd-app.yaml):
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: nginx-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/seu-usuario/meu-repo.git
targetRevision: main
path: k8s
destination:
server: https://kubernetes.default.svc
namespace: default
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
Aplique este manifesto no seu cluster:
kubectl apply -f argocd-app.yaml
O ArgoCD agora vai sincronizar automaticamente. Você pode acompanhar pelo dashboard ou pela CLI:
# Listar aplicações
argocd app list
# Ver status detalhado
argocd app get nginx-app
# Forçar sincronização
argocd app sync nginx-app
Sincronização Automática vs Manual
No exemplo anterior, usamos automated.prune: true e automated.selfHeal: true. Isso significa que o ArgoCD sincroniza automaticamente e remove recursos que não estão mais em Git (prune) além de corrigir desvios em tempo real (selfHeal). Para aplicações críticas, você pode querer sincronização manual:
syncPolicy:
syncOptions:
- CreateNamespace=true
# Sem 'automated', você fará deploy manualmente via:
# argocd app sync nginx-app
Padrões Avançados e Boas Práticas
Multi-ambiente com Kustomize
Em produção, você raramente tem um único ambiente. Você precisa de dev, staging e production com configurações diferentes. O Kustomize é perfeito para isso. Estruture seu repositório assim:
meu-repo/
├── base/
│ ├── kustomization.yaml
│ ├── deployment.yaml
│ └── service.yaml
├── overlays/
│ ├── dev/
│ │ └── kustomization.yaml
│ ├── staging/
│ │ └── kustomization.yaml
│ └── production/
│ └── kustomization.yaml
Arquivo base/kustomization.yaml:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
Arquivo base/deployment.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: app
spec:
replicas: 1
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: app
image: myapp:latest
resources:
requests:
memory: "64Mi"
cpu: "100m"
Arquivo overlays/production/kustomization.yaml:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
bases:
- ../../base
replicas:
- name: app
count: 5
images:
- name: myapp
newTag: "1.2.3"
patchesStrategicMerge:
- deployment-patch.yaml
Arquivo overlays/production/deployment-patch.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: app
spec:
template:
spec:
containers:
- name: app
resources:
requests:
memory: "256Mi"
cpu: "500m"
limits:
memory: "512Mi"
cpu: "1000m"
Agora crie uma aplicação ArgoCD apontando para o overlay de production:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: myapp-production
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/seu-usuario/meu-repo.git
targetRevision: main
path: overlays/production
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
Helm Charts com ArgoCD
Se você prefere Helm (em vez de manifestos brutos ou Kustomize), ArgoCD suporta nativamente. Estruture seu repositório:
meu-helm-repo/
├── Chart.yaml
├── values.yaml
├── values-dev.yaml
├── values-prod.yaml
└── templates/
├── deployment.yaml
├── service.yaml
└── _helpers.tpl
Arquivo values-prod.yaml:
replicaCount: 5
image:
repository: myapp
tag: "1.2.3"
resources:
limits:
cpu: "1"
memory: "512Mi"
requests:
cpu: "500m"
memory: "256Mi"
Manifesto da Aplicação ArgoCD:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: myapp-helm
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/seu-usuario/meu-helm-repo.git
targetRevision: main
path: .
helm:
valuesFiles:
- values-prod.yaml
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
Notificações e Integração com CI/CD
O ArgoCD pode notificar via Slack, email ou webhooks quando uma sincronização ocorre. Configure notificações editando o ConfigMap:
kubectl edit configmap argocd-notifications-cm -n argocd
Exemplo de configuração para Slack:
service.slack: |
token: $slack-token
Depois, configure um gatilho de notificação no argocd-application.yaml:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: myapp
namespace: argocd
annotations:
notifications.argoproj.io/subscribe.on-sync-succeeded.slack: notificacoes
notifications.argoproj.io/subscribe.on-sync-failed.slack: notificacoes
spec:
# ... resto da configuração
Integração com CI/CD é simples: quando seu pipeline de CI termina (testes passam, imagem é feita), você atualiza a tag da imagem no Git:
# No seu pipeline CI (exemplo com GitHub Actions)
- name: Update image tag in ArgoCD repo
run: |
git clone https://github.com/seu-usuario/meu-repo.git
cd meu-repo
sed -i "s|image: myapp:.*|image: myapp:${{ github.sha }}|g" k8s/deployment.yaml
git config user.email "ci@example.com"
git config user.name "CI Bot"
git add k8s/deployment.yaml
git commit -m "Update image to ${{ github.sha }}"
git push
O ArgoCD detectará a mudança em segundos e sincronizará automaticamente.
Conclusão
ArgoCD implementa GitOps de forma elegante e pronta para produção, eliminando a necessidade de imperativos kubectl apply e tornando Kubernetes tão simples quanto fazer um commit. Você aprendeu que (1) ArgoCD funciona constantemente comparando o estado em Git com o cluster, corrigindo desvios automaticamente — isso é recuperação de desastres integrada, (2) Kustomize e Helm com ArgoCD permitem gerenciar múltiplos ambientes sem duplicação de código, mantendo simplicidade, e (3) integração com CI/CD é trivial: seu CI atualiza Git, ArgoCD sincroniza — seu pipeline agora é completamente rastreável e auditável. A verdade está no Git, não em comandos perdidos em históricos de terminal.