Usando o Argo CD para implementar a abordagem GitOps nos clusters Kubernetes

Atualizado em: 31/05/2024

Sobre o GitOps

GitOps é uma estrutura operacional que utiliza as melhores práticas da cultura DevOps durante o ciclo de vida das aplicações, tais como: controle de versão, colaboração, conformidade e ferramentas de integração, entrega e deploy contínuo (CI/CD), e as aplica à automação da infraestrutura. Fonte: Gitlab.

Imagine o seguinte cenário: você tem várias alterações a serem aplicadas em diferentes aplicações sendo executadas em diferentes clusters Kubernetes, distribuídos em mais de um cloud provider e/ou no ambiente on-premisse. Para fazer isso, você pode executar de forma manual ou desenvolver um ou mais pipelines. De qualquer forma, neste cenário existe uma grande complexidade e o esforço técnico de um time de operação, além do risco envolvido quando for necessário fazer rollback. Outra preocupação é evitar as divergências entre o que está aplicado no cluster Kubernetes e o que está versionado no git.

Para ajudar na execução de atividades semelhantes a essa, a abordagem GitOps trata a infraestrutura como código tendo as informações versionadas em um ou mais repositórios git, tratando-os como fonte da verdade e faz uso de ferramentas para aplicar continuamente as mudanças a partir de um ponto central.

Para saber informações sobre os benefícios, vantagens e desvantagens dessa abordagem, recomendo a leitura dos posts a seguir:

Existem várias ferramentas que implementam a abordagem GitOps, entre elas estão: Flux CD, Argo CD, Jenkins-X, Tekton e AWS Code Deploy. Neste tutorial vamos conhecer o Argo CD. Recomendo a leitura das seguintes páginas que falam um pouco mais sobre essas ferramentas:

Se você ainda não sabe o que é Docker, Kubernetes ou mesmo o Git, recomendo a leitura dos links a seguir.

Sobre o Argo CD

Argo CD, é uma ferramenta declarativa que usa a abordagem GitOps para implantar aplicações no Kubernetes.

Achei o Argo CD bem fácil de instalar e configurar. Além disso, ele pode ser usado para gerenciar várias aplicações em diferentes clusters Kubernetes a partir de um único ponto. Ele pode se conectar a repositórios git públicos e privados, é gratuito, tem o código fonte aberto, é um projeto incubado pela CNCF, possui uma interface web de visualização e gerenciamento dos recursos, mas também pode ser configurado via linha de comando.

Para saber mais informações sobre o Argo CD acesse os links que estão nas referências, no fim deste tutorial.

Neste tutorial você aprenderá a instalar o Argo CD no Kubernetes. Em seguida, você configurará o Argo CD para extrair arquivos de configuração das aplicações a partir de um repositório público no GitHub e verá o Argo CD aplicando as mudanças no Kubernetes.

Requisitos

Para a execução deste tutorial, partirei da premissa que você está usando alguma distribuição GNU/Linux e já tem instaladas as seguintes ferramentas:

