Assemblage et déploiement dynamiques d'images Docker avec werf en utilisant l'exemple de site de documentation versionnée

Nous avons déjà parlé de notre outil werf GitOps plus d'une fois , mais cette fois, nous aimerions partager l'expérience de la construction du site avec la documentation du projet - werf.io (sa version russe est ru.werf.io ). Il s'agit d'un site statique normal, mais son assemblage est intéressant car il est construit à l'aide d'un nombre dynamique d'artefacts.



Entrez dans les nuances de la structure du site: génération d'un menu général pour toutes les versions, pages d'informations sur les versions, etc. - nous ne le ferons pas. Au lieu de cela, nous nous concentrons sur les problèmes et les fonctionnalités de l'assemblage dynamique et un peu sur les processus CI / CD associés.

Introduction: comment le site est organisé

Pour commencer, la documentation werf est stockée avec son code. Cela pose certaines exigences de développement qui dépassent généralement le cadre de cet article, mais au moins, nous pouvons dire que:

• Les nouvelles fonctions de werf ne doivent pas être publiées sans mise à jour de la documentation et, à l'inverse, toute modification de la documentation implique la sortie d'une nouvelle version de werf;
• Le projet a un développement assez intensif: de nouvelles versions peuvent sortir plusieurs fois par jour;
• Tout déploiement manuel d'un site avec une nouvelle version de la documentation est au moins fastidieux;
• Le projet a adopté l'approche du versioning sémantique, avec 5 canaux de stabilité. Le processus de libération implique le passage séquentiel des versions à travers les canaux afin d'augmenter la stabilité: de l'alpha au solide comme le roc;
• Le site a une version en langue russe qui «vit et se développe» (c'est-à-dire dont le contenu est mis à jour) en parallèle avec la version principale (c'est-à-dire en langue anglaise).

Pour cacher à l'utilisateur toute cette «cuisine intérieure», en lui offrant ce qui «fonctionne tout simplement», nous avons créé un outil d'installation et de mise à jour de werf distinct - c'est multiwerf . Il suffit d'indiquer le numéro de version et le canal de stabilité que vous êtes prêt à utiliser, et multiwerf vérifiera s'il existe une nouvelle version sur le canal et la téléchargera si nécessaire.

La dernière version de werf dans chaque canal est disponible dans le menu de sélection de version sur le site. Par défaut, la version du canal le plus stable pour la dernière version s'ouvre sur werf.io/documentation - elle est également indexée par les moteurs de recherche. La documentation du canal est disponible à des adresses individuelles (par exemple, werf.io/v1.0-beta/documentation pour la version bêta 1.0).

Total, le site a les versions suivantes:

1. root (ouvre par défaut)
2. pour chaque canal de mise à jour actif de chaque version (par exemple, werf.io/v1.0-beta ).

Pour générer une version spécifique d'un site dans le cas général, il suffit de le compiler à l'aide des outils Jekyll en exécutant la commande appropriée ( jekyll build ) dans le répertoire /docs du référentiel werf, après avoir basculé sur la balise Git de la version requise.

Il ne reste plus qu'à ajouter que:

• l'utilitaire lui-même (werf) est utilisé pour l'assemblage;
• Les processus CI / CD sont basés sur GitLab CI;
• et tout cela, bien sûr, fonctionne à Kubernetes.

Les tâches

Nous formulons maintenant des tâches qui prennent en compte toutes les spécificités décrites:

1. Après avoir changé la version werf sur n'importe quel canal de mise à jour, la documentation sur le site doit être mise à jour automatiquement .
2. Pour le développement, vous devez être en mesure de visualiser occasionnellement les versions préliminaires du site .

La recompilation du site doit être effectuée après avoir changé la version sur n'importe quel canal à partir des balises Git correspondantes, mais dans le processus de construction de l'image, nous obtiendrons les fonctionnalités suivantes:

