Magalu Cloud for Magalu Cloud

Posted on Sep 2

Integração do ArgoCD com clusters Kubernetes da Magalu Cloud

#magalucloud #cloud #argocd #kubernetes

Em times que trabalham com Kubernetes, é comum enfrentar desafios para garantir que o ambiente de produção esteja sempre sincronizado com os manifestos versionados no Git. Atualizações manuais, falta de rastreabilidade nas mudanças e divergências entre ambientes são apenas alguns dos problemas que colocam em risco a estabilidade das aplicações.

Esse cenário se torna ainda mais complexo quando múltiplos clusters e equipes estão envolvidos, exigindo uma abordagem mais automatizada, segura e auditável para o processo de deploy.

Neste artigo, mostraremos como o ArgoCD pode ser a solução para esses desafios, automatizando a entrega contínua em clusters Kubernetes com base em uma fonte de verdade única: o repositório Git. Você vai aprender como configurar o ArgoCD na Magalu Cloud utilizando Helm, integrar repositórios Git (via HTTPS ou SSH), criar aplicações tanto pela interface quanto por linha de comando, e até utilizar plugins como o ArgoCD Vault Plugin para lidar com segredos de forma segura.

Dependências necessárias

Acesso ao cluster MGC

Para interagir com o cluster Kubernetes provisionado na Magalu Cloud (MGC), é necessário obter o arquivo de configuração de acesso (kubeconfig). Esse arquivo define as credenciais, o endpoint e o contexto necessário para executar comandos kubectl ou gerenciar o cluster com ferramentas como kubie.

O processo começa acessando o console da MGC. No painel de Kubernetes, selecione o cluster desejado e utilize a opção “Download Config” disponível no menu lateral.

Com o arquivo .yaml em mãos, o acesso ao cluster pode ser ativado via terminal usando o seguinte comando:

$ kubie ctx -f /caminho/para/config.yaml

Esse comando define o contexto adequado para que todas as operações subsequentes sejam executadas diretamente no cluster correto. Caso não tenha o kubie instalado, verifique os pré-requisitos mencionados na seção de dependências.

Instalação do ArgoCD com Helm

O ArgoCD é uma ferramenta declarativa de entrega contínua (CD) para Kubernetes. Ele sincroniza o estado do cluster com os manifestos armazenados em repositórios Git, garantindo consistência e controle de versões para os recursos implantados.

A instalação do ArgoCD em um cluster Kubernetes da Magalu Cloud pode ser feita de forma prática utilizando o Helm, uma das abordagens mais recomendadas para esse tipo de setup. Caso prefira outro método de instalação, consulte a documentação oficial do ArgoCD.

Para iniciar, salve o seguinte arquivo em um diretório local e ajuste conforme necessário: https://github.com/argoproj/argo-helm/blob/main/charts/argo-cd/values.yaml

Na maioria dos casos, os valores padrão já são suficientes. Basta configurar o Ingress e o domínio para refletirem o endereço onde o servidor do ArgoCD será exposto. O próprio README do repositório traz informações úteis sobre essas configurações e opções de escalabilidade com suporte à AWS.

Com o arquivo values.yaml ajustado, execute os comandos abaixo no terminal para instalar o ArgoCD no cluster:

$ helm repo add argo https://argoproj.github.io/argo-helm
$ helm install -f /caminho/para/values.yaml argocd argo/argo-cd

Observação: Ao utilizar as configurações padrão do ArgoCD, é criado automaticamente um usuário admin, cuja senha inicial fica armazenada em um Secret no namespace argocd. Essa senha pode ser recuperada com o comando abaixo:

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

Esse usuário deve ser utilizado apenas para o setup inicial. A documentação oficial recomenda configurar outros usuários, com suporte a diferentes métodos de autenticação, como integração com Google, LDAP e SSO.

Caso seja necessário atualizar a instalação do ArgoCD, basta modificar o arquivo values.yaml e executar o comando:

$ helm upgrade -f /caminho/para/values.yaml argocd argo/argo-cd

Como adicionar um repositório Git no ArgoCD? (SSH e HTTPS)

Para que o ArgoCD possa monitorar e sincronizar aplicações a partir de um repositório Git, é necessário configurar esse repositório como fonte de verdade. Essa conexão pode ser feita utilizando HTTPS ou SSH, a depender do controle de acesso e da política de autenticação adotada pelo time.