Além disso, você precisa ter acesso a 1 ou 2 clusters Kubernetes (sejam eles no ambiente on-premisse, cloud (EKS, GKE ou AKS ou ainda, usando minikube, kind, k0s, microk8s ou k3s).

Instalando o Argo CD

Estando conectado em um cluster Kubernetes, execute os seguintes comandos para instalar o Argo CD:

kubectl create namespace argocd

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

Atenção:
Os manifestos de instalação incluem recursos ClusterRoleBinding que fazem referência ao namespace argocd. Se você estiver instalando o Argo CD em um namespace diferente, certifique-se de atualizar a referência do namespace.

Se preferir, você pode instalar o ArgoCD usando o Helm, seguindo as instruções da página: https://artifacthub.io/packages/helm/argo/argo-cd

Existem várias formas de acessar a interface web do Argo CD citadas nesta página. A mais simples é a seguinte:

Port-Forward:

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

Isso criará um encaminhamento da aplicação que executa no cluster Kubernetes na porta 443/TCP para a porta 8443/TCP do host local. Dessa forma, você pode abrir um navegador no endereço: https://localhost:8443. Se você fechar o terminal ou der CRTL+C, o port-forward será encerrado e você perderá o acesso.

Atenção:

Mantenha o port-forward em execução durante todo o tutorial.

O login padrão é admin e uma senha aleatória será gerada. Para obtê-la, execute o seguinte comando em outro terminal:

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

Após fazer o login no Argo CD, altere a senha no seguinte endereço: https://localhost:8443/user-info?changePassword=true

Após mudar a senha na interface web, você pode remover a secret argocd-initial-admin-secret, que contém a senha inicial com o seguinte comando:

kubectl -n argocd delete secret argocd-initial-admin-secret

Instalando o Argo CD CLI (Command Line Interface)

O Argo CD também pode ser gerenciado pela linha de comando. Para isso, execute os seguintes comandos para instalar o binário:

Na página https://argo-cd.readthedocs.io/en/stable/cli_installation/ existe diferentes forma de instalar o CLI do ArgoCD, mas neste tutorial optarei por instalar usando o comando asdf como gerenciar de pacotes.

Instalando o asdf
ASDF_VERSION="v0.14.0"
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch $ASDF_VERSION

# Adicionando no $HOME/.bashrc
echo ". \"\$HOME/.asdf/asdf.sh\"" >> ~/.bashrc
echo ". \"\$HOME/.asdf/completions/asdf.bash\"" >> ~/.bashrc
source ~/.bashrc 
Fonte: https://asdf-vm.com/guide/introduction.html

Instalando o ArgoCD usando o asdf

VERSION=2.10.4
asdf plugin-add argocd https://github.com/beardix/asdf-argocd.git
asdf list all argocd
asdf install argocd $VERSION
asdf global argocd $VERSION

Fonte: https://github.com/beardix/asdf-argocd

Visualize as opções da linha de comando do argocd:

argocd --help

argocd subcommand --help

Realize a autenticação entre o binário e o servidor com o seguinte comando:

argocd login localhost:8443

Atenção:
As configurações do Argo CD também pode ser declaradas em arquivos YAML e versionadas no Git conforme apresentado neste tutorial: https://medium.com/devopsturkiye/self-managed-argo-cd-app-of-everything-a226eb100cf0 e nesta página da documentação: https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup

Implantando uma aplicação (deploy)

O repositório https://github.com/argoproj/argocd-example-apps possui vários exemplos de aplicações que podem ser implantadas usando o Argo CD. Eu fiz um clone desse repositório em: https://github.com/aeciopires/argocd-example-apps

Implante a aplicação guestbook no mesmo cluster do Argo CD, no namespace myapp a partir do código que está em https://github.com/aeciopires/argocd-example-apps, mais precisamente no diretório guestbook:

kubectl create namespace myapp

argocd app create guestbook \
--repo https://github.com/aeciopires/argocd-example-apps.git \
--path guestbook \
--dest-server https://kubernetes.default.svc \
--dest-namespace myapp

Atenção:
O endereço https://kubernetes.default.svc corresponde a identificação padrão do cluster Kubernetes no qual está implantado o Argo CD. Esse nome sempre é atribuído durante a instalação e você pode obter na interface web do Argo CD em: https://localhost:8443/settings/clusters

Na interface web, você pode visualizar as aplicações criadas no Argo CD a partir do seguinte endereço https://localhost:8443/applications. No caso da aplicação guestbook, o status e outras configurações estarão disponíveis a partir do endereço: https://localhost:8443/applications/guestbook.

Mas vamos continuar utilizando a linha de comando…

Obtenha o status da aplicação usando o seguinte comando:

argocd app get guestbook

Sincronize o código da aplicação no Git com o cluster Kubernetes:

argocd app sync guestbook

Visualize os recursos implantados da aplicação:

kubectl get all -n myapp

Visualize os logs do pod da aplicação:

argocd app logs guestbook

Agora mude alguma informação em um manifest existente no diretório da aplicação guestbook no git ou adicione algum arquivo. Dê commit e faça o push das alterações na branch principal (master ou main).

Visualize as diferenças entre o que está no git e o que está no cluster Kubernetes:

argocd app diff guestbook

Sincronize novamente a aplicação.

argocd app sync guestbook

Observe o histório de mudanças da aplicação:

argocd app history guestbook

Faça um rollback das alterações para o ID de histórico referente ao commit desejado:

argocd app rollback guestbook HISTORY_ID

O que achou?

Observe que foi necessário sincronizar manualmente as alterações no Argo CD para ele pegar do Git e aplicar no Kubernetes. Para deixar esse processo automático para essa aplicação, execute o seguinte comando:

argocd app set guestbook --sync-policy automated

Se precisa desabilitar a sincronização automática, execute o seguinte comando:

argocd app set guestbook --sync-policy none

Curiosidade: obtendo os manifestos YAML da aplicação:

argocd app manifests guestbook

Liste os recursos da aplicação:

argocd app resources guestbook

Implantando uma aplicação helm em outro cluster

Atenção:
Argo CD não tem opinião sobre como os segredos devem ser gerenciados, por exemplo usando helm secrets + sops. Há muitas maneiras de fazer isso e não há uma solução única para todos os casos. Alguns tutoriais dão algumas alternativas e estes são citados nas Referências na seção Argo CD + Sops + Helm Secrets.

Eu criei uma imagem Docker customizada do Argo CD para dar suporte ao sops + helm secrets + helm plugin e adicionei instruções sobre como usar o AWS KMS junto com o sops e criar um secret no Kubernetes relacionada ao arquivo de credenciais de acesso da AWS. Se tiver interesse, acesse este repositório: https://github.com/aeciopires/custom-argocd

Como falei, o Argo CD pode gerenciar muitos clusters a partir de um único ponto. Para testar isso, adicione outro cluster com o seguinte comando:

kubectl config get-contexts -o name

argocd cluster add CONTEXT_NAME

Atenção:
Altere CONTEXT_NAME pelo nome do cluster que você já tem acesso.

Visualize a lista de clusters cadastrados no Argo CD no seguinte endereço: https://localhost:8443/settings/clusters

Implante a aplicação aecio no outro cluster, no namespace aecions a partir do código que está em https://github.com/aeciopires/argocd-example-apps, mais precisamente no diretório kube-pires. :

CLUSTER_URL=CHANGE_HERE

argocd app create aecio \
--repo https://github.com/aeciopires/argocd-example-apps.git \
--path kube-pires \
--release-name aecioapp \
--values values.yaml \
--dest-server $CLUSTER_URL \
--dest-namespace aecions \
--sync-policy auto \
--sync-option CreateNamespace=true

Atenção:
Com o uso da opção –sync-option CreateNamespace=true, o namespace aecions será criado automaticamente se não existir no cluster. Caso contrário o Argo CD faria 5 tentativas (por padrão) para tentar implantar a aplicação sem obter sucesso.

A opção –sync-policy auto faz com que a cada alteração enviada ao Git, as mudanças sejam aplicadas imediatamente.

kube-pires é um helm chart de teste usado para implantar a aplicação aecioapp usando os valores definidos no arquivo kube-pires/values.yaml.

CLUSTER_URL é o endereço interno do cluster que você pode obter na interface web do Argo CD em: https://localhost:8443/settings/clusters

A aplicação aecioapp e aecio são diferentes. A primeira se refere a uma aplicação helm. A segunda é uma aplicação no Argo CD.
Neste caso, a sincronização entre os arquivos do git e o Kubernetes está habilitada para ocorrer de forma automática. Para saber mais sobre os conceitos do Argo CD, acesse a página: https://argo-cd.readthedocs.io/en/stable/core_concepts

Visualize a aplicação na interface web: https://localhost:8443/applications/aecio:

Agora visualize o status da aplicação utilizando a linha de comando:

argocd app get aecio

Visualize os recursos implantados da aplicação:

argocd app resources aecio

Visualize as possíveis diferenças entre o que está no git e o no Kubernetes:

argocd app diff aecio

Mude o número de réplicas no arquivo kube-pires/values.yaml. Faça commit e push das alterações no repositório git.

Visualize as mudanças na interface web do Argo CD.

Atenção:
Por padrão, o Argo CD não impede que alterações manuais sejam realizadas nos recursos e objetos do Kubernetes, para corrigir um incidente por exemplo. Se isso ocorrer, ele não vai substituir as configurações manuais automaticamente.

Você pode vizualizar as diferenças e ajustar o arquivo no git para manter as alterações como código ou substituir as alterações manuais sincronizando sob demanda o código do Git com a aplicação implantada no Kubernetes.

Se você deseja forçar que no Kubernetes execute apenas o que estiver versionado no Git, substituindo imediatamente qualquer alteração manual, então você pode remover a aplicação e criar novamente com os seguintes comandos:

argocd app delete aecio

argocd app create aecio \
--repo https://github.com/aeciopires/argocd-example-apps.git \
--path kube-pires \
--release-name aecioapp \
--values values.yaml \
--dest-server CLUSTER_URL \
--dest-namespace aecions \
--sync-policy auto \
--sync-option CreateNamespace=true \
--self-heal

Ou melhor ainda, você pode alterar as configurações de uma aplicação existente da seguinte forma:

argocd app set aecio --self-heal

Agora qualquer alteração manual nos recursos dessa aplicação no cluster, será imediatamente substituída pelo o que está definido no Git.

Tem muitas opções de sincronização que podem ser consultadas nos links que estão nas referências ao fim do tutorial.

Mude o readnessprobe.path e livenessprobe.path no arquivo kube-pires/values.yaml. Faça commit e push das alterações no repositório git.

Visualize as mudanças na interface web do Argo CD.

Atenção:
Infelizmente, o Argo CD ainda não dá suporte a pegar um helm chart de uma URL e os arquivos de values.yaml e secrets.yaml de um repositório git simulteamente. Hoje ele tenta encontrar o helm chart e o as arquivos de values em um mesmo endereço, o que é muito ruim pensando em configuração em larga escala, quando você precisa usar o mesmo helm chart em diferentes ambientes ou clientes com configurações distintas.

Felizmente, há algumas estratégias sugeridas nesta feature request de 2019: https://github.com/argoproj/argo-cd/issues/2789 e recentemente Kay Reichart abriu um Pull Request implementando uma solução nativa: https://github.com/argoproj/argo-cd/pull/6280. O código está sendo revisado e, em breve, teremos esta funcionalidade disponível.

Remova as aplicações do Argo CD e dos clusters Kubernetes (undeploy):

argocd app delete guestbook

argocd app delete aecio

Remova um cluster do Argo CD com o seguinte comando:

argocd cluster rm CLUSTER_URL

Remova o Argo CD do cluster Kubernetes (undeploy):

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

kubectl delete namespace argocd

O que achou?

Mais informações podem ser obtidas nos links das referências.

Este tutorial mostrou apenas o básico e a parte simples que pode ser feito com o Argo CD. Há muitas funcionalidades e possibilidades que podem ser exploradas e por isso incentivo você a ler e praticar o conhecimento que está publicado nos links das referências. Bons testes e estudos!

Referências

Argo CD:

Argo CD + Sops + Helm Secrets:

Atenção:
Argo CD não tem opinião sobre como os segredos devem ser gerenciados, por exemplo usando helm secrets + sops. Há muitas maneiras de fazer isso e não há uma solução única para todos os casos. Os tutoriais a seguir dão algumas alternativas.

Eu criei uma imagem Docker customizada do Argo CD para dar suporte ao sops + helm secrets + helm plugin e adicionei instruções sobre como usar o AWS KMS junto com o sops e criar um secret no Kubernetes relacionada ao arquivo de credenciais de acesso da AWS. Se tiver interesse, acesse este repositório: https://github.com/aeciopires/custom-argocd

Sync Policy:

Tracking and Deployment Strategies:

Security: