ArgoCD: GitOps para Gerir Kubernetes na PME

O ArgoCD é uma ferramenta de código aberto que implementa o paradigma GitOps para fazer a gestão declarativa de clusters Kubernetes. Em vez de executar comandos kubectl apply manualmente, o ArgoCD monitoriza um repositório Git e sincroniza automaticamente o estado do cluster com o conteúdo desse repositório. Para as PME que já operam em Kubernetes, isto significa implantações reproduzíveis, auditoria completa via histórico do Git e reversão instantânea em caso de erro.

Neste artigo, exploramos a arquitectura do ArgoCD, o processo de instalação, a sincronização de aplicações, a gestão de múltiplos clusters e as boas práticas que uma PME deve adoptar para tirar o máximo proveito desta solução auto-alojada.

Neste artigo

• 1. Introdução — O que é GitOps
• 2. ArgoCD: Arquitectura e Componentes
• 3. Instalação e Configuração Inicial
• 4. Sincronização de Aplicações
• 5. Gestão de Múltiplos Clusters
• 6. Boas Práticas para PME
• 7. Conclusão

1. Introdução — O que é GitOps

GitOps é um paradigma de gestão de infraestrutura onde o Git é a única fonte de verdade (single source of truth). Em vez de descrever o estado desejado do cluster em scripts imperativos ou ferramentas de linha de comando, toda a configuração do sistema é declarada em ficheiros versionados num repositório Git. Um agente automático — neste caso, o ArgoCD — compara continuamente o estado real do cluster com o estado declarado no Git e aplica as diferenças.

Os quatro princípios fundamentais do GitOps, tal como definidos pela OpenGitOps, são:

Para uma PME, o GitOps traz benefícios directos: qualquer alteração passa por revisão (pull request), existe um histórico completo de quem mudou o quê e quando, e uma reversão corresponde simplesmente a um git revert. Não é necessário dar acesso directo ao cluster a cada programador — basta permissão no repositório Git.

2. ArgoCD: Arquitectura e Componentes

O ArgoCD é composto por vários componentes que comunicam entre si para garantir a sincronização entre o Git e o cluster Kubernetes. A arquitectura é modular e todos os componentes executam dentro do próprio cluster (ou num cluster de gestão dedicado).

Componentes principais

Fluxo de funcionamento

O fluxo típico do ArgoCD é o seguinte:

1. Commit no Git — Um programador (ou uma conduta de CI) faz push de uma alteração para o repositório que contém os manifestos Kubernetes.
2. Detecção — O Repo Server detecta a alteração (polling ou webhook) e clona o repositório actualizado.
3. Comparação — O Application Controller compara o estado declarado no Git com o estado real do cluster (live state).
4. Sincronização — Se a política for de sincronização automática, o ArgoCD aplica os manifestos no cluster. Caso contrário, aguarda aprovação manual.
5. Relatório — O estado da sincronização fica visível na interface web e na CLI, incluindo eventuais erros.

3. Instalação e Configuração Inicial

O ArgoCD instala-se no cluster Kubernetes através de manifestos oficiais. O método mais comum é aplicar o manifesto de instalação directamente, que cria o namespace argocd e todos os recursos necessários.

Passo 1 — Instalar o ArgoCD

# Criar namespace e instalar o ArgoCD
kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Passo 2 — Instalar a CLI do ArgoCD

# Descarregar e instalar o binário argocd
curl -sSL -o /usr/local/bin/argocd \
  https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

Passo 3 — Aceder à interface web

Por defeito, o API Server não fica exposto externamente. A forma mais simples de aceder para teste é criar um port-forward:

# Encaminhar a porta do API Server para localhost
kubectl port-forward svc/argocd-server -n argocd 8080:443

# Noutra consola, obter a palavra-passe inicial
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

# Iniciar sessão (utilizador: admin)
argocd login localhost:8080

Passo 4 — Registar o repositório Git

Para que o ArgoCD possa ler os manifestos, é necessário registar o repositório Git que contém a configuração das aplicações:

# Registar repositório público (sem credenciais)
argocd repo add https://github.com/empresa/manifestos-k8s.git

# Registar repositório privado com credenciais
argocd repo add https://github.com/empresa/manifestos-k8s.git \
  --username git-user \
  --password token-github

Passo 5 — Expor o ArgoCD com Ingress

Para uso em produção, convém expor o API Server através de um Ingress com TLS. Um exemplo básico:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  rules:
  - host: argocd.empresa.pt
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              name: https

4. Sincronização de Aplicações

No ArgoCD, uma Application representa uma unidade de implantação — um conjunto de recursos Kubernetes definidos no Git que são sincronizados para um cluster. A sincronização pode ser manual (click-to-sync) ou automática (auto-sync).

Criar uma Application via CLI

argocd app create minha-app \
  --repo https://github.com/empresa/manifestos-k8s.git \
  --path ./producao/minha-app \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --sync-policy automated \
  --auto-prune \
  --self-heal

Criar uma Application via manifesto YAML

A abordagem declarativa (recomendada para produção) consiste em definir a Application como um recurso Kubernetes:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: minha-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/empresa/manifestos-k8s.git
    targetRevision: HEAD
    path: ./producao/minha-app
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Estados de sincronização

Reversão (rollback) instantânea

Uma das maiores vantagens do GitOps é a reversão. Se um commit introduzir um problema, basta reverter o commit no Git e o ArgoCD aplica automaticamente a versão anterior:

# Reverter o último commit no repositório de manifestos
git revert HEAD
git push origin main

# O ArgoCD detecta a alteração e sincroniza automaticamente
# (se auto-sync estiver activo) ou aguarda sincronização manual

# Para forçar sincronização manual imediata
argocd app sync minha-app

5. Gestão de Múltiplos Clusters

Uma funcionalidade essencial do ArgoCD para PME com ambientes de desenvolvimento, homologação e produção é a capacidade de gerir múltiplos clusters a partir de uma única instalação do ArgoCD. Este cluster de gestão pode implantar aplicações em qualquer número de clusters remotos.

Registar um cluster remoto

# Registar cluster remoto usando o contexto actual do kubeconfig
argocd cluster add contexto-producao

# Listar clusters registados
argocd cluster list

Implantar em clusters específicos

Ao criar uma Application, o campo destination.server define qual o cluster de destino. É possível ter múltiplas Applications a apontar ao mesmo repositório Git mas para clusters diferentes:

# Application para desenvolvimento
argocd app create app-dev \
  --repo https://github.com/empresa/manifestos-k8s.git \
  --path ./ambientes/dev \
  --dest-server https://1.2.3.4:6443 \
  --dest-namespace desenvolvimento \
  --sync-policy automated

# Application para produção
argocd app create app-prod \
  --repo https://github.com/empresa/manifestos-k8s.git \
  --path ./ambientes/prod \
  --dest-server https://5.6.7.8:6443 \
  --dest-namespace producao \
  --sync-policy automated

ApplicationSets para múltiplos clusters

O ArgoCD oferece ApplicationSets, que permitem gerar Applications automaticamente para múltiplos clusters a partir de um único modelo. Isto é particularmente útil quando se pretende implantar a mesma aplicação em vários clusters com configurações distintas por ambiente:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: app-multi-cluster
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - cluster: dev
        url: https://1.2.3.4:6443
      - cluster: prod
        url: https://5.6.7.8:6443
  template:
    metadata:
      name: 'app-{{cluster}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/empresa/manifestos-k8s.git
        path: 'ambientes/{{cluster}}'
        targetRevision: HEAD
      destination:
        server: '{{url}}'
        namespace: producao
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

6. Boas Práticas para PME

Separar repositórios de código e de manifestos

Manter os manifestos Kubernetes (YAML, Helm values, Kustomize) num repositório Git separado do código-fonte da aplicação. Isto permite que a conduta de CI construa e publique imagens Docker, enquanto a conduta de implantação (CD) actualiza apenas a referência da imagem no repositório de manifestos.

Usar Kustomize ou Helm para gestão de ambientes

Em vez de manter cópias inteiras de manifestos para cada ambiente (desenvolvimento, homologação, produção), usar Kustomize (integrado nativamente no kubectl) ou Helm para definir uma base comum e sobrepor apenas as diferenças por ambiente. O ArgoCD suporta ambos nativamente.

Activar self-heal em produção

Em produção, o selfHeal: true garante que qualquer alteração manual fora do Git (feita directamente no cluster via kubectl) é automaticamente revertida. Isto evita configuração dispersiva (configuration drift) e mantém o Git como única fonte de verdade.

Proteger o cluster de gestão

O cluster onde o ArgoCD está instalado tem acesso a todos os clusters geridos. Protegê-lo com autenticação forte (SSO via Dex, LDAP ou SAML), RBAC restritivo e cópias de segurança regulares. Em ambientes sensíveis, considerar uma instalação dedicada do ArgoCD num cluster isolado.

Revisão por pares via Pull Requests

Todas as alterações aos manifestos devem passar por um pull request com revisão obrigatória. Isto garante que nenhum programador pode alterar a infraestrutura sem supervisão, a criar um histórico de auditoria completo e rastreável.

Sincronização automática vs. manual

Configurar notificações

O ArgoCD pode enviar notificações para Slack, Microsoft Teams, e-mail ou webhooks quando uma sincronização falha ou um recurso entra em estado degradado. Configurar alertas para o estado das aplicações em produção é essencial para detectar problemas cedo. As notificações fazem parte do core do Argo CD desde a v2.3 — o controlador vem incluído numa instalação normal (com os ConfigMaps argocd-notifications-cm e argocd-notifications-secret criados por omissão) e só o catálogo de triggers/templates precisa de ser aplicado:

# As notificações já vêm integradas no Argo CD (controlador incluído desde a v2.3)
# Instalar o catálogo de triggers e templates:
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/notifications_catalog/install.yaml

# Configurar canal Slack
kubectl edit configmap argocd-notifications-cm -n argocd
# Adicionar:
#   service.slack: |
#     token: $slack-token
#   template.app-deployed: |
#     message: |
#       {{.app.metadata.name}} sincronizada com sucesso

7. Conclusão

O ArgoCD implementa de forma robusta e madura o paradigma GitOps para Kubernetes. Para uma PME, os benefícios são tangíveis: implantações reproduzíveis a partir de um repositório Git, auditoria completa via histórico de commits, reversão instantânea com git revert e gestão centralizada de múltiplos clusters a partir de uma única instalação.

A adopção do GitOps com ArgoCD representa uma mudança cultural tanto como técnica: o Git passa a ser o painel de controlo, e todas as alterações à infraestrutura seguem o mesmo fluxo de revisão que o código da aplicação. Esta abordagem reduz erros manuais, melhora a colaboração entre equipas e cria um registo auditável de todas as mudanças.

A documentação oficial completa está disponível em argo-cd.readthedocs.io e o código-fonte no GitHub do projecto ArgoCD.