Configurei o Argo CD no Kubernetes local — Veja como eu fiz

Configurei o Argo CD no Kubernetes local — Veja como eu fiz

O pod estava rodando havia onze dias. Estável. Saudável. Fazendo seu trabalho silenciosamente dentro do meu cluster Kubernetes local. Eu o deletei de propósito. Seis segundos depois, um pod novinho em folha apareceu no lugar dele. Mesma especificação, mesma configuração, zero downtime. Não toquei no kubectl apply. Não disparei nenhum pipeline. Não fiz absolutamente nada. O Argo CD estava monitorando meu repositório Git, viu que o estado desejado dizia "este pod deve existir" e o trouxe de volta à vida antes que eu pudesse trocar de aba no navegador. Aquele momento — ver um pod deletado ressuscitar sozinho em um cluster local Docker Desktop rodando no meu MacBook — foi quando o GitOps deixou de ser um conceito abstrato que eu tinha lido em posts do blog da CNCF e se tornou algo que eu podia sentir. Algo visceral. Seu repositório Git se torna a única fonte de verdade, e o Kubernetes se curva para corresponder. Não eventualmente. Não depois que um pipeline roda. Agora mesmo. Eu vinha planejando configurar o Argo CD havia meses. Continuava empurrando para "o próximo fim de semana." A suposição era que seria complicado — ferramentas de nível produção geralmente são. Achei que precisaria de um cluster na nuvem, um pipeline CI/CD já configurado, talvez uma tarde inteira lutando com Helm charts e configurações de RBAC. A configuração real levou menos de dez minutos. E o projeto que usei para testá-lo — infrawhisper, uma plataforma de dados e IA que venho construindo com componentes como um servidor API, engine de IA, processador de streams e um dashboard em tempo real — me deu um teste de estresse perfeito para verificar se o Argo CD conseguia lidar com um deployment local genuinamente complexo. Aqui está tudo que fiz, tudo que aprendi, e a armadilha do Docker Desktop que quase inviabilizou tudo.

Por que finalmente parei de rodar kubectl apply na mão

Tenho uma confissão. Por um tempo embaraçosamente longo, meu fluxo de deployment para Kubernetes local era assim:

1. Alterar código
2. Fazer build da imagem Docker
3. Rodar kubectl apply -f deployment.yaml
4. Perceber que esqueci de atualizar a tag da imagem
5. Editar o YAML, aplicar de novo
6. Me perguntar por que os pods antigos ainda estão rodando
7. Deletar o deployment, aplicar do zero
8. Repetir amanhã com a mesma frustração Se você já trabalhou com Kubernetes por algum tempo, conhece essa dor. Não é que o kubectl apply esteja quebrado — funciona perfeitamente. O problema é que ele coloca você, o humano, no caminho crítico de cada deployment. Você se torna o pipeline. E humanos são pipelines terríveis. O problema mais profundo é o drift. Você aplica um manifesto. Um colega de equipe (ou a versão das 2 da manhã de você mesmo) faz uma mudança manual rápida com kubectl edit. Agora o estado do seu cluster divergiu silenciosamente do que está no seu repositório Git. Ninguém percebe até algo quebrar. E quando quebra, boa sorte descobrindo se o estado "correto" está no Git, no cluster ou no histórico de terminal de alguém. O GitOps resolve isso tornando uma regra inegociável: Git é a verdade. O cluster corresponde ao Git. Sempre. Se divergirem, o cluster muda — não o Git. De acordo com uma pesquisa CNCF End User Survey de meados de 2025, quase 60% dos clusters Kubernetes agora dependem do Argo CD para entrega de aplicações. Esse número sobe a cada trimestre. E 97% dos respondentes que usam Argo CD o executam em produção — acima dos 93% em 2023. Esta não é mais uma ferramenta experimental. É a forma padrão como equipes sérias fazem deploy no Kubernetes. Mas a maioria dos guias que encontrei presumiam que você está rodando EKS ou GKE. Um cluster de produção com networking adequado, load balancers e controladores ingress já configurados. Eu queria saber: isso funciona no Docker Desktop? Em um cluster local onde você está experimentando, quebrando coisas e aprendendo? A resposta é sim — com um workaround importante que vou mostrar no passo dois.

O que o Argo CD realmente faz (O modelo mental que importa)

