Próximos passos com Atlantis

Depois de dois longos anos, é hora de reviver essa série de como continuar sua jornada com automação de infraestrutura como código. Em dois anos, muita coisa mudou, aprendi muito usando Atlantis praticamente toda dia, então espero fechar esse post e em breve terminar a série com um resumão e minhas experiências com Atlantis e Terraform.

Nesse post, abordarei um pouco sobre instalação e configuração e integração com GitHub.

Iniciando

Existem alguns modos de instalação, isso vai depender muito de onde você roda sua infraestrutura. Tome cuidado com anti-patterns, aqui vale pensar da seguinte forma "O que vem primeiro? O ovo ou a galinha?". Por isso, pense bem onde você vai subir e rodar sua instância de Atlantis.

Atualmente (Julho de 2023) existem as seguintes formas de você fazer deploy do Atlantis. Vou deixar links abaixo para cada uma delas:

• Helm Chart
• Manifestos Kubernetes
• Kustomize
• OpenShift
• AWS Fargate
• Google Kubernetes Engine
• Google Compute Engine
• Docker
• Azure
• A forma como você quiser

Essa parte vai depender de como você ou seu time vão querer suportar o Atlantis. A minha dica é, se é um projeto greenfield, comece com uma EC2, AWS Fargate, Google Cloud Run ou uma VM no GCE (Google Compute Engine) e depois pense melhor onde rodar. Abordarei mais sobre patterns e anti-patterns no próximo post.

Instalação

Independente de onde você for fazer deploy do Atlantis, a configuração é igual para qualquer uma delas. O que muda a partir daqui é, com qual Git provider você quer integrar o Atlantis.

Os providers suportados são:

• GitHub
• GitLab
• Bitbucket Cloud
• Bitbucket Server
• Azure DevOps

Como mencionei anteriormente, faremos a configuração passo a passo com GitHub.

O que você vai precisar ter para os próximos passos é basicamente a URL externa do Atlantis. Vou falar sobre segurança em um próximo post, mas isso vai também depender de sua arquitetura.

Se preparando

Como mencionado no último post, você interage com o Atlantis através de eventos de Pull Request (ou Merge Request no GitLab). Para isso, o Atlantis precisa receber webhooks do seu Git provider para que ele funcione.

De uma forma básica, webhook é uma requisição HTTP que é enviada por um evento a partir de um sistema para outro com um payload com alguns dados. Para saber mais sobre Webhooks, leia aqui.

Uma boa estratégia aqui é criar uma secret para o webhook. Essa secret pode ser criada com qualquer gerador de string e deve ser maior que 24 caractéres. Você pode criar com bash utilizando o comando echo | md5sum | head -c 32; echo; Após gerar salve a secret, você precisará dela mais pra frente.

Outro passo importante é criar um usuário no GitHub específico (ou utilizar algum já existente) para o Atlantis. Mesmo que a documentação trate como opcional, eu recomendo. Você também pode utilizar um GitHub App.

Com esse usuário criado, crie um Personal Access Token com permissões apenas para repo. Também é recomendável que esse token expire de tempos em tempos.

A partir daqui você já deve estar com o Atlantis rodando e acessível via UI na porta 4141 ou na porta que você expôs no Load Balancer.
Se você tem dúvidas de como subir, me chama no Telegram em @brunopadz ou comenta no post e a gente bate um papo.

No GitHub, há duas possibilidades de integração do Atlantis. Ou a nível de organização ou a nível repositório. O processo é o mesmo para ambos.

1. Adicione um Webhook, no campo Payload URL coloque https://URL_DO_ATLANTIS/events.
2. No Content-type coloque application/json.
3. No campo Secret cole a secret gerada anteriomente para o Webhook. Se você está criando um Webhook por repositório, a secret deverá ser a mesma.
4. Selecione Let me select individual events e selecione:
   • Pull request reviews
   • Pushes
   • Issue comments
   • Pull Requests
5. Deixe o checkbox Active marcado.

Autenticação com cloud provider

O Atlantis funciona basicamente executando os comandos terraform plan e terraform apply. Assim como você roda o Terraform da sua máquina, o Atlantis precisa de credenciais para se comunicar com cloud providers.

Fica a seu critério como realizar a autenticação. É possível fazer via ENV VARs, EC2 Roles (no caso da AWS) ou GCE Instance Service Accounts no Google.

Dica: Para se integrar com múltiplas contas da AWS, é recomendável fazer assume roles. Mais infos sobre isso no próximo post da série.

Na AWS recomendo utilizar EC2 Roles. Fica fácil de utilizar tanto no Fargate, quanto no Kubernetes (com IRSA) ou em EC2s.

Configurando o Atlantis

Existem 3 formas de configurar o Atlantis:

1. Através de flags no comando atlantis server
2. Utilizando a flag --repo-config para controlar o comportamento do Atlantis em cada repositório e definir o que usuários podem configurar no atlantis.yaml
3. Utilizando arquivos atlantis.yaml na raíz dos repositórios que possuem código em Terraform

Dica: Existe uma precedência para carregar as configurações. A ordem é:

• Flags
• ENV VARs
• Arquivos de configuração

Como estamos configurando para integração com GitHub, o mínimo de configurações necessárias são as seguintes flags ou ENV VARS:

• --gh-user ou ATLANTIS_GH_USER
• --gh-token ou ATLANTIS_GH_TOKEN
• --gh-webhook-secret ou ATLANTIS_GH_WEBHOOK_SECRET
• --repo-allowlist ou ATLANTIS_REPO_ALLOWLIST

Exemplo:

# Usuário do GitHub que irá fazer os comentários nas Pull Requests
--gh-user=atlantis-ci-user \
# Personal Access Token do usuário "atlantis-ci-user"
--gh-token=abcdefg123456xyz1337 \
# Secret criada para o Webhook
--gh-webhook-secret=abcdefg123456xyz1337abcdefg123456xyz1337 \
# List de quais repos que o Atlantis pode rodar dentro de uma organização
--repo-allowlist='github.com/minha-org/*'

Com essas configurações o Atlantis está pronto para receber os webhooks vindos do GitHub. Para testar, abra uma Pull Request em qualquer repositório que contenha código em Terraform e que esteja na Allow list da configuração.

Nessa mensagem, o Atlantis vai mostrar o output do terraform plan e você pode interagir com ele através de um comentário na Pull Request.

Basicamente, todo comentário é feito com atlantis ao invés de terraform. Para todos os possíveis comandos, consulte a documentação oficial ou atlantis help. Alguns exemplos além do plan e apply são:

• atlantis import para importar recursos no state
• atlantis state rm para remover recursos do state

No próximo post, trarei alguns temas como boas práticas e anti-patterns ao utilizar o Atlantis.

Até lá!