<h2>O que é ArgoCD e Por que GitOps?</h2>

<p>ArgoCD é uma ferramenta declarativa de entrega contínua (CD) construída especificamente para Kubernetes. Diferentemente de pipelines tradicionais que fazem &quot;push&quot; de mudanças (você envia o código para o cluster), ArgoCD implementa o padrão GitOps onde o próprio cluster &quot;puxa&quot; 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.</p>

<p>GitOps é um paradigma onde todo o estado da infraestrutura e aplicações é versionado em Git. Quando você precisa fazer deploy, não executa comandos <code>kubectl apply</code> 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.</p>

<h2>Arquitetura Fundamental do ArgoCD</h2>

<h3>Como ArgoCD Funciona</h3>

<p>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.</p>

<p>A arquitetura consiste em três partes principais: (1) o <strong>API Server</strong> que gerencia as aplicações e seus estados, (2) o <strong>Repository Server</strong> que clona e analisa seu repositório Git, e (3) o <strong>Application Controller</strong> que executa a sincronização entre Git e cluster. Existe também uma interface web e CLI para visualizar e gerenciar aplicações.</p>

<h3>Instalação Prática</h3>

<p>Vamos instalar o ArgoCD em seu cluster. Primeiro, certifique-se de que você tem <code>kubectl</code> configurado e conectado ao seu cluster:</p>

<pre><code class="language-bash"># 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</code></pre>

<p>Acesse <code>https://localhost:8080</code> no navegador. A senha padrão do usuário <code>admin</code> é armazenada em um secret:</p>

<pre><code class="language-bash"># Recuperar senha inicial

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath=&quot;{.data.password}&quot; | base64 -d</code></pre>

<p>Após fazer login, mude a senha imediatamente usando a CLI do ArgoCD. Instale a CLI primeiro:</p>

<pre><code class="language-bash"># 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</code></pre>

<h2>Criando e Gerenciando Aplicações com ArgoCD</h2>

<h3>Definindo uma Aplicação GitOps</h3>

<p>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:</p>

<pre><code>meu-repo/

├── k8s/

│ ├── deployment.yaml

│ ├── service.yaml

│ └── configmap.yaml

└── README.md</code></pre>

<p>Aqui está um exemplo de <code>deployment.yaml</code>:</p>

<pre><code class="language-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: &quot;64Mi&quot;

cpu: &quot;250m&quot;

limits:

memory: &quot;128Mi&quot;

cpu: &quot;500m&quot;</code></pre>

<p>Agora, crie um manifesto da Aplicação ArgoCD (chamado <code>argocd-app.yaml</code>):</p>

<pre><code class="language-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</code></pre>

<p>Aplique este manifesto no seu cluster:</p>

<pre><code class="language-bash">kubectl apply -f argocd-app.yaml</code></pre>

<p>O ArgoCD agora vai sincronizar automaticamente. Você pode acompanhar pelo dashboard ou pela CLI:</p>

<pre><code class="language-bash"># Listar aplicações

argocd app list

Ver status detalhado

argocd app get nginx-app

Forçar sincronização

argocd app sync nginx-app</code></pre>

<h3>Sincronização Automática vs Manual</h3>

<p>No exemplo anterior, usamos <code>automated.prune: true</code> e <code>automated.selfHeal: true</code>. 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:</p>

<pre><code class="language-yaml">syncPolicy:

syncOptions:

• CreateNamespace=true

Sem &#039;automated&#039;, você fará deploy manualmente via:

argocd app sync nginx-app</code></pre>

<h2>Padrões Avançados e Boas Práticas</h2>

<h3>Multi-ambiente com Kustomize</h3>

<p>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:</p>

<pre><code>meu-repo/

├── base/

│ ├── kustomization.yaml

│ ├── deployment.yaml

│ └── service.yaml

├── overlays/

│ ├── dev/

│ │ └── kustomization.yaml

│ ├── staging/

│ │ └── kustomization.yaml

│ └── production/

│ └── kustomization.yaml</code></pre>

<p>Arquivo <code>base/kustomization.yaml</code>:</p>

<pre><code class="language-yaml">apiVersion: kustomize.config.k8s.io/v1beta1

kind: Kustomization

resources:

• deployment.yaml
• service.yaml</code></pre>

<p>Arquivo <code>base/deployment.yaml</code>:</p>