Antes de percorrer a instalação, quero te dar o modelo mental que fez tudo se encaixar para mim. Porque os comandos são simples. Entender por que eles funcionam é o que separa alguém que instala o Argo CD de alguém que realmente o usa bem. O Argo CD é um controller do Kubernetes. Ele roda dentro do seu cluster como um conjunto de pods — um servidor, um servidor de repositórios, um controller de aplicações e alguns serviços de suporte. Uma vez instalado, você o aponta para um repositório Git e diz: "Este diretório contém o estado desejado da minha aplicação. Monitore-o." A partir desse momento, o Argo CD opera em um loop de reconciliação contínuo:

1. Observar — Consultar o repositório Git em busca de mudanças (ou receber notificações via webhook)
2. Comparar — Calcular a diferença entre o estado desejado no Git e o estado atual no cluster
3. Agir — Se diferirem, alertar você (sync manual) ou aplicar automaticamente as mudanças (auto sync) O terceiro passo é onde a mágica acontece. Com auto-sync habilitado, o fluxo de trabalho se torna:

Push para Git → Argo CD detecta mudança → Deploy automático → Auto-repara se drift ocorrer

Nenhum pipeline CI/CD disparando uma etapa de deploy. Nenhum humano rodando comandos. Você faz push do código e o cluster converge para corresponder. O ciclo de feedback é tão rápido que mudou completamente a forma como eu penso sobre deployments. Isso é o que tornou tudo concreto para mim: fiz push de uma atualização de Helm chart para meu repositório infrawhisper às 23:15. Às 23:15 e cerca de oito segundos, o Argo CD já tinha sincronizado a mudança e os novos pods estavam sendo implantados. Eu nem saí do meu editor de código. A mensagem de commit apareceu no dashboard do Argo CD — feat(deploy): add Argo CD application manifest for GitOps deployment — e o status de sync dizia "Sync OK." Esse nível de imediatismo faz deploys manuais parecerem enviar instruções de deployment por pombo-correio. Mais uma coisa sobre o modelo mental. O Argo CD não apenas faz deploy. Ele monitora ativamente o drift. Se alguém (ou algo) mudar o estado do cluster fora do Git — um kubectl edit manual, um script não autorizado, uma exclusão acidental — o Argo CD detecta a diferença e a corrige. O cluster se auto-repara. Vou provar que isso funciona com um teste ao vivo mais adiante neste post. Mas primeiro, vamos colocá-lo para rodar.

A configuração completa: Argo CD no Docker Desktop Kubernetes

Pré-requisitos — O que você precisa antes de começar

Você precisa de exatamente duas coisas:

• Docker Desktop com Kubernetes habilitado (Configurações → Kubernetes → Enable Kubernetes → Apply & Restart). Estou rodando Docker Desktop no macOS, mas os passos são idênticos no Windows e Linux.
• kubectl configurado e apontando para seu cluster Docker Desktop. Verifique com:

kubectl config current-context
# Deve retornar: docker-desktop

Se você vir um contexto diferente, mude com kubectl config use-context docker-desktop. Você não quer instalar o Argo CD acidentalmente em um cluster de produção. Me pergunte como sei que vale a pena verificar isso. É isso. Não é necessário Helm para a instalação básica. Sem conta de provedor cloud. Sem load balancer. O Kubernetes integrado do Docker Desktop é suficiente.

Passo 1 — Instalar o Argo CD no seu cluster

Dois comandos. O primeiro cria um namespace dedicado. O segundo baixa os manifestos oficiais do Argo CD e instala tudo.

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

Isso instala o Argo CD v3.3.4 (o release estável de março de 2026), que inclui hooks PreDelete, atualização de token OIDC em segundo plano, controles RBAC aprimorados e integração com KEDA. O manifesto implanta vários componentes no namespace argocd:

• argocd-server — O servidor API e a interface web
• argocd-repo-server — Clona e processa seus repositórios Git
• argocd-application-controller — O mecanismo de reconciliação que monitora drift
• argocd-redis — Camada de cache
• argocd-dex-server — Autenticação SSO (opcional para configurações locais) Aguarde cerca de 60-90 segundos para todos os pods alcançarem o estado Running. Você pode acompanhá-los subindo:

kubectl get pods -n argocd -w

Quando você vir cinco ou seis pods mostrando 1/1 Running, está pronto para o próximo passo. E o próximo passo é aquele que me travou por bons vinte minutos.

