Ansible bootrap

Ce dépôt est un référentiel Ansible pour les projets ansible de Lydra.

Il sert de base à tout nouveau projet Ansible pour gagner du temps..

Ansible

Ressources : Site officiel, Ansible Galaxy

Présentation

Ansible est un outil d’automatisation, il peut configurer des systèmes, déployer des logiciels, et orchestrer les tâches informatiques avancées comme des déploiements continus ou des mises à jour sans coupure de service.

Ansible gère les machines sans agent (agentless), il n’y a pas de démon sur les nœuds donc pas de mises à jours client à prévoir et pas de problème du type : "impossible de mettre à jour car l’agent ne tourne pas". C’est donc moins intrusif et moins consommateur en ressources pour les machines. Le seul prérequis sur la machine est d'avoir un environnement Python 2 ou 3.

Ansible est décentralisé : il repose sur les informations d’identification sur le système d’exploitation existant pour contrôler l’accès à des machines distantes via SSH. Si nécessaire, il peut facilement se connecter avec Kerberos, LDAP, et d’autres systèmes de gestion d’authentification centralisés.

Les fichiers de configuration décrivent l’état dans lequel le serveur doit-être et non la manière d’amener le serveur à cet état. Ansible est capable, par lui même, de savoir comment arriver à cet état. Ansible permet aussi des lancements à blanc pour pré-visualiser les modifications qui seront nécessaires pour amener le nœud dans l’état souhaité.

Ansible crée à partir des configurations de simples scripts shell qu’il va envoyer et exécuter sur les nœuds distants à travers une connexion SSH.

Prérequis

Démarrage Rapide

Installer toutes les dépendances du projet :

make

Lancer votre environnement de développement

pipenv shell

L'environnement Python

Pour que tout les contributeurs aient le même environnement de développement, il est important de fixer les dépendances Python et paquets pip. Pour cela on utilise pipenv.

Il faut d'abord s'assurer d'avoir pipenv et pyenv installés ou à jour. Voir cet article pour en savoir plus sur les deux outils (cf. doc1 et doc2) :

pip install --user pipenv

ou pour mettre à jour

python3 -m pip install --user --upgrade pipenv

L'option --user permet de n'appliquer les changements que pour l'utilisateur, et évite de "casser" l'installation par défaut du système.

curl -L https://raw.githubusercontent.com/pyenv/pyenv-installer/master/bin/pyenv-installer | bash

Puis dans .zshrc, ajouter le bloc suivant :

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
if command -v pyenv 1>/dev/null 2>&1; then
 eval "$(pyenv init -)"
fi

On peut alors installer la version de Python que l'on veut, par exemple la 3.8 avec la commande :

pyenv install 3.8.12

Pour le projet on initialise alors l'environnement de travail. Dans ce dépôt on a fixé l'environnement avec un Python 3.8 et la commande :

pipenv install

Ensuite, il suffit de lancer la commande à chaque fois qu'on se replace dans le dossier de travail :

pipenv shell

Pour vérifier la version :

python --version
Python 3.8.12

Dans le cas où vous rencontreriez l'erreur suivante (⠋/usr/bin/python3: No module named pipenv.pew) sur une Ubuntu 20.04, merci de vous référez à la documentation ici.

L'avantage de pipenv est de gérer les variables d'environnement qu'il redéfini en local.

Pour développer il faut toujours être dans un environnement pipenv pour lancer les commandes ansibles et avoir les bons paquets pip pour le projet. Pour ça lancer simplement la commande :

pipenv shell

Ansible

Ansible est géré par pipenv. Il a été configuré avec la version 4 grâce à la commande :

pipenv install ansible==4  

Définissez les rôles / collections à utiliser pour le projet dans Le fichier requirements.yml. Ils seront installés en local dans le sous-dossier .ansible/. On peut retrouver les rôles / collections partagées par la communauté (ici).

ansible-vault

Il est utilisé pour chiffrer et déchiffrer les fichiers sensibles pour qu'ils ne soient pas visibles en clair sur Github ou Gitlab (Source).

Par convention ces fichiers s’appellent *.vault.

Pour s'assurer que ces fichiers soient chiffrés à la volée au moment du commit ajoutez les éléments suivants à votre fichier .git/config :

[diff "ansible-vault"]
  textconv = .git_crypt_diff
  # Do not cache the vault contents
  cachetextconv = false
[filter "ansible-vault"]
  clean  = .git_crypt_clean

Créez votre fichier .vault_pass à la racine du projet et contenant le mot de passe du projet.

Une fois cette configuration faite, tous les fichiers contenant "vault" dans leur nom sont automatiquement chiffrés au moment du commit. Ainsi vous ne risquez plus de compromettre des informations sensibles en les partageant en clair sur un dépôt de code.

Les fichiers chiffrés peuvent alors être lus avec Ansible Vault :

ansible-vault edit my_file.vault.yml --vault-password-file=.vault_pass

Pour plus de détail voir ici.

Un plugin peut-être ajouté dans VSCodium afin de faciliter la gestion des secrets (dhoeric.ansible-vault).

~/.ssh/config