<pre><code class="language-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: &quot;64Mi&quot;

cpu: &quot;100m&quot;</code></pre>

<p>Arquivo <code>overlays/production/kustomization.yaml</code>:</p>

<pre><code class="language-yaml">apiVersion: kustomize.config.k8s.io/v1beta1

kind: Kustomization

bases:

• ../../base

replicas:

• name: app

count: 5

images:

• name: myapp

newTag: &quot;1.2.3&quot;

patchesStrategicMerge:

• deployment-patch.yaml</code></pre>

<p>Arquivo <code>overlays/production/deployment-patch.yaml</code>:</p>

<pre><code class="language-yaml">apiVersion: apps/v1

kind: Deployment

metadata:

name: app

spec:

template:

spec:

containers:

• name: app

resources:

requests:

memory: &quot;256Mi&quot;

cpu: &quot;500m&quot;

limits:

memory: &quot;512Mi&quot;

cpu: &quot;1000m&quot;</code></pre>

<p>Agora crie uma aplicação ArgoCD apontando para o overlay de production:</p>

<pre><code class="language-yaml">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</code></pre>

<h3>Helm Charts com ArgoCD</h3>

<p>Se você prefere Helm (em vez de manifestos brutos ou Kustomize), ArgoCD suporta nativamente. Estruture seu repositório:</p>

<pre><code>meu-helm-repo/

├── Chart.yaml

├── values.yaml

├── values-dev.yaml

├── values-prod.yaml

└── templates/

├── deployment.yaml

├── service.yaml

└── _helpers.tpl</code></pre>

<p>Arquivo <code>values-prod.yaml</code>:</p>

<pre><code class="language-yaml">replicaCount: 5

image:

repository: myapp

tag: &quot;1.2.3&quot;

resources:

limits:

cpu: &quot;1&quot;

memory: &quot;512Mi&quot;

requests:

cpu: &quot;500m&quot;

memory: &quot;256Mi&quot;</code></pre>

<p>Manifesto da Aplicação ArgoCD:</p>

<pre><code class="language-yaml">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</code></pre>

<h3>Notificações e Integração com CI/CD</h3>

<p>O ArgoCD pode notificar via Slack, email ou webhooks quando uma sincronização ocorre. Configure notificações editando o ConfigMap:</p>

<pre><code class="language-bash">kubectl edit configmap argocd-notifications-cm -n argocd</code></pre>

<p>Exemplo de configuração para Slack:</p>

<pre><code class="language-yaml">service.slack: |

token: $slack-token</code></pre>

<p>Depois, configure um gatilho de notificação no <code>argocd-application.yaml</code>:</p>

<pre><code class="language-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</code></pre>

<p>Integração com CI/CD é simples: quando seu pipeline de CI termina (testes passam, imagem é feita), você atualiza a tag da imagem no Git:</p>

<pre><code class="language-bash"># 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 &quot;s|image: myapp:.*|image: myapp:${{ github.sha }}|g&quot; k8s/deployment.yaml

git config user.email &quot;ci@example.com&quot;

git config user.name &quot;CI Bot&quot;

git add k8s/deployment.yaml

git commit -m &quot;Update image to ${{ github.sha }}&quot;

git push</code></pre>

<p>O ArgoCD detectará a mudança em segundos e sincronizará automaticamente.</p>

<h2>Conclusão</h2>

<p>ArgoCD implementa GitOps de forma elegante e pronta para produção, eliminando a necessidade de imperativos <code>kubectl apply</code> 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.</p>

<h2>Referências</h2>

<ul>

<li><a href="https://argo-cd.readthedocs.io/en/stable/" target="_blank" rel="noopener noreferrer">Documentação Oficial ArgoCD</a></li>

<li><a href="https://www.weave.works/technologies/gitops/" target="_blank" rel="noopener noreferrer">GitOps with Kubernetes</a></li>

<li><a href="https://kustomize.io/" target="_blank" rel="noopener noreferrer">Kustomize - Kubernetes native configuration management</a></li>

<li><a href="https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/" target="_blank" rel="noopener noreferrer">ArgoCD Application CRD Specification</a></li>

<li><a href="https://helm.sh/" target="_blank" rel="noopener noreferrer">Helm Package Manager for Kubernetes</a></li>

</ul>

<p>&lt;!-- FIM --&gt;</p>