Passo 2 — Remover NetworkPolicies (A armadilha do Docker Desktop)

Este é o passo que nenhum guia de "início rápido" mencionou. Instalei o Argo CD, tentei acessar a UI e não obtive nada. Connection refused. Timeout. Os pods estavam rodando, o serviço existia, mas o port-forwarding simplesmente... não funcionava. Depois de vinte minutos verificando seletores de serviço e logs de pods, encontrei o problema: o Argo CD vem com recursos NetworkPolicy que restringem o tráfego entre seus componentes. Em um cluster real com um plugin CNI que suporta NetworkPolicies (Calico, Cilium, etc.), funcionam perfeitamente. No networking integrado do Kubernetes no Docker Desktop? Quebram tudo silenciosamente. O CNI padrão do Docker Desktop não aplica NetworkPolicies, mas as policies ainda são criadas e podem interferir na descoberta de serviços de maneiras sutis. A solução é simples:

kubectl delete networkpolicies --all -n argocd

É isso. Um comando. Vinte minutos da minha vida que não vou recuperar. Estou escrevendo isso para que você não perca os mesmos vinte minutos.

Depois de executar isso, o port-forwarding funciona imediatamente. Se você está rodando um cluster real com Calico ou Cilium, pule este passo — você quer manter essas policies.

Passo 3 — Acessar o dashboard do Argo CD

Agora exponha o servidor Argo CD para sua máquina local:

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

Abra seu navegador e navegue até https://localhost:8443. Você receberá um aviso de certificado — é esperado para um certificado autoassinado no localhost. Clique para continuar. Você deve ver a tela de login do Argo CD. Limpa. Minimalista. Aquela interface escura que sinaliza "esta é uma ferramenta séria."

Passo 4 — Obter suas credenciais de acesso

O nome de usuário padrão é admin. A senha inicial é gerada automaticamente e armazenada como um secret do Kubernetes. Extraia-a com:

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

Copie essa saída — é sua senha temporária. Faça login com admin e a senha decodificada. Dica profissional: Mude essa senha imediatamente após o primeiro login, especialmente se alguém mais tiver acesso à sua rede. Em um ambiente de desenvolvimento local é menos crítico, mas construir bons hábitos importa. Você pode mudá-la pela CLI do Argo CD ou pela UI em User Info → Update Password. Neste ponto, você tem uma instalação do Argo CD totalmente funcional rodando no seu cluster Kubernetes local. O dashboard está vazio — nenhuma aplicação ainda. Isso muda agora.

Passo 5 — Criar seu manifesto de Application

É aqui que o Argo CD se conecta ao seu repositório Git e começa a gerenciar seus deployments. Você precisa de um manifesto Application — um recurso personalizado do Kubernetes que diz ao Argo CD o que monitorar e onde fazer deploy. Aqui está o manifesto que usei para meu projeto infrawhisper:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-repo.git
    targetRevision: main
    path: deploy/helm/my-app
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Deixe-me explicar o que cada seção faz, porque entender esses campos economiza horas de depuração depois: source — Onde o Argo CD deve procurar seus manifestos:

• repoURL: Seu repositório Git (repos públicos funcionam imediatamente; repos privados precisam de credenciais configuradas nas configurações do Argo CD)
• targetRevision: Qual branch acompanhar. Eu uso main, mas você pode apontar para qualquer branch, tag ou SHA de commit
• path: O diretório dentro do repo que contém seus manifestos Kubernetes ou Helm chart
• helm.valueFiles: Se você está usando Helm (eu estava), isso especifica qual arquivo de valores aplicar destination — Onde o Argo CD deve fazer deploy:
• server: A URL do servidor API do Kubernetes. https://kubernetes.default.svc significa "faça deploy no mesmo cluster onde o Argo CD está rodando." Para configurações locais, é sempre o que você quer.
• namespace: O namespace destino para os recursos da sua aplicação syncPolicy — Como o Argo CD deve se comportar:
• automated: Habilita auto-sync. Sem isso, você teria que clicar manualmente em "Sync" na UI toda vez
• prune: true: Se você remover um recurso do Git, o Argo CD o remove do cluster. Sem isso, manifestos deletados deixam recursos órfãos
• selfHeal: true: Este é o grande. Se alguém ou algo mudar o estado do cluster fora do Git, o Argo CD reverte. Seu cluster sempre corresponde ao Git.
• CreateNamespace=true: O Argo CD criará o namespace destino se ele não existir Salve isso como application.yaml no diretório do seu projeto. Ajuste repoURL, path e namespace para corresponder à sua configuração real.

