Lors de la migration des services sur cluster Scaleway, nous avons également migré nos packages npm, précédemment hébergés dans un container Velero dans l’ancien cluster, vers le “Package Registry” proposé gratuitement par gitlab.com .
Ce billet porte sur l’utilisation de ce registre.
Accès au Registry
Le “projet source“, hébergeant le Package Registry pour les packages Ceneau communs, est ‘bo-common’. Dans la suite, ‘source_project_id’ fait référence à l’id du projet source sur Gitlab.
Poste de développement
Lorsqu’on travaille sur un projet applicatif (exchange, maintenance, etc.), il est nécessaire que le poste de développement puisse atteindre le registry en lecture.
Lorsqu’on travaille sur le projet ‘bo-common’, pour pouvoir publier de nouvelles version de ce package, il est nécessaire que le poste de développement puisse atteindre le registry en écriture.
- Création d’un Deploy Token par développeur
Chaque développeur Ceneau doit donc créer un Deploy Token associé par poste de développement (afin de pouvoir les désactiver en cas de compromission), avec les droits d’écriture (write_package_registry) sur le registry.
Où?
gitlab.com > projet source > Settings > Repository > Deploy Tokens
- Configuration de l’authentification npm sur poste de développement
Npm peut être configuré globalement sur le poste de développement avec cette commande (à utiliser même si yarn est employé pour les autres opérations courantes):
npm config set -- https://gitlab.com/api/v4/projects/<source_project_id>/packages/npm/:_authToken=<deploy_token_password>Configuration npm par projet (service consommateur)
Ceci ne concerne que les projets utilisant les packages npm.
- Configuration de cible de dépôt par projet
Le fichier .npmrc cible le répertoire de dépôt en fonction du scope npm (ici, ‘@ceneau’ est le scope des packages Ceneau).
Ce fichier permet au développeur de rapatrier les packages Ceneau dans son service, et est également utilisé dans le build de l’image Docker ainsi que dans les pipelines CI.
Le fichier .npmrc doit contenir :
@ceneau:registry=https://gitlab.com/api/v4/projects/<source_project_id>/packages/npm/- Dockerfile
Les Dockerfiles des projets utilisant npm doivent utiliser le .npmrc du projet pour cibler le dépôt de package, mais également s’authentifier auprès du dépôt npm (comme pour le poste de développement; mais ici, le build de l’image va s’opérer dans un environnement différent propre à Docker).
Exemple de configuration dans un Dockerfile, utilisant une variable de build:
ARG PACKAGE_REGISTRY_ACCESS_TOKEN
...
COPY --chown=node:node .npmrc .
RUN echo >> .npmrc
RUN echo "//gitlab.com/api/v4/projects/<source_project_id>/packages/npm/:_authToken=${PACKAGE_REGISTRY_ACCESS_TOKEN}" >> .npmrc
RUN yarn install
RUN rm -f .npmrcNOTE: on ajoute toujours une nouvelle ligne à .npmrc au cas où un retour à la ligne n’existe pas déjà dedans.
NOTE: bien dégager le .npmrc qui contient le Deploy Token après l’avoir utilisé.
IMPORTANT: il était avant courant de builder manuellement l’image Docker d’un service sur son poste de développement ou un serveur. Cette pratique est maintenant caduque. Il faudrait pour cela passer au build la valeur du Deploy Token créé pour le poste de développement en argument, qu’il ne faut surtout pas laisser trainer dans les fichiers de dev, ou pire, le committer.
Si cela était cependant nécessaire, il est préconisé de mettre le Deploy Token du poste de développement en variable d’environnement de son OS (Windows, Linux), nommée CENEAU_PACKAGE_REGISTRY_ACCESS_TOKEN afin de pouvoir l’utiliser et le passer en argument de build à Docker (–build-arg PACKAGE_REGISTRY_ACCESS_TOKEN=”${CENEAU_PACKAGE_REGISTRY_ACCESS_TOKEN}”).
- Pipeline CI
Enfin, les pipelines Gitlab CI `.gitlab-ci.yml` de chaque projet doivent être adaptés pour accéder au registry.
Pour ce faire, Gitlab met à disposition une variable spéciale $CI_JOB_TOKEN, générée automatiquement à chaque lancement de pipeline et dont la durée de vie est limitée à l’exécution du pipeline. En utilisant ce jeton spécial, il est possible pour un projet d’interagir avec un autre projet du même groupe (à condition que ce projet cible l’y autorise, voir point suivant).
Passage du token en argument de build Docker:
docker build ... --build-arg PACKAGE_REGISTRY_ACCESS_TOKEN="${CI_JOB_TOKEN}"ATTENTION! cet argument est à passer à toutes les occurrences de docker build dans le fichier du pipeline.
Utilisation du token dans la phase pipeline de test
Si le pipeline inclut une phase de test (avec ‘yarn install’ et ‘yarn test:ci’ par exemple), ces tests s’exécutent de nouveau dans un nouvel environnement (autre que le poste de développement ou le build Docker), auquel on doit de nouveau passer le token, afin que ‘yarn install’ puisse rapatrier les packages Ceneau. Dans la phase de test, mettre ce bloc afin de compléter le `.npmrc` utilisé lors de cette phase:
before_script:
# Add access token authentication to npm configuration to reach the package registry (on another project)
- echo >> .npmrc
- echo "//gitlab.com/api/v4/projects/<source_project_id>/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc- Autorisation d’accès au niveau du projet source
Il est impératif que le projet source autorise le projet consommateur à utiliser ses CI_JOB_TOKENs pour accéder à ses ressources (sans quoi un 404 sera retourné pour signifier qu’il n’en a pas l’autorisation).
Sur gitlab.com > projet source > Settings > CI/CD > Token Access :
– bien vérifier que l’option “Limit access to this project” est activée (sécurité)
– dans “Allow CI job tokens from the following projects to access this project”, ajouter le projet consommateur en utilisant son chemin (exemple: pour un projet sur https://gitlab.com/masociete/mongroupe/monprojet, indiquer “masociete/mongroupe/monprojet”).