Introduction à Atlantis

Photo by timJ from Unsplash

TL;DR Atlantis est un outil open source permettant de collaborer avec l'outil Terraform. En effet, la gestion des différents déploiements Terraform devient vite fastidieuse quand on commence à travailler à plusieurs dans un ou plusieurs projets. Atlantis est l'outil idéal pour mieux gérer cela. Il est compatible avec les principaux gestionnaires de version Git en ligne, à savoir, GitHub, Gitlab et Bitbucket.

Avant d'aller plus loin, n'hésitez pas à prendre connaissance des articles ci-dessous:

Atlantis propose dans sa documentation. Les sections Installing et Configuring permettent de prendre en main l'installation et la configuration d'Atlantis.

Vous trouverez ci-dessous :

  • Installation de Terraform
  • Installation d'Atlantis
  • Configuration d'Atlantis
  • Mise en pratique

Installer Terraform

Pour effectuer l'installation de Terraform sur un environnement linux, il faut tout d'abord commencer par télécharger le package Linux présent sur le site Terraform d'Hashicorp.

Pour télécharger le package Linux 64 bits nous allons copier le lien et utiliser depuis un shell la commande wget ou curl :

wget https://releases.hashicorp.com/terraform/0.12.25/terraform_0.12.25_linux_amd64.zip

A ce jour la version actuelle est la 0.12.25. Vérifiez sur le site la dernière version à jour.

Une fois le package téléchargé vous pouvez le décompresser vers le répertoire terraform avec la commande suivante :

unzip terraform_0.12.25_linux_amd64.zip -d terraform/

Pour finir, ajoutez le répertoire terraform au PATH pour utiliser la commande terraform plus simplement. Pour cela il suffit d’ajouter au fichier « .profile » le chemin vers le répertoire contenant l'exécutable terraform :

export PATH="$PATH:~/terraform"
``

Une fois l’ajout effectué, rafraichissez la session courante avec la
commande source en précisant en paramètre le fichier profile :

```shell
source .profile

Il est maintenant possible d'utiliser la commande terraform depuis n’importe quel répertoire :

terraform --version

Installer Atlantis

Rendez-vous dans le repository Github du projet pour accéder à la dernière version d'Atlantis. A l'heure ou cet article est publié, la version d'Atlantis est à 0.11.1. lancez la commande suivante pour installer Atlantis :

curl -L https://github.com/runatlantis/atlantis/releases/download/v0.11.1/atlantis_linux_amd64.zip \
     -o atlantis.zip 
sudo unzip atlantis.zip -d /usr/local/bin && rm atlantis.zip

Configurer Atlantis

Premièrement, il faut que le serveur Atlantis puisse être accessible par Github/ Gitlab. Pour cela vous devez spécifier un lien vers votre serveur Atlantis. Créez une variable d'environnement "URL" ou vous spécifierez le lien vers votre serveur Atlantis :

URL=http://atlantis.aws.easyteam.fr

Note: Vous pouvez dans un premier temps, créer un tunnel Ngrok pour effectuer vos tests. Le port par défaut d'Atlantis est le 4141, donc il faudra lancer la commande ngrok http 4141.

Github/Gitlab exige de renseigner un secret pour garantir au client que les webhooks proviennent bien d'eux. Il vous faut générer une chaine de caractères et l'ajouter dans une variable d'environnement "SECRET" et préciser cette valeur sur Github/Gitlab.

Github

Rendez-vous dans votre repository > Settings > Webhooks > Add webhook :

  • Ajoutez dans le champ "Payload URL", le lien que vous avez renseigné dans la variable d'environnement "URL" en ajoutant /events à la fin. Exemple : https://6b80f187.ngrok.io/events
  • Ajoutez la chaine de caractère que vous avez enregistrée dans la variable d'environnement SECRET dans le champ "Secret".
  • Définissez le type de contenu sur application/json
  • Selectionnez "Let me select individual events." et cochez :

    • Pull request reviews
    • Pushes
    • Issue comments
    • Pull requests
  • Laissez Active cochez
  • Terminez avec Add wehbook

Gitlab

Rendez-vous dans votre repository > Settings > Webhooks :

  • Spécifiez le lien vers votre serveur Atlantis dans le champ URL
  • Spécifiez le secret que vous venez de créer dans le champ Secret Token.
  • Cochez les cases Push Events, comments, Merge request events et laissez l'option Enable SSL verification cochée.

Sur la machine hébergeant Atlantis définissez les variables d'environnement suivantes :

$ SECRET=[SECRET]

Ensuite, il vous faut générer un token depuis github/gitlab :

  • Github : Settings > Developper Settings > Personal access tokens > Generate new token
  • Gitlab : Settings > Access Tokens

Nommez votre token Atlantis avec un scope repo, puis générez le token. Ensuite, renseignez le token généré dans une variable d'environnement nommée TOKEN :

$ TOKEN=[Token]

Spécifiez le nom d'utilisateur possédant un accès au repository dans une variable d'environnement USERNAME.

Il est conseillé de créer un nouvel utilisateur nommé @atlantis qui sera en charge d'exécuter toutes les actions API.

$ USERNAME=[USERNAME]

Spécifiez l'URL de votre repository Github/Gitlab dans une variable d'environnement nommé REPO_WHITELIST :

$ REPO_WHITELIST=github.com/[USERNAME]/[Project_Name]

Une fois que vous avez renseigné toutes les informations utiles à Atlantis vous pouvez lancer le serveur en spécifant toutes les variables déclarées :

$ atlantis server --atlantis-url="$URL" --gitlab-user="$USERNAME" \
  --gitlab-token="$TOKEN" --gitlab-webhook-secret="$SECRET" \
  --repo-whitelist="$REPO_WHITELIST"

Assurez-vous bien que le port 4141 soit bien ouvert :

$ netstat -tulpn | grep LISTEN

Mise en pratique

Vous pouvez voir ci-dessous un schéma qui illustre les différentes intéractions entre Github, Atlantis et Terraform :

Schéma Atlantis

Dans la pratique, cela se présente de la manière suivante :

  • Une fois la Pull Request (PR) créé avec le nouveau code Terraform,

Création d'une Pull Request

  • Atlantis va se charger d'effectuer un terraform plan, en prenant en compte les fichiers venant d'être poussés et afficher le résultat en commentaire dans la PR.

Plan du commit

Si vous souhaitez effectuer un plan dans un workspace spécifique, commentez : atlantis plan -w dev.

Plan du commit

  • Vous pouvez faire vérifier et approuver la PR par un membre du projet.

PR approuvé

  • Quand celle-ci est approuvé, vous pouver appliquer la modification en commentant la PR avec atlantis apply.

apply terraform

Si vous souhaitez detruire les ressources appliquées, commentez : atlantis plan -w dev -- -destroy => atlantis apply -w dev

Plusieures raisons peuvent vous pousser à utiliser Atlantis :

  • Vous souhaitez que les changements Terraform soient visibles par tous
  • Vous n'êtes pas opérateur, mais vous souhaitez pouvoir utiliser Terraform
  • Vous souhaitez standardiser vos processus de déploiement

Atlantis est un projet qui continue d'évoluer, ainsi il propose de nombreuses fonctionnalités que vous pouvez retrouver dans la documentation. Pour en savoir plus, n'hésitez pas à regarder la Documentation Atlantis

Easyteam DevOps

Easyteam DevOps