Passo 6 — Fazer deploy e assistir à mágica

Aplique o manifesto:

kubectl apply -f application.yaml

Agora mude para seu dashboard do Argo CD em https://localhost:8443. Em questão de segundos, você deve ver sua aplicação aparecer. O Argo CD começa a sincronizar imediatamente — clonando seu repo, renderizando o Helm chart (ou manifestos simples), e aplicando os recursos ao seu cluster. Para meu projeto infrawhisper, o dashboard acendeu com toda a topologia da aplicação: api-server rodando 3 pods, dashboard com 2 pods, ai-engine com 2 pods, stream-processor com 2 pods, collector com 2 pods, mais o infrawhisper-agent e o controlador ingress. Tudo visível em uma visualização de rede. O hash do commit 776a48f do meu último push estava ali na UI, com a mensagem de commit que eu tinha escrito minutos antes.

A lista de containers do Docker Desktop contava a mesma história de outro ângulo — 38 containers rodando, com os componentes do argocd ao lado dos meus pods de aplicação: ai-engine, api-server, clickhouse, collector, dashboard, kafka, postgres, redis, stream-processor. Uma plataforma de dados completa rodando localmente, gerenciada inteiramente via Git.

Essa é a configuração. Seis passos, menos de dez minutos. Mas a configuração é apenas a fundação. A verdadeira pergunta é: funciona realmente como a documentação promete? Rodei três testes para descobrir.

O teste de auto-reparação: Deletando um pod de propósito

Aqui está o teste que rodei para provar que a auto-reparação funciona em um cluster local. Eu tinha meu componente dashboard do infrawhisper rodando com 2 pods réplica. Um pod específico — dashboard-75fd8b8ddb-55x9h — estava rodando saudável havia 11 dias. Estável, servindo tráfego, fazendo seu trabalho. Eu o matei.

kubectl delete pod dashboard-75fd8b8ddb-55x9h -n my-app

Então observei. Não o dashboard do Argo CD — observei o terminal. Em seis segundos:

• ANTES: dashboard-75fd8b8ddb-55x9h — Running, Idade: 11 dias
• DELETADO: Pod terminado
• DEPOIS: dashboard-75fd8b8ddb-lt5bn — Running, Idade: 6 segundos Um pod novinho, nome diferente, mesma especificação. O controller ReplicaSet do Kubernetes cuidou da substituição imediata (isso é comportamento padrão do Kubernetes). Mas aqui está a parte que importa: o loop de reconciliação do Argo CD confirmou que o estado do cluster ainda correspondia ao estado desejado no Git. Se a exclusão do pod tivesse causado drift no deployment geral em relação à definição do Git — digamos, se alguém tivesse reduzido manualmente o número de réplicas — o Argo CD também teria detectado e corrigido isso. Isso não é resiliência hipotética. É mensurável. Vi acontecer no meu laptop, em um cluster local, com ferramentas que você pode instalar em dez minutos. A implicação mais profunda levou um dia para ser absorvida. Com auto-reparação habilitada, seus manifestos de deployment no Git não são apenas arquivos de configuração. São um contrato. Uma promessa sobre como o cluster deve estar a todo momento. Quebre o contrato manualmente, e o sistema o aplica automaticamente. Essa mudança de pensamento — de "eu faço deploy das coisas" para "eu declaro coisas e o sistema as mantém" — é o cerne do GitOps. E a sensação é completamente diferente quando você experimenta isso em primeira mão.

Detecção de drift: O guardião silencioso

O teste de auto-reparação cobre exclusões acidentais. Mas e as mudanças manuais intencionais? O tipo que acontece quando alguém roda kubectl edit deployment para "consertar algo rapidamente" em produção às 3 da manhã? Testei isso escalando manualmente meu deployment api-server de 3 réplicas para 1:

kubectl scale deployment api-server --replicas=1 -n my-app