Afin d'utiliser les bons identifiants et ports de connexion, il est nécessaire de définir les hôtes à piloter dans le fichier ~/.ssh/config. Voici un exemple :

Host server_prd_01 server.prd01.lydra.eu 192.168.1.207
    HostName server.prd01.lydra.eu
    Port 1234
    User thomas

Sur la ligne Host on peut mettre autant d'alias que désiré, séparé par un espace, le serveur pourra être adressé ainsi avec la commande ssh server_prd_01 et utiliser directement les bons paramètres.

PATH

Nous utilisons souvent des helper scripts qui se trouvent dans les répertoires bin/.

Il faut ajouter ce chemin suivant dans votre PATH :

export PATH="./bin:$PATH"

Hook

Nous utilisons un hook pour vérifier les fichiers vault non chiffrés. Vous devez créer un lien symbolique.

Dans le répertoire Git:

make install_hooks

Rôles Ansible et Docker

Afin de disposer de toutes les ressources nécessaires (Docker, Ansible, rôles, etc), il est nécessaire de lancer la commande make à la racine du projet.

Cette commande permet des paramètres, si on souhaite ne rafraîchir qu'une partie :

make				        # contrôle les prérequis et installe l'environnement de dev
make install			  # idem
make install_deps		# installe les rôles et collections Ansible
make delete_deps		# supprime les rôles et collections Ansible
make renew_deps		  # supprime puis réinstalle les rôles et collections
make refresh_deps		# force la mise à jour des rôles et collections
make check  		    # contrôle les prérequis
make install_hooks  # installe le hook de pré-commit

Il est important de relancer la commande make renew_deps régulièrement pour charger en local les nouveaux rôles Ansible utilisés par le projet.

Les logs Ansible

ARA est un outil web (local) qui facilite la lecture et l'exploration des logs produites par Ansible.

La configuration du Pipfile a été faite grâce à la commande :

pipenv install ara[server]==1.5.7

Démarrer l'outil avant de lancer ses scripts Ansible :

export ANSIBLE_CALLBACK_PLUGINS=$(python -m ara.setup.callback_plugins)

ara-manage runserver &

Attention, lors du premier lancement dans un environnement vierge il se peut que vous soyez confrontés au message suivant : "You have 28 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, api, auth, contenttypes, db, sessions. Run 'python manage.py migrate' to apply them.". Le tout accompagné d'une erreur 500 lorsque vous accédez au serveur de logs. Dans ce cas exécutez la commande suivante : ara-manage migrate pour régler ce souci.

Visualiser les logs : http://127.0.0.1:8000

Utilisation

Tester

Vérifier la configuration de votre environnement avec la commande de test :

provision test --tags=info

Validité du code (Lint)

Pour tester la syntaxe de son code, on peut utiliser la commande lint qui fera divers contrôles et recommandations.

lint

Le contrôle sera fait par un ansible-playbook --syntax-check puis un ansible-lint [...] sur chacun des fichiers Yaml.

Provisionner l'infrastructure

Il faut lancer cette commande à chaque fois que l'on souhaite appliquer des changements globaux d'infrastructure :

provision <env_type> [options]

Par défaut l'environnement sera dev. Dont les paramètres sont :

• env_type : environnement à provisionner
  • dev : développement
  • stg : staging
  • rec : recette
    • prd : production
• options :
  • --limit=<name> : ne cibler qu'un sous-groupe ou qu'une machine de l'environnement ciblé
    • debian
    • server_rec_01
  • --tags=<tags> : ne provisionner qu'une partie identifiée par un tag
    • deploy
    • common
  • --skip-tags=<tags> : permet d'exclure certaines parties du script
  • --check : réalise un test sans rien exécuter
  • --syntax-check : contrôle la syntaxe (voir l'alternative Lint)
  • --verbose

Exemples :

provision dev --limit=server_dev_01 --tags=common
provision dev --limit=server_dev_01 --skip-tags=common

À noter que les variables peuvent être surchargées dans l’ordre suivant (cf. doc Ansible)

• le groupe all
• les autres groupes, dans l’ordre alphabétique (cf. autre doc Ansible)
  • si les groupes sont hiérarchisés, cette hiérarchie est respectée
• le host

Déployer l'application

Cette commande est un alias de provision avec un tag prédéfini. On utilise cette commande pour deployer uniquement l'application sans recharger/réinstaller certains paquets système.

deploy [<env_type>] [options]

Par défaut l'environnement sera dev. Les options sont les mêmes que pour provision. L'option --tags=deploy est ajoutée par défaut.

Résumé

# Démarrer l'environnement
pipenv shell
export PATH="./bin:$PATH"
cd ansible
export ANSIBLE_CALLBACK_PLUGINS=$(python -m ara.setup.callback_plugins)

ara-manage runserver &
# (...) modification de ses scripts Ansible
# Tester
lint
provision dev --limit=server_dev_01 --tags=common --syntax-check
provision dev --limit=server_dev_01 --tags=common --check
# Lancer
provision dev --limit=server_dev_01 --tags=common
# Visualiser les logs sur http://127.0.0.1:8000