HTTPS

A autenticação por HTTPS pode ser feita diretamente pela interface do ArgoCD. Basta acessar o painel, navegar até Settings Repositories e utilizar a opção Connect Repo.

Ao informar a URL do repositório (por exemplo, https://github.com/usuario/repositorio.git), o ArgoCD aceitará autenticação anônima ou credenciais via usuário e senha ou token pessoal (PAT), caso o repositório seja privado.

A interface exibe os campos: tipo do repositório (git), nome (example), projeto (default), URL (https://github.com/example/repo.git), além de opções para usuário e senha. No topo, há botões para conectar, salvar como template de credenciais e cancelar.

Esse método é especialmente útil para times que utilizam autenticação centralizada por tokens e desejam evitar a gestão de chaves SSH no ambiente.

SSH

Para conexões mais seguras e controladas, recomenda-se utilizar chaves SSH. Nesse caso, é necessário gerar um par de chaves (ou utilizar um já existente) e registrar a chave pública como Deploy Key no repositório desejado, seja no GitHub, GitLab ou Bitbucket.

No ArgoCD, também via Settings Repositories, selecione a opção Connect Repo using SSH e informe a URL no formato git@github.com:usuario/repositorio.git, além da chave privada correspondente.

A interface mostra os campos: Nome obrigatório (example), Projeto (default), URL do repositório (git@github.com:example/repo.git) e chave privada SSH (<PRIVATE_KEY>). No topo, estão os botões Connect, Save as Credentials Template e Cancel.

O uso de SSH é uma prática comum em ambientes com maior exigência de segurança, já que permite revogação granular de acesso por chave e separação clara entre ambientes.

Com o repositório Git devidamente configurado no ArgoCD, o próximo passo é definir o que será implantado e como essa sincronização acontecerá. É aqui que entra o conceito de Application.

O que é um Application e como criar um?

Um Application no ArgoCD é a representação de um conjunto de recursos Kubernetes que serão sincronizados a partir de um repositório Git. Ele define o destino (cluster e namespace), a origem (repo e caminho) e o método de sincronização.

Nos exemplos abaixo estamos considerando essa estrutura de arquivos com mgc sendo a pasta repositório (importante dizer que é possível combinar estrutura de manifestos com helm charts):

Manifesto

mgc
├── applications # Deploy das aplicações
│   ├── airflow
│   │   ├── manifestos
│   │   │   ├── airflow.yaml
│   │   │   ├── secret.yaml   
│   │   ├── application.yaml
├── initial-addons # Helm charts aplicados manualmente
│   ├── argocd_values.yaml

Helm chart

mgc
├── apps # Deploy das aplicações
│   ├── airflow
│   │   ├── airflow-values.yaml 
│   │   ├── application.yaml
├── initial-addons # Helm charts aplicados manualmente
│   ├── argocd_values.yaml

Via Interface Web (UI)

A maneira mais acessível de criar um Application no ArgoCD é pela interface web, ideal para times em fase inicial de adoção do GitOps. Ao criar uma nova aplicação, você define os parâmetros que o ArgoCD usará para monitorar, sincronizar e aplicar os recursos no cluster:

Application Name: nome da aplicação.
- Project: default (ou outro).
- Sync Policy: Automatic (recomendado para CD).
- Repository URL: Git HTTPS ou SSH.
- Revision: ex: main.
- Path: apps/airflow/
- Cluster URL: geralmente https://kubernetes.default.svc.
- Namespace: default

Após preencher essas informações, a aplicação pode ser criada com um clique no botão Create, e o ArgoCD iniciará o processo de sincronização conforme as configurações definidas.

A interface exibe os botões CREATE e CANCEL no topo.

Na seção GENERAL, aparecem os campos Application Name (preenchido com example-application) e Project Name (default), além da política de sincronização (SYNC POLICY) configurada como Manual.

Entre as opções adicionais estão checkboxes como Set Deletion Finalizer, Skip Schema Validation, Prune Last, Respect Ignore Differences, Replace e Retry, além de configurações à direita como Auto-create Namespace, Apply Out of Sync Only e Server Side Apply. A política de propagação de prune está definida como foreground.

Na seção SOURCE, os campos exibidos são: Repository URL (git@github.com:example/repo.git), Revision (HEAD) e Path (/).

Via CLI (argocd)

Para quem já tem o ArgoCD instalado e deseja automatizar a criação de aplicações ou integrá-la em pipelines, a CLI do ArgoCD é uma ferramenta poderosa. Ela permite registrar novos Applications diretamente via terminal, sem necessidade de interação com a interface web.

Após autenticar-se no servidor do ArgoCD com o comando:

argocd login argocd.example.com

É possível criar uma nova aplicação com o seguinte comando:

argocd app create app-demo \
  --repo https://github.com/user/repository.git \
  --path apps/airflow/ \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default \
  --sync-policy automated

Esse comando define o nome da aplicação (app-demo), o repositório e caminho onde estão os manifestos ou Helm charts, o cluster e namespace de destino, além de ativar a sincronização automática.

Se for necessário aplicar os recursos imediatamente após a criação, basta rodar:

argocd app sync app-demo

Esse fluxo via CLI é especialmente útil em ambientes automatizados, como scripts de provisionamento, pipelines CI/CD ou setup de novos ambientes.

Via Terminal (kubectl + YAML)

A forma mais declarativa de criar aplicações no ArgoCD é utilizando arquivos YAML com o recurso Application. Essa abordagem se alinha totalmente à filosofia GitOps, permitindo que a definição das aplicações seja versionada e aplicada via kubectl, como qualquer outro recurso do Kubernetes.

Essa prática é útil tanto para ambientes automatizados quanto para times que mantêm o controle total da infraestrutura como código.

Abaixo, dois exemplos de Application - um utilizando manifestos Kubernetes e outro com Helm Charts como fonte:

application.yaml usando source GitHub e aplicando manifestos Kubernetes

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
 name: app-demo
spec:
 destination:
   server: https://kubernetes.default.svc
   namespace: default
 source:
   repoURL: git@github.com:usuario/repositorio.git
   path: apps/airflow/manifestos
   targetRevision: main
 project: default
 syncPolicy:
   automated:
     prune: true
     selfHeal: true

application.yaml usando source GitHub e aplicando Helm Charts

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
 name: app-demo
spec:
 destination:
   server: https://kubernetes.default.svc
   namespace: default
 source:
   repoURL: git@github.com:usuario/repositorio.git
   path: charts/minha-app
   targetRevision: main
   helm:
     valueFiles:
       - $values/apps/airflow/airflow-values.yaml
 project: default
 syncPolicy:
   automated:
     prune: true
     selfHeal: true

Após salvar o conteúdo em um arquivo (por exemplo, application.yaml), aplique-o no cluster com o comando:

kubectl apply -f application.yaml

Depois de definir uma aplicação no ArgoCD, apontando origem, destino e regras de sincronização, é comum que os manifestos incluam valores sensíveis, como senhas, tokens ou chaves de API. Manter esses dados seguros e, ao mesmo tempo, alinhados à prática de versionamento, é um dos principais desafios em ambientes Kubernetes.

Para lidar com esse cenário de forma segura e escalável, o ArgoCD oferece suporte ao Vault Plugin (AVP), que permite a injeção dinâmica de segredos diretamente nos manifestos, sem expor essas informações no repositório Git.

AVP Plugin e como utilizar nos manifestos que serão aplicados?

O Vault Plugin (AVP) é uma extensão que permite injetar segredos diretamente nos manifestos a partir de provedores, sem que esses dados fiquem explícitos nos arquivos versionados.

Exemplo de uso nos manifestos

apiVersion: v1
kind: ConfigMap
metadata:
 name: exemplo-configmap
data:
 DB_PASSWORD: <path:secret/data/postgres#password>

Sempre que houver alterações nos segredos utilizados nos manifestos, especialmente quando gerenciados por meio do ArgoCD Vault Plugin, é necessário realizar um Hard Refresh na aplicação correspondente dentro do ArgoCD. Isso garante que os novos valores sejam buscados e aplicados corretamente no cluster, já que o ArgoCD não detecta mudanças em dados externos por padrão.

A interface exibe botões de controle como Details, Diff, Sync, Sync Status, History and Rollback, Delete e Refresh (com opção de Hard Refresh).

O estado da aplicação mostra Healthy, com sincronização marcada como Synced to main (13d61ad) e modo automático habilitado.

A última sincronização foi bem-sucedida para o commit 84ab096, realizada há 7 dias, acompanhada do comentário "feat: nodopaol affinity".

DEV Community