Por cerca de quinze segundos, o cluster teve 1 pod api-server em vez dos 3 definidos no meu repositório Git. Então o loop de reconciliação do Argo CD detectou o drift, comparou o estado atual com o Git e escalou de volta para 3. Sem alarme. Sem intervenção manual. O dashboard do Argo CD mostrou brevemente a saúde do app como "Degraded" (o que é preciso — rodar menos réplicas do que o desejado é degradado), depois voltou para "Healthy" quando a reconciliação foi concluída. Esse é o comportamento que torna o GitOps transformador para equipes. Ele não apenas previne problemas — os corrige ativamente. E cria uma trilha de auditoria. Cada operação de sync aparece no histórico do Argo CD. Você pode ver exatamente quando o drift ocorreu e quando foi corrigido. Tente conseguir isso com kubectl apply.

Auto-Sync: Push para Git, assista ao deploy

O terceiro teste foi o mais simples e o mais satisfatório. Alterei um valor no values.yaml do meu Helm chart — aumentei a contagem de réplicas do dashboard de 2 para 3 — commitei e fiz push para main. Eu tinha o dashboard do Argo CD aberto no navegador e meu terminal rodando kubectl get pods -n my-app -w lado a lado. Em cerca de quinze segundos após o push, o Argo CD detectou o novo commit, baixou o chart atualizado, renderizou os manifestos e aplicou a mudança. Um terceiro pod de dashboard começou a subir enquanto eu assistia. O status de sync no dashboard atualizou para mostrar o novo hash do commit. A mensagem de commit que eu tinha acabado de escrever estava ali na UI. Sem pipeline. Sem configuração de webhook. Sem script de deploy. Fiz push do código e o cluster mudou. Essa é a promessa do GitOps, e em um cluster Docker Desktop local rodando Argo CD v3.3.4, ela foi entregue exatamente como anunciado.

O que o Argo CD acerta — E onde é honesto

Depois de rodar essa configuração por vários dias no meu projeto infrawhisper, aqui está minha avaliação honesta. O que é genuinamente impressionante:

• O dashboard sozinho já vale a instalação. Ver toda a topologia da sua aplicação — cada deployment, serviço, pod e ingress — em um mapa visual é algo que o kubectl nunca vai te dar. Para meu projeto infrawhisper com seus mais de doze componentes, isso foi de "seria legal ter" para "como eu trabalhava sem isso" em cerca de três horas.
• A velocidade de sync é real. Eu esperava minutos. Recebi segundos. O atraso entre fazer push para o Git e ver a mudança ao vivo no cluster foi consistentemente abaixo de 20 segundos na minha configuração local.
• Rollback é um clique. O Argo CD mantém um histórico de cada sync. Se um deployment der errado, você clica em "Rollback" e seleciona um commit anterior. O cluster reverte. Tente fazer isso com kubectl apply e uma reza.
• A renderização de Helm chart é feita para você. Não precisei rodar helm template ou helm install localmente. O repo-server do Argo CD renderiza o chart e aplica a saída. Isso significa que seu repositório Git só precisa do código-fonte do chart — o Argo CD cuida do resto. O que eu gostaria que alguém tivesse me dito:
• O overhead de recursos não é trivial. No Docker Desktop, os componentes do Argo CD adicionaram aproximadamente 500MB-700MB de uso de RAM e vários núcleos de CPU de atividade em segundo plano. Em uma máquina moderna, está tranquilo. Em um laptop mais antigo, você vai sentir. Meu Docker Desktop já estava rodando 38 containers para o stack do infrawhisper — adicionar os pods do Argo CD por cima empurrou o uso total de memória para mais de 8GB.
• Repos privados precisam de configuração adicional. Se seu repositório Git é privado (a maioria é), você precisa configurar credenciais de repositório nas configurações do Argo CD. Isso envolve uma chave SSH, um token de acesso pessoal ou um GitHub App. A documentação oficial cobre isso bem, mas é um passo extra que os guias de "instalação com dois comandos" convenientemente pulam.
• O fluxo da senha inicial do admin é desajeitado. Decodificar Base64 de um secret do Kubernetes para obter sua primeira senha funciona, mas não é uma boa experiência de desenvolvedor. Adoraria ver um assistente de configuração interativo para instalações locais.
• NetworkPolicies no Docker Desktop são uma verdadeira perda de tempo. Já cobri isso nos passos de configuração, mas vale a pena repetir: se você está rodando no Docker Desktop e as coisas não conectam, delete as NetworkPolicies primeiro. Esse único problema provavelmente causa mais configurações locais do Argo CD abandonadas do que qualquer bug real. Se você prefere que alguém construa esse tipo de infraestrutura do zero — clusters Kubernetes, pipelines GitOps, todo o stack de engenharia de plataforma — eu aceito projetos de DevOps e engenharia cloud. Você pode ver o que construí em fiverr.com/s/EgxYmWD.

Onde isso se encaixa em um fluxo de trabalho real

Rodar Argo CD localmente não é apenas um exercício de aprendizado. É a primeira etapa de um fluxo de trabalho que escala diretamente para produção. Esta é a progressão que planejo para meu projeto infrawhisper: Etapa 1 (onde estou agora): Cluster Docker Desktop local com Argo CD gerenciando deployments Helm. Perfeito para desenvolvimento, testar comportamentos de sync e validar manifestos antes que toquem um cluster real. Etapa 2: Mover os mesmos manifestos — sem alterações — para um cluster de staging no AWS EKS ou um cluster autogerenciado. O manifesto Application do Argo CD permanece idêntico. Só o destination.server muda. Etapa 3: Deployment em produção com Argo CD gerenciando múltiplos ambientes através de ApplicationSets. Mesmo repositório Git, diferentes arquivos de valores por ambiente, Argo CD cuidando do rollout para cada um. A percepção-chave: o manifesto Application que escrevi no passo 5 deste guia não muda entre as etapas. O Helm chart não muda. A política de sync não muda. Estou construindo o fluxo de produção agora, no meu laptop, com as mesmas ferramentas que usarei quando o infrawhisper entrar em produção. Isso não é um benefício secundário do Argo CD local — é o benefício principal. Engenheiros de plataforma agora representam 37% dos usuários do Argo CD segundo a pesquisa CNCF, e é exatamente por isso. Os padrões que você estabelece localmente se transferem diretamente para produção. Não existe um passo de "reescrever o pipeline de deployment" quando você está pronto para lançar.

As cinco coisas que o Argo CD te dá que o kubectl apply nunca vai dar

Depois de viver com essa configuração, consigo articular exatamente o que mudou. Não em termos abstratos — em termos concretos de fluxo de trabalho diário: 1. Auto Sync elimina a etapa de deploy completamente. Push para Git. Vá embora. O cluster se atualiza. Isso parece pouco até você perceber quantas vezes por dia roda kubectl apply. Para mim, eram 15-20 vezes durante desenvolvimento ativo. Cada uma é uma troca de contexto, uma janela de terminal, uma chance de aplicar o manifesto errado no namespace errado. Tudo eliminado. 2. Auto-reparação pega erros que você nunca notaria. Exclusões acidentais de pods. Scripts não autorizados. Autoescaladores mal configurados. O Argo CD detecta drift e o corrige. No meu stack infrawhisper com mais de 10 microsserviços, isso não é um luxo — é a diferença entre um ambiente local estável e um que apodrece lentamente. 3. Detecção de drift cria responsabilidade. Cada mudança manual é revertida e registrada. Isso é segurança e higiene operacional em um só. Você pode ver quem (ou o quê) mudou o cluster, quando, e como o Argo CD corrigiu. 4. O dashboard visual substitui uma dúzia de comandos kubectl. Status de pods, contagem de réplicas, health checks, histórico de sync, topologia da aplicação — tudo em uma aba do navegador. Antes eu rodava kubectl get pods, kubectl get svc, kubectl describe deployment e kubectl logs em sequência rápida apenas para entender o estado do meu cluster. Agora dou uma olhada no dashboard do Argo CD. 5. Rollback se torna um único clique. Não "encontrar o último commit funcional, fazer checkout do manifesto, aplicar, verificar se funcionou." Um clique. Selecionar o commit. Pronto. Para um projeto como o infrawhisper com serviços interdependentes, só isso justifica a configuração.

O que eu faria diferente da próxima vez

Se eu fosse configurar tudo isso do zero de novo, três coisas mudariam: Eu instalaria a CLI do Argo CD desde o início. A UI web é ótima para visualização, mas a CLI (argocd) é mais rápida para gerenciar aplicações, sincronizar e verificar status pelo terminal. Não a instalei inicialmente porque queria manter a configuração mínima, e me arrependi em menos de um dia. Instale com:

brew install argocd

