ansible-role-shipyard

À propos de Shipyard

Shipyard est un outil pour orchestrer des clusters et des stacks Docker Swarm à partir de playbooks Ansible.

Il est fortement inspiré par Helm et helmfile et fournit les mêmes concepts dans un environnement compatible avec Swarm mais non Kubernetes.

Concepts :

• Shipyard Chart : Un package définissant une stack Docker Compose et tous ses fichiers associés (fichiers de configuration, variables d'environnement, etc.), similaire à un Helm Chart, un fichier RPM yum ou une formule Homebrew. Un chart contient toutes les définitions nécessaires pour déployer et exécuter une application en tant que stack Docker Swarm, organisées dans une disposition spécifique. Un chart peut être utilisé pour déployer une simple application ou une stack complète d'application web avec plusieurs dépendances, telles que des serveurs HTTP, des bases de données, des caches, etc. (similaire à un Helm Chart)
• Shipyard Stack : une instance d'un Shipyard Chart, personnalisée via un fichier values.yaml. (similaire à un Helm Release)
• shipyard.yaml : un fichier définissant quels Charts instancier en utilisant quelles valeurs sur quels hôtes Docker. (similaire à un fichier helmfile.yaml)

Comme vous pouvez le voir, les concepts sont très similaires à Helm et helmfile. La principale différence est que Shipyard n'est pas spécifique à Kubernetes et ne nécessite pas de cluster Kubernetes pour fonctionner. Au lieu de cela, il utilise Docker Swarm pour déployer les stacks.

Prérequis

Le rôle Ansible suppose que vous avez préconfiguré les hôtes cibles avec :

• Docker Swarm (c'est-à-dire que docker swarm deploy fonctionne)
• Docker Compose (c'est-à-dire que docker-compose fonctionne)
• Authentification Docker pour les images utilisées (c'est-à-dire que docker pull mon-image fonctionne)

Variables du rôle

Le rôle peut être personnalisé par quelques variables optionnelles :

• shipyard_filename : chemin vers votre fichier shipyard.yaml. Par défaut : {{inventory_path}}/shipyard.yaml. Ce fichier peut être un modèle Jinja2.
• shipyard_charts_path : chemin vers votre répertoire de charts. Par défaut : {{inventory_path}}/shipyard/charts
• shipyard_stacks_path : chemin vers votre répertoire de stacks (values.yaml / values.sops.yaml). Par défaut : {{inventory_path}}/shipyard/stacks
• shipyard_stacks_docker_secrets : une liste de secrets Docker. Par défaut []
• shipyard_tag : déployez éventuellement uniquement les stacks avec cette étiquette. Par défaut : vide

Utilisation

Obtenir le rôle depuis Ansible galaxy

Configurez votre fichier requirements.yml pour inclure le rôle :

roles:
  - name: linkorb.shipyard

Puis exécutez ansible-galaxy install -r requirements.yml pour installer le rôle.

Création d'un fichier shipyard.yaml :

Le fichier shipyard.yaml définit quelles stacks sont déployées sur quels hôtes. Il est similaire à un fichier helmfile.yaml.

# shipyard.yaml
stacks:
  - name: my-traefik
    chart: traefik
    host: swarm-host-a
    values: my-traefik/values.yaml
    tag: lb

  - name: my-whoami
    chart: whoami
    host: swarm-host-a
    values: my-whoami/values.yaml
    tag: apps

  - name: my-mariadb
    chart: mariadb
    host: swarm-host-a
    values: my-mariadb/values.yaml
    tag: db

  - name: my-whoami-b
    chart: whoami
    host: swarm-host-b
    values: my-whoami-b/values.yaml
    tag: apps

Ajout du rôle Shipyard à votre playbook Ansible

Dans votre playbook Ansible (généralement site.yml), ajoutez ce qui suit :

- name: Configuration de l'hôte Docker shipyard
  hosts: my-swarm-hosts # ou un groupe d'hôtes - censés être des gestionnaires de Docker Swarm avec authentification de tirage d'image Docker configurée
  tags:
    - shipyard # ou toute autre étiquette que vous souhaitez utiliser pour exécuter ce playbook
  roles:
    - role: linkorb.shipyard # le rôle provenant d'Ansible Galaxy
      vars:
        shipyard_tag: apps

Cela recherchera le fichier shipyard.yml à la racine du répertoire du playbook. Il déploiera sur les hôtes gérés les stacks étiquetées avec apps qui y sont listées.

Création d'un Shipyard Chart

Structure de répertoire d'un Shipyard Chart :

my-shipyard-chart/
  Chart.yaml # les métadonnées du chart
  LICENSE # la licence de ce chart
  README.md # le README de ce chart
  values.yaml # les valeurs par défaut pour ce chart
  templates/ # les modèles jinja2 pour ce chart
    docker-compose.yml # le fichier modèle docker compose pour ce chart
    example.conf # un exemple de modèle de fichier de configuration pour ce chart
    env.example # un autre exemple de modèle de fichier de configuration pour ce chart
    a-directory/ # un répertoire à copier sur l'hôte cible

Le rôle Shipyard copiera tous les fichiers et dossiers dans le répertoire templates/ sur l'hôte cible, puis rendra les fichiers en utilisant les valeurs du Chart et de la Stack (voir la section suivante pour plus d'informations à ce sujet).

values.yaml / values.sops.yaml et valeurs par défaut du chart

Chaque stack (une instance d'un chart) prend un fichier values contenant les valeurs pour cette instance du chart. Les valeurs sont chargées depuis {{shipyard_stacks_path}}/{{stack_name}}/values.yaml. Si un fichier values.sops.yaml est détecté, il est également chargé et déchiffré automatiquement (basé sur le fichier .sops.yaml dans la racine de votre dépôt).

Chaque chart fournit également des valeurs.yaml par défaut. Toute valeur au niveau de la stack qui reste non définie sera réglée sur la valeur par défaut du chart.

L'ordre de chargement (et de priorité de remplacement) est :

1. les valeurs par défaut du chart
2. le values.yaml de la stack
3. le values.sops.yaml de la stack

Valeurs spéciales

• primed_volumes : une liste d'objets d'informations de volume Docker qui seront créés pour la stack.

  Cette valeur n'est significative que lorsqu'un Chart le prend en charge.

  Chaque objet d'information de volume a les propriétés suivantes :

  • name : Le nom du volume
  • target : L'endroit dans le conteneur où monter le volume
  • path : Le chemin, sous le chemin de la stack sur l'hôte distant, à copier récursivement dans le volume.

  Par exemple, un volume contenant des scripts d'initialisation de base de données MariaDB peut être créé comme suit :

  # my-stack/values.yaml
  primed_volumes:
  - name: mariadb_init_data
    target: /docker-entrypoint-initdb.d # c'est ici que le conteneur MariaDB cherche les données d'initialisation
    path: docker-entrypoint-initdb.d # ce répertoire est présent dans le répertoire templates/ du Chart
  

Structure du répertoire de l'hôte cible

Sur les hôtes cibles (gestionnaires Docker Swarm), le rôle créera la structure de répertoire suivante :

/opt/shipyard/stacks/
  my-shipyard-stack/
    docker-compose.yml # le fichier docker compose rendu
    example.conf # le fichier de configuration d'exemple rendu
    # ... etc

Déploiement des stacks sur Docker Swarm

Après que les modèles aient été rendus et écrits sur l'hôte, le rôle exécutera docker stack deploy sur l'hôte cible pour déployer la stack Docker Swarm.

Exemple de Shipyard Chart

Consultez le répertoire example/shipyard/charts/whoami pour un exemple de Shipyard Chart.

Contribuer

Nous accueillons les contributions pour améliorer ce dépôt. Que ce soit pour corriger un bug, ajouter une fonctionnalité ou améliorer la documentation, votre aide est très appréciée. Pour commencer, fork ce dépôt puis clonez votre fork.

Assurez-vous de vous familiariser avec les Directives de Contribution de LinkORB pour nos normes concernant les commits, les branches et les demandes de tirage, ainsi qu'avec notre code de conduite avant de soumettre des modifications.

Si vous ne pouvez pas implémenter les changements qui vous plaisent, n'hésitez pas à ouvrir un nouveau rapport de problème afin que nous ou d'autres puissions nous en occuper.

Présenté par l'équipe d'ingénierie de LinkORB

Découvrez nos autres projets sur linkorb.com/engineering. Au fait, nous recrutons !