guide_utilisateur_ci.md

# Utilisation de la chaîne d'intégration

## Introduction

Ce dépôt utilise la [chaîne d'intégration de Gitlab](https://docs.gitlab.com/ee/ci/), ou **CI**, pour automatiser certaines tâches dès lors que des changements ont lieu sur le dépôt. L'idée est en particulier d'automatiser la construction des images Docker et les analyses de sécurité, ce qui permet d'améliorer la sécurité de l'infrastructure, d'unifier les procédures, de garder un historique clair des modifications et de synchroniser l'état des services sur les machines avec l'état de ce dépôt.

La CI est déclenchée dès lors qu'une modification est susceptible d'altérer un service est détectée.

Elle va effectuer les opérations suivantes, partiellement ou complètement selon le contexte :
* Détection de l'image modifiée,
* Construction de l'image Docker et push vers le registre de test,
* Analyses de sécurité,
* Push vers le registre de production.

Chaque étape peut échouer et bloquer les étapes ultérieures. Il faudra régler les problèmes et mettre à jour le dépôt afin de relancer la CI le cas échéant.

## Mettre à jour un service

On peut vouloir mettre à jour :
* Le service (*e.g.* changer un numéro de version dans le Dockerfile),
* La configuration (éditer un fichier quelconque),
* La configuration des volumes (*e.g.* changer le point de montage du Docker Compose),
* etc.

En principe, il suffit de récupérer ce dépôt, de faire les mises à jour souhaitées, de commit les changements et de les pousser pour que l'image soit construite si besoin. Le cas échéant, pour des services "maisons", il est de bon ton de mettre à jour un fichier `CHANGELOG.md` pour résumer les modifications.

Si vous mettez à jour un fichier de configuration qui nécessite de reconstruire l'image, il faudra lancer la CI manuellement depuis la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines). Si vous mettez à jour un fichier de configuration qui est monté dans le conteneur via Docker Compose, aucune action de la CI n'est nécessaire, **même pas l'action `push-prod`**.

Notez que le **nom final** de l'image construite est celui que vous indiquez dans le `docker-compose.yml`. Si vous mettez à jour un service en lui-même (option 1 de la liste ci-dessus), il faut impérativement modifier la version de l'image construite dans ce fichier dans le `docker-compose.yml`.

**Attention, la CI se déclenche en regardant les modifications apportées lors du dernier commit. Si vous modifiez le `Dockerfile` dans un commit, puis le `README` dans un autre, et que vous poussez le tout, la construction ne se déclenchera pas automatiquement.**

Vous pouvez suivre les différentes étapes de la CI sur la page [Pipelines](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines), et il est **recommandé** de lire les logs des différentes étapes en cliquant sur chacune d'entre elles. Si la construction et les analyses de sécurité se passent bien, tous les voyants sont au vert (sauf la dernière étape, qui doit être déclenchée manuellement). Sinon, référez-vous à la section [Troubleshooting](#troubleshooting).

Enfin, il est de bon ton de vérifier que les CVE whitelistées dans le fichier `clair-whitelist.yml` sont toujours détectées dans le scan de Clair (étape `clair`). Si non, on pourra les enlever de la liste.

On peut ensuite [déployer le service](guide_deploiement.md).

## Exemple de mise à jour

On veut mettre à jour Mattermost de la version 5.18.0 à la version 5.19.0. On fait les modifications dans le Dockerfile et on pousse le commit. Les modifications dépendent évidemment du service, on peut voir le commit [472e0d72](https://gitlab.utc.fr/picasoft/projets/dockerfiles/commit/472e0d72534659e215270adade6746b65b6f65e3) pour l'exemple.

Le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) se lance automatiquement. Je suis les logs des jobs un par un pour vérifier que tout se passe bien.

La construction de l'image et les analyses de vulnérabilité se passent bien : aucun paquet n'introduit de nouvelle vulnérabilité.

Je [déploie la nouvelle version du service](./guide_deploiement.md).

Si tout se passe bien, je me rends de nouveau sur le [pipeline](https://gitlab.utc.fr/picasoft/projets/dockerfiles/pipelines/54707) et je lance manuellement l'étape `push-prod` pour pousser l'image sur le registre de production.

## Astuces

Il est possible de relancer une pipeline plus ancienne, pour reconstruire une ancienne version de l'image, quand cela est nécessaire, et revenir exactement dans l'état du commit concerné.

## Troubleshooting

Des erreurs peuvent survenir à plusieurs étapes de la CI.
Les logs de chaque étape donnent des informations sur la nature de l'erreur.

### Impossibilité de pull une image

Parfois, un timeout empêche de pull l'image depuis le registre de test entre deux étapes, avec des messages de timeout ou de type `Unknown blob`. Il faudra dans ce cas redémarrer le registre de test (sur `pica01-test`, probablement) et relancer la chaîne d'intégration.

### Lors de la construction de l'image

Si l'erreur ne vient pas d'un Dockerfile mal écrit, elle peut venir d'un nom d'image mal formaté dans le Docker Compose (voir [Formalisme du dépôt](./guide_developpeur_ci#formalisme-du-dpt)).

### Lors de l'analyse de sécurité statique

Cette analyse échoue lorsque des CVE avec une criticité `High` ou plus sont détectées. Les CVE de niveau plus faible étant inévitables, la CI n'échoue pas et se contente de les afficher.

Clair vous indique quels paquets sont vulnérables. Plusieurs choix s'offrent à vous : mitiger la CVE (choix à privilégier) ou mettre la CVE en liste blanche.

On regardera à ce titre le [Mini guide pour mitiger une CVE !](mini_guide_cve.md)

Ensuite, on pousse les modifications et la CI ré-effectuera les tests de vulnérabilités, en reconstruisant l'image si nécessaire.

### Lors de l'analyse de sécurité dynamique

Il est fort probable que l'erreur provienne d'un mauvais Docker Compose, et que Docker Bench for Security n'arrive pas à lancer votre ou vos conteneur(s), par exemple à cause d'un fichier manquant ou d'un mauvais formattage.