Eu usaria ApplicationSets desde o dia um. Meu projeto infrawhisper tem um único manifesto Application, mas conforme adiciono mais ambientes (staging, produção), vou precisar de um Application por ambiente. ApplicationSets permitem criar templates de recursos Application — uma definição que gera múltiplos Applications baseados em parâmetros. Começar com esse padrão cedo economiza uma migração depois. Eu configuraria as credenciais do repositório imediatamente. Comecei com um fork de repo público para testes, depois mudei para meu repo privado real. A etapa de configuração de credenciais interrompeu meu fluxo. Configure primeiro, mesmo que seu repo seja atualmente público. Seu eu do futuro vai agradecer.

Primeiros passos: O checklist de dez minutos

Aqui está a versão condensada. Se você leu tudo acima e só quer os passos em uma tela:

# 1. Verifique seu contexto Kubernetes
kubectl config current-context  # Deve ser: docker-desktop
# 2. Instale o Argo CD
kubectl create namespace argocd
kubectl apply -n argocd -f \
  https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 3. Aguarde os pods (cerca de 60-90 segundos)
kubectl get pods -n argocd -w
# 4. Remova as NetworkPolicies (apenas Docker Desktop!)
kubectl delete networkpolicies --all -n argocd
# 5. Port-forward a UI
kubectl port-forward svc/argocd-server -n argocd 8443:443
# 6. Obtenha a senha de admin
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d
# 7. Login em https://localhost:8443 (admin + senha decodificada)
# 8. Aplique seu manifesto Application
kubectl apply -f application.yaml

Oito comandos. Menos de dez minutos. Um pipeline GitOps totalmente funcional rodando no seu laptop. O Argo CD suporta Helm charts, Kustomize, Jsonnet e manifestos YAML simples — então qualquer que seja seu formato de deployment atual, ele se conecta sem reescrever nada. Para meu projeto infrawhisper, usei Helm porque o chart já estava estruturado para deployments parametrizados. Mas se você tem um diretório de manifestos YAML crus, simplesmente aponte o source.path do Application para esse diretório e remova a seção helm. O Argo CD resolve o resto.

Perguntas frequentes

O Argo CD funciona com o Docker Desktop Kubernetes?

Sim. O Argo CD roda no Kubernetes integrado do Docker Desktop com um workaround necessário: delete as NetworkPolicies padrão no namespace argocd, já que o CNI do Docker Desktop não as trata corretamente. Depois disso, todos os recursos — auto-sync, auto-reparação, detecção de drift e o dashboard web — funcionam de forma idêntica aos clusters hospedados na nuvem.

Quanta RAM o Argo CD usa em um cluster local?

Espere 500MB-700MB de RAM adicional para os componentes do plano de controle do Argo CD (server, repo-server, application-controller, redis, dex). Em uma máquina com 16GB+ de RAM, é negligenciável. Em máquinas com 8GB rodando outras cargas de trabalho pesadas, pode ser necessário ajustar os limites de recursos nos manifestos do Argo CD.

O Argo CD pode fazer deploy a partir de um repositório Git privado?

Sim, mas você precisa configurar credenciais de repositório nas configurações do Argo CD primeiro. As opções incluem chaves SSH, tokens de acesso pessoal ou GitHub Apps. Configure isso pela UI do Argo CD (Settings → Repositories) ou pela CLI argocd antes de criar seu manifesto Application.

O que acontece se eu mudar algo manualmente no cluster?

Com selfHeal: true na política de sync do seu Application, o Argo CD detecta o drift e reverte automaticamente o cluster para corresponder ao Git. O dashboard mostra brevemente a aplicação como "OutOfSync" ou "Degraded," depois a corrige dentro do próximo ciclo de reconciliação (tipicamente menos de 30 segundos). O evento de drift é registrado no histórico de sync para auditoria.

A configuração local do Argo CD é igual à de produção?

Quase idêntica. O manifesto Application, as políticas de sync e a configuração do Helm chart se transferem diretamente para um cluster de produção. As únicas mudanças são a URL destination.server (apontando para seu cluster de produção em vez de kubernetes.default.svc) e os arquivos de valores específicos por ambiente. Este é um dos argumentos mais fortes para começar localmente — você constrói padrões de produção desde o dia um.

Vamos trabalhar juntos

Procurando construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tecnológica? Adoraria ajudar.

• Fiverr (builds personalizados e integrações): fiverr.com/s/EgxYmWD
• Portfolio: mejba.me
• Ramlit Limited (soluções empresariais): ramlit.com
• ColorPark (design e branding): colorpark.io
• xCyberSecurity (serviços de segurança): xcybersecurity.io