• La liste des versions des canaux étant en train de changer, il suffit de remonter la documentation des canaux où la version a changé. Après tout, tout remonter n'est pas très beau.
• L'ensemble des canaux pour les versions peut varier. À un certain moment, par exemple, la version sur les canaux peut ne pas être plus stable que la version 1.1 à accès anticipé, mais au fil du temps, elle apparaîtra - ne changez pas l'assemblage à la main dans ce cas?

Il s'avère que l' assemblage dépend de la modification des données externes .

Implémentation

Choix de l'approche

Vous pouvez également exécuter chaque version requise avec un module distinct dans Kubernetes. Cette option implique un plus grand nombre d'objets dans le cluster, qui augmentera avec une augmentation du nombre de versions de werf stables. Et cela implique à son tour un service plus complexe: chaque version a son propre serveur HTTP, et avec une petite charge. Bien sûr, cela entraîne des coûts plus élevés pour les ressources.

Nous avons suivi le chemin de l' assemblage de toutes les versions nécessaires en une seule image . Les statistiques compilées de toutes les versions du site sont dans un conteneur avec NGINX, et le trafic vers le déploiement correspondant passe par NGINX Ingress. Une structure simple - une application sans état - facilite la mise à l'échelle du déploiement (en fonction de la charge) à l'aide de Kubernetes lui-même.

Pour être plus précis, nous collectons deux images: une pour le circuit de production, l'autre pour le circuit de développement. Une image supplémentaire est utilisée (lancée) uniquement sur le circuit de développement avec la principale et contient la version du site à partir de la validation de la revue, et le routage entre eux est effectué à l'aide des ressources Ingress.

werf vs git clone et artefacts

Comme déjà mentionné, afin de générer des statistiques de site pour une version spécifique de la documentation, vous devez créer en basculant vers la balise de référentiel correspondante. On pourrait également le faire en clonant le référentiel à chaque fois pendant l'assemblage, en sélectionnant les balises appropriées dans la liste. Cependant, c'est une opération plutôt consommatrice de ressources et, de plus, nécessitant l'écriture d'instructions non triviales ... Un autre inconvénient sérieux - avec cette approche, il n'y a aucun moyen de mettre en cache quelque chose pendant l'assemblage.

Ici, l'utilitaire werf vient à notre aide, qui implémente la mise en cache intelligente et permet l'utilisation de référentiels externes . L'utilisation de werf pour ajouter du code à partir du référentiel accélérera considérablement la construction, car werf effectue essentiellement le clonage du référentiel une fois, puis ne fetch si nécessaire. De plus, lors de l'ajout de données à partir du référentiel, nous ne pouvons sélectionner que les répertoires nécessaires (dans notre cas, c'est le répertoire docs ), ce qui réduira considérablement la quantité de données ajoutées.

Étant donné que Jekyll est un outil conçu pour compiler des statistiques et n'est pas nécessaire dans l'image finale, il serait logique de compiler dans l' artefact werf et d' importer uniquement le résultat de la compilation dans l'image finale.

Écriture werf.yaml

Nous avons donc décidé de compiler chaque version dans un artefact werf distinct. Cependant, nous ne savons pas combien de ces artefacts seront au cours de l'assemblage , donc nous ne pouvons pas écrire une configuration d'assemblage fixe (à proprement parler, nous pouvons toujours, mais elle ne sera pas complètement efficace).

werf vous permet d'utiliser des Go-templates dans votre fichier de configuration ( werf.yaml ), ce qui permet de générer une config "à la volée" en fonction de données externes (ce dont vous avez besoin!). Les données externes dans notre cas sont des informations sur les versions et les versions, sur la base desquelles nous collectons le nombre nécessaire d'artefacts et obtenons en conséquence deux images: werf-doc et werf-dev pour le lancement sur des chemins différents.

Les données externes sont transmises via des variables d'environnement. Voici leur composition:

• RELEASES - une ligne avec une liste de versions et la version actuelle correspondante de werf, sous la forme d'une liste, séparée par un espace, au format <_>%<_> . Exemple: 1.0%v1.0.4-beta.20
• CHANNELS - une ligne avec une liste de canaux et la version actuelle correspondante de werf, sous la forme d'une liste avec un espace de valeurs au format <>%<_> . Exemple: 1.0-beta%v1.0.4-beta.20 1.0-alpha%v1.0.5-alpha.22
• ROOT_VERSION - La version de la version werf à afficher par défaut sur le site (il n'est pas toujours nécessaire d'afficher la documentation pour le numéro de version le plus élevé). Exemple: v1.0.4-beta.20
• REVIEW_SHA - hachage de la validation de révision à partir de laquelle vous devez collecter la version pour la boucle de test.

Ces variables seront remplies dans le pipeline GitLab CI, et comment exactement est décrit ci-dessous.

Tout d'abord, pour plus de commodité, nous définissons les variables Go-template dans werf.yaml leur affectant des valeurs à partir des variables d'environnement:

 {{ $_ := set . "WerfVersions" (cat (env "CHANNELS") (env "RELEASES") | splitList " ") }} {{ $Root := . }} {{ $_ := set . "WerfRootVersion" (env "ROOT_VERSION") }} {{ $_ := set . "WerfReviewCommit" (env "REVIEW_SHA") }} 

La description de l'artefact pour compiler la statique de la version du site est généralement la même pour tous les cas dont nous avons besoin (y compris la génération de la version racine, ainsi que la version pour le circuit de développement). Par conséquent, nous le placerons dans un bloc séparé en utilisant la fonction define - pour une réutilisation ultérieure avec include . Nous transmettrons les arguments suivants au modèle:

• Version - version générée (nom de la balise);
• Channel - le nom du canal de mise à jour pour lequel l'artefact est généré;
• Commit - validation du hachage si un artefact est généré pour la validation de la révision;
• contexte.

Le nom de l'artefact doit être unique. Nous pouvons y parvenir, par exemple, en ajoutant le nom du canal (valeur de la variable .Channel ) comme suffixe pour le nom de l'artefact: artifact: doc-{{ .Channel }} . Mais vous devez comprendre que lors de l'importation à partir d'artefacts, vous devrez vous référer aux mêmes noms.

Lors de la description d'un artefact, une fonctionnalité werf comme mount est utilisée . Le montage avec le build_dir service build_dir vous permet d'enregistrer le cache Jekyll entre les démarrages de pipeline, ce qui accélère considérablement la reconstruction .

Vous avez peut-être également remarqué l'utilisation du fichier releases.yml - il s'agit du fichier YAML avec les données de publication demandées à github.com (l'artefact obtenu en exécutant le pipeline). Il est nécessaire lors de la compilation du site, mais dans le contexte de l'article, nous nous intéressons au fait qu'un seul artefact , l' artefact racine de la version du site , dépend de son état (dans d'autres artefacts, il n'est pas nécessaire).

Ceci est implémenté en utilisant l'opérateur conditionnel pour les modèles {{ $Root.Files.Get "releases.yml" | sha256sum }} go et le {{ $Root.Files.Get "releases.yml" | sha256sum }} {{ $Root.Files.Get "releases.yml" | sha256sum }} dans la scène . Cela fonctionne comme suit: lors de l'assemblage d'un artefact pour la version racine (la variable .Channel est root ), le hachage du fichier releases.yml affecte la signature de toute la scène, car il s'agit d'un composant du nom du travail Ansible (paramètre name ). Ainsi, lors de la modification du contenu du fichier releases.yml , l'artefact correspondant sera reconstruit.

Faites également attention à travailler avec un référentiel externe. Seul le répertoire /docs est ajouté à l'image de l'artefact à partir du référentiel werf , et selon les paramètres transmis, les données de la balise ou de la validation de révision nécessaires sont ajoutées immédiatement.

Pour utiliser le modèle d'artefact pour générer une description d'artefact des versions transférées des canaux et des versions, nous organisons une boucle sur la variable .WerfVersions dans werf.yaml :

 {{ range .WerfVersions -}} {{ $VersionsDict := splitn "%" 2 . -}} {{ dict "Version" $VersionsDict._1 "Channel" $VersionsDict._0 "Root" $Root | include "doc_artifact" }} --- {{ end -}} 

Parce que la boucle va générer plusieurs artefacts (on l'espère), il faut prendre en compte le séparateur entre eux - la séquence --- (pour plus d'informations sur la syntaxe du fichier de configuration, voir la documentation ). Comme précédemment déterminé, lorsque vous appelez le modèle en boucle, nous transmettons les paramètres de version, l'URL et le contexte racine.

De même, mais déjà sans boucle, nous appelons le modèle d'artefact pour les "cas spéciaux": pour la version racine, ainsi que la version du commit de révision:

 {{ dict "Version" .WerfRootVersion "Channel" "root" "Root" $Root | include "doc_artifact" }} --- {{- if .WerfReviewCommit }} {{ dict "Version" "review" "Channel" "review" "Commit" .WerfReviewCommit "Root" $Root | include "doc_artifact" }} {{- end }} 

Veuillez noter que l'artefact pour la validation de la révision ne sera collecté que si la variable .WerfReviewCommit est .WerfReviewCommit .

Les artefacts sont prêts - il est temps d'importer!

L'image finale, conçue pour s'exécuter dans Kubernetes, est un NGINX normal, dans lequel le fichier de configuration du serveur nginx.conf et les statiques des artefacts sont ajoutés. En plus de l'artefact de la version racine du site, nous devons répéter la boucle sur la variable .WerfVersions pour importer des artefacts des versions des canaux et des versions + observer la règle de dénomination des artefacts que nous avons adoptée précédemment. Étant donné que chaque artefact stocke des versions du site dans deux langues, nous les importons aux emplacements fournis par la configuration.


L'image supplémentaire, qui, avec l'image principale, est lancée sur le circuit de développement, ne contient que deux versions du site: la version du commit de révision et la version racine du site (il existe des actifs généraux et, si vous vous en souvenez, des données de publication). Ainsi, l'image supplémentaire de l'image principale ne différera que dans la section d'importation (et, bien sûr, dans le nom):

 image: werf-dev ... import: - artifact: doc-root add: /app/_main_site to: /app/main_site before: setup - artifact: doc-root add: /app/_ru_site to: /app/ru_site before: setup {{- if .WerfReviewCommit }} - artifact: doc-review add: /app/_main_site to: /app/main_site/review before: setup - artifact: doc-review add: /app/_ru_site to: /app/ru_site/review before: setup {{- end }} 

Comme déjà indiqué ci-dessus, l'artefact pour la validation de révision ne sera généré que lorsque werf démarre avec la variable d'environnement REVIEW_SHA . Il serait possible de ne pas générer d'image werf-dev s'il n'y a pas de REVIEW_SHA environnement REVIEW_SHA , mais pour que le nettoyage basé sur werf-dev des politiques pour les images Docker fonctionne pour l'image werf-dev, nous la laissons être collectée uniquement avec l'artefact de la version racine (de toute façon, il déjà assemblé), pour simplifier la structure du pipeline.

L'assemblage est prêt! On passe au CI / CD et aux nuances importantes.

Pipeline dans GitLab CI et fonctionnalités de l'assemblage dynamique

Lors du démarrage de l'assembly, nous devons définir les variables d'environnement utilisées dans werf.yaml . Cela ne s'applique pas à la variable REVIEW_SHA, que nous définirons lorsque le pipeline est appelé à partir du hook GitHub.

Nous générerons les données externes nécessaires dans le script Bash generate_artifacts , qui générera deux artefacts GitLab de pipeline:

• fichier releases.yml avec les données de version,
• fichier common_envs.sh contenant les variables d'environnement à exporter.

Vous trouverez le contenu du fichier generate_artifacts dans notre exemple de référentiel . L'obtention de données n'est pas le sujet de l'article, mais le fichier common_envs.sh est important pour nous, car le travail de werf en dépend. Un exemple de son contenu:

 export RELEASES='1.0%v1.0.6-4' export CHANNELS='1.0-alpha%v1.0.7-1 1.0-beta%v1.0.7-1 1.0-ea%v1.0.6-4 1.0-stable%v1.0.6-4 1.0-rock-solid%v1.0.6-4' export ROOT_VERSION='v1.0.6-4' 

Vous pouvez utiliser la sortie d'un tel script, par exemple, en utilisant la fonction Bash source .

Et maintenant pour la partie amusante. Pour que les applications de génération et de déploiement fonctionnent correctement, vous devez rendre werf.yaml identique pour au moins un pipeline . Si cette condition n'est pas remplie, les signatures des étapes que werf calcule lors de l'assemblage et, par exemple, du déploiement, seront différentes. Cela entraînera une erreur de déploiement, car l'image requise pour le déploiement sera absente.

En d'autres termes, si lors de l'assemblage de l'image du site, les informations sur les versions et les versions sont une et qu'au moment de la publication une nouvelle version est publiée et que les variables d'environnement ont des valeurs différentes, le déploiement échoue avec une erreur: l'artefact de la nouvelle version n'a pas encore été collecté.

Si la génération de werf.yaml dépend de données externes (par exemple, une liste des versions actuelles, comme dans notre cas), la composition et les valeurs de ces données doivent être enregistrées dans le pipeline. Ceci est particulièrement important si les paramètres externes changent assez souvent.

Nous allons recevoir et capturer des données externes à la première étape du pipeline dans GitLab ( Prebuild ) et les transférer plus loin en tant qu'artefact CI GitLab . Cela vous permettra de démarrer et de redémarrer les tâches de pipeline (génération, déploiement, nettoyage) avec la même configuration dans werf.yaml .

Le contenu de l'étape Prebuild du fichier .gitlab - ci.yml :

 Prebuild: stage: prebuild script: - bash ./generate_artifacts 1> common_envs.sh - cat ./common_envs.sh artifacts: paths: - releases.yml - common_envs.sh expire_in: 2 week 

En capturant des données externes dans un artefact, vous pouvez créer et déployer à l'aide des étapes de pipeline standard GitLab CI: génération et déploiement. Nous lançons le pipeline par des hooks à partir du référentiel gerHub werf (c'est-à-dire lors du changement du référentiel sur GitHub). Les données pour eux peuvent être prises dans les propriétés du projet GitLab dans la section Paramètres CI / CD -> Déclencheurs de pipeline , puis créer le Webhook correspondant ( Paramètres -> Webhooks ) dans GitHub.

L'étape de construction ressemblera à ceci:

 Build: stage: build script: - type multiwerf && . $(multiwerf use 1.0 alpha --as-file) - type werf && source <(werf ci-env gitlab --tagging-strategy tag-or-branch --verbose) - source common_envs.sh - werf build-and-publish --stages-storage :local except: refs: - schedules dependencies: - Prebuild 

GitLab ajoutera deux artefacts de l'étape de source common_envs.sh à la phase de construction, nous exportons donc les variables avec une entrée préparée à l'aide de la source common_envs.sh . Nous entamons la phase d'assemblage dans tous les cas, à l'exception du lancement du pipeline dans les délais. Selon le calendrier, le pipeline sera lancé pour le nettoyage - nous n'avons pas besoin de construire dans ce cas.

Au stade du déploiement, nous décrivons deux tâches - séparément pour le déploiement sur les circuits de production et de développement, à l'aide du modèle YAML:

 .base_deploy: &base_deploy stage: deploy script: - type multiwerf && . $(multiwerf use 1.0 alpha --as-file) - type werf && source <(werf ci-env gitlab --tagging-strategy tag-or-branch --verbose) - source common_envs.sh - werf deploy --stages-storage :local dependencies: - Prebuild except: refs: - schedules Deploy to Production: <<: *base_deploy variables: WERF_KUBE_CONTEXT: prod environment: name: production url: werf.io only: refs: - master except: variables: - $REVIEW_SHA refs: - schedules Deploy to Test: <<: *base_deploy variables: WERF_KUBE_CONTEXT: dev environment: name: test url: werf.test.flant.com except: refs: - schedules only: variables: - $REVIEW_SHA 

Les tâches ne diffèrent essentiellement qu'en indiquant le contexte du cluster sur lequel werf doit exécuter le déploiement ( WERF_KUBE_CONTEXT ) et en définissant les variables d'environnement du contour ( environment.name et environment.url ), qui sont ensuite utilisées dans les modèles de graphique Helm. Le contenu des modèles ne sera pas donné, car il n'y a rien d'intéressant pour ce sujet, mais vous pouvez les trouver dans le référentiel d'articles .

Touche finale

Étant donné que les versions werf sont publiées assez souvent, de nouvelles images sont souvent collectées et le Docker Registry s'agrandit constamment. Par conséquent, il est nécessaire de configurer le nettoyage automatique des images par stratégie. C'est très simple à faire.

Pour la mise en œuvre, vous aurez besoin de:

• Ajouter une étape de purification à .gitlab-ci.yml ;
• Ajouter des tâches de nettoyage périodiques;
• Définissez la variable d'environnement avec un jeton d'accès en écriture.

Ajoutez l'étape de nettoyage à .gitlab-ci.yml :

 Cleanup: stage: cleanup script: - type multiwerf && . $(multiwerf use 1.0 alpha --as-file) - type werf && source <(werf ci-env gitlab --tagging-strategy tag-or-branch --verbose) - source common_envs.sh - docker login -u nobody -p ${WERF_IMAGES_CLEANUP_PASSWORD} ${WERF_IMAGES_REPO} - werf cleanup --stages-storage :local only: refs: - schedules 

Presque nous tous l'avons déjà vu un peu plus haut - uniquement pour le nettoyage, vous devez d'abord vous connecter au Docker Registry avec un jeton qui a le droit de supprimer des images dans le Docker Registry (le jeton de tâche GitLab CI émis automatiquement ne dispose pas de tels droits). Le jeton doit être entré dans GitLab à l'avance et sa valeur doit être spécifiée dans la variable d'environnement WERF_IMAGES_CLEANUP_PASSWORD projet (Paramètres CI / CD -> Variables) .

L'ajout d'une tâche de nettoyage avec le planning nécessaire se fait dans CI / CD ->
Horaires

C'est tout: le projet dans le Docker Registry ne se développera plus constamment à partir d'images inutilisées.

À la fin de la partie pratique, je rappelle que la liste complète de l'article est disponible dans Git :

• .gitlab-ci.yml ;
• werf.yaml .

Résultat

1. Nous avons obtenu une structure de construction logique: un artefact par version.
2. L'assemblage est universel et ne nécessite pas de modifications manuelles lors de la sortie de nouvelles versions de werf: la documentation du site est automatiquement mise à jour.
3. Deux images sont collectées pour différents contours.
4. Ça marche vite car la mise en cache est utilisée au maximum - lorsqu'une nouvelle version de werf est publiée ou qu'un hook GitHub est appelé pour une validation de révision, seul l'artefact correspondant avec une version modifiée est reconstruit.
5. Pas besoin de penser à supprimer les images inutilisées: le nettoyage de la politique werf maintiendra l'ordre dans le Docker Registry.

Conclusions

• L'utilisation de werf permet à l'assembly de fonctionner rapidement grâce à la mise en cache de l'assembly lui-même et à la mise en cache lorsque vous travaillez avec des référentiels externes.
• Git- . werf , fetch .
• Go- werf.yaml , .
• werf — , pipeline.
• werf , .

PS

:

• « Kubernetes »;
• « werf GitLab CI »;
• « werf Helm- »;
• « werf 1.0 stable: GitOps, ».