15 min de lecture

Objectifs d'apprentissage

À la fin de ce module, vous serez en mesure de:

  • Provisionner un Private Container Registry et ses jetons d'accès avec `ionoscloud_container_registry` et `ionoscloud_container_registry_token`
  • Authentifier le CLI Docker auprès du registre avec un jeton à portée limitée, et pousser et récupérer des images
  • Construire des images de production pour l'API et le frontend web de TaskBoard à l'aide de Dockerfiles multi-étapes
  • Mettre en œuvre un pipeline d'images qui étiquette chaque image avec le SHA de la commit Git et la pousse vers le registre
  • Configurer les identifiants CI pour GitHub Actions et GitLab CI afin de se connecter au registre sans exposer le jeton

Unité 3.1 : Container Registry et pipelines d'images

Introduction

Le module 2 a fourni à TaskBoard son réseau, son équilibreur de charge, son stockage et ses bases de données. L'application elle-même s'exécute toujours sous forme de fichiers copiés sur un serveur. Avant de pouvoir la déployer sur Managed Kubernetes dans l'unité 3.2, vous avez besoin d'images de conteneurs versionnées dans un registre accessible à votre cluster et à votre pipeline CI.

Le Private Container Registry vous le permet. Il prend en charge l'API HTTP v2 du registre Docker, de sorte que le CLI Docker et tout système CI qui communique avec cette API fonctionnent avec lui. L'accès nécessite toujours une authentification : vous créez des jetons avec des plages d'accès, et chaque client s'authentifie à l'aide d'un jeton.

Dans cette unité, vous provisionnez le registre et ses jetons à l'aide de Terraform, vous vous connectez avec Docker, vous construisez des images multi-étapes pour l'API et le frontend de TaskBoard, puis vous les poussez avec des étiquettes Git SHA. Dans le Code Lab, vous exécutez la boucle complète, de terraform apply à un tirage vérifié.

1. Provisionnement du registre avec Terraform

resource "ionoscloud_container_registry" "taskboard" {
  name     = "taskboard-registry-7f3a"
  location = "de/fra"

  garbage_collection_schedule {
    days = ["Sunday"]
    time = "03:00:00+00:00"
  }

  features {
    vulnerability_scanning = false
  }
}

La ressource nécessite un name et un location. Les deux sont immuables : modifier l'un ou l'autre force Terraform à détruire et recréer le registre, y compris toutes les images qu'il contient. Le registre est disponible dans la région FRA, emplacement de/fra.

1.1 Règles de nommage

Le nom du registre doit :

  • Être unique au niveau global pour tous les clients
  • Comprendre entre 3 et 63 caractères
  • Ne contenir que des caractères alphanumériques et des tirets
  • Commencer par un caractère de a à z et se terminer par un caractère alphanumérique

Comme le nom est global, ajoutez un suffixe aléatoire pour chaque environnement, comme vous l'avez fait pour les buckets Object Storage dans l'unité 2.4.

1.2 Analyse des vulnérabilités et collecte des ordures

L'analyse des vulnérabilités est un module payant. Dans le provider, elle est activée par défaut et ne peut pas être désactivée après activation. Si vous ne souhaitez pas l'activer, définissez vulnerability_scanning = false lors de la création du registre.

La collecte des ordures est désactivée par défaut. La suppression d'une image ou d'une étiquette ne libère pas de stockage : le registre masque les éléments supprimés, mais les données restent sur le disque jusqu'à l'exécution de la collecte des ordures. Le bloc garbage_collection_schedule configure une exécution hebdomadaire avec days et un time.

Pendant la collecte des ordures, le registre est en lecture seule et vous ne pouvez pas pousser d'images. Planifiez l'exécution en dehors de vos heures de déploiement, sinon une poussée CI échouera pendant son exécution.

1.3 Restriction de l'accès réseau et lecture du nom d'hôte

resource "ionoscloud_container_registry" "taskboard" {
  # ... arguments from Section 1
  api_subnet_allow_list = ["203.0.113.10/32"]
}

data "ionoscloud_container_registry" "taskboard" {
  id = ionoscloud_container_registry.taskboard.id
}

output "registry_hostname" {
  value = data.ionoscloud_container_registry.taskboard.hostname
}

Le registre est accessible depuis Internet public. api_subnet_allow_list limite les CIDR de sous-réseaux autorisés à se connecter ; une liste vide ou non définie signifie qu'aucune restriction n'est appliquée. La réponse de création ne contient pas d'hôte, car celui-ci n'a pas encore été alloué. Par conséquent, lisez hostname depuis la source de données une fois que le registre est en cours d'exécution.

2. Jetons et connexion Docker

Les clients Docker s'authentifient à l'aide de jetons de registre. Il n'existe ni dépôts publics ni accès non authentifié. Un jeton possède un nom, une date d'expiration facultative, un statut et une ou plusieurs plages d'accès.

2.1 Jetons en tant que code

resource "ionoscloud_container_registry_token" "ci_push" {
  registry_id           = ionoscloud_container_registry.taskboard.id
  name                  = "taskboard-ci-push"
  status                = "enabled"
  save_password_to_file = "ci-push.pass"

  scopes {
    name    = "taskboard/*"
    type    = "repository"
    actions = ["pull", "push"]
  }
}

resource "ionoscloud_container_registry_token" "k8s_pull" {
  registry_id           = ionoscloud_container_registry.taskboard.id
  name                  = "taskboard-k8s-pull"
  status                = "enabled"
  save_password_to_file = "k8s-pull.pass"

  scopes {
    name    = "taskboard/*"
    type    = "repository"
    actions = ["pull"]
  }
}

Un périmètre combine un type, un name et actions. Avec le type repository, le nom est le chemin du référentiel que le jeton peut accéder, et * agit comme un joker. Les actions sont pull, push et delete. Le type registry crée un jeton pouvant lister les référentiels du registre.

Créez un jeton par consommateur. Le jeton CI pousse ; le jeton de cluster de l'Unité 3.2 ne fait que tirer. Si un jeton de cluster est divulgué, personne ne peut l'utiliser pour écraser vos images.

2.2 Règles des jetons qui affectent votre code

Règle Valeur
Longueur du nom De 3 à 63 caractères, alphanumérique et tirets, commence par a-z
Modification du nom Impossible ; name est immuable
Date d'expiration Au moins 1 heure dans le futur, horodatage ISO 8601
À l'expiration Le jeton est supprimé, pas désactivé
Action de poussée Nécessite également l'action de tirage
Mot de passe Renvoyé une seule fois, à la création
Nom en double 409 Conflict

Le mot de passe est la partie critique. Le fournisseur documente save_password_to_file comme le seul moyen d'obtenir le jeton, et cela ne fonctionne qu'à la création. Déplacez le fichier dans votre coffre de secrets immédiatement après apply et supprimez-le localement. Si vous perdez le mot de passe, créez un nouveau jeton.

2.3 Connexion avec Docker

export CR_HOST="$(terraform output -raw registry_hostname)"
export CR_USERNAME="taskboard-ci-push"

docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin < ci-push.pass

docker login nécessite trois valeurs : le nom d'hôte du registre, le nom d'utilisateur et le mot de passe. Récupérez le nom d'utilisateur à partir de credentials de la réponse du jeton ; dans les exemples d'API, il correspond au nom du jeton. Transmettez le mot de passe via --password-stdin afin qu'il n'apparaisse jamais dans l'historique de votre shell ou dans la liste des processus.

Vous pouvez également créer un jeton via l'API. La réponse contient credentials.username et credentials.password :

curl --silent --request POST \
  "https://api.ionos.com/containerregistries/registries/$REGISTRY_ID/tokens" \
  --header "Authorization: Bearer $IONOS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"properties": {"name": "taskboard-hotfix", "expiryDate": null,
           "scopes": [{"name": "taskboard/*", "actions": ["pull", "push"], "type": "repository"}]}}' \
  | jq -r '.properties.credentials.password' > hotfix.pass

Notez les deux identifiants distincts : le jeton bearer de l'API Cloud (IONOS_TOKEN) gère les registres et les jetons ; le jeton du registre sert à se connecter à Docker.

3. Dockerfiles multi-étapes pour TaskBoard

Une construction multi-étapes compile dans une image et ne copie que le résultat dans une petite image d'exécution. Les outils de construction, les caches et les fichiers sources ne font pas partie de ce que vous publiez.

3.1 Le service API

# api/Dockerfile
FROM python:3.12-slim AS build
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
COPY --from=build /install /usr/local
COPY src/ ./src/
RUN useradd --uid 10001 taskboard
USER 10001
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

La première étape installe les dépendances dans /install ; la deuxième étape ne copie que cet arborescence et le code source. Le conteneur s'exécute en tant qu'utilisateur non root, ce sur quoi vous vous appuyez dans l'Unité 3.2.

3.2 L'interface Web

# web/Dockerfile
FROM node:22-alpine AS build
WORKDIR /web
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginxinc/nginx-unprivileged:alpine
COPY --from=build /web/dist /usr/share/nginx/html
EXPOSE 8080

L'image du frontend contient des fichiers statiques et un serveur web, mais rien provenant de Node.js. Les images plus petites sont poussées plus rapidement et contiennent moins de paquets à mettre à jour. Si vous avez activé l'analyse des vulnérabilités, chaque paquet que vous laissez hors de l'étape d'exécution représente une source de résultats en moins.

4. Le modèle de pipeline d'images

Chaque construction de TaskBoard suit les mêmes quatre étapes : construction, étiquetage avec le SHA Git, poussée et transmission de la référence au déploiement.

4.1 Étiquetage avec le SHA de la commit

SHA="$(git rev-parse --short=12 HEAD)"

docker build -t "$CR_HOST/taskboard/api:$SHA" api/
docker build -t "$CR_HOST/taskboard/web:$SHA" web/

docker push "$CR_HOST/taskboard/api:$SHA"
docker push "$CR_HOST/taskboard/web:$SHA"

Une étiquette SHA est immuable par convention : un commit, une image. Une étiquette mobile telle que latest rend le retour en arrière de l'Unité 3.3 une opération hasardeuse, car le cluster ne peut pas déterminer quelle version il exécute. Les noms de dépôts tels que taskboard/api correspondent à la portée taskboard/* de la section 2.1.

4.2 Passer un digest au déploiement

DIGEST="$(docker inspect --format '{{index .RepoDigests 0}}' "$CR_HOST/taskboard/api:$SHA")"
echo "$DIGEST"   # <registry-hostname>/taskboard/api@sha256:...

Le digest fixe le contenu exact de l'image. Votre manifeste de déploiement dans l'Unité 3.2 peut utiliser soit l'étiquette SHA, soit le digest ; le pipeline de l'Unité 3.3 l'insère dans le manifeste.

4.3 Limites de débit pour les serveurs de construction

Le registre limite chaque client :

Indicateur Limite Description
Nombre maximal de connexions simultanées par client 100 Le nombre le plus élevé de connexions TCP simultanées qu'un client unique (exemple : un serveur de construction ou un nœud de cluster) peut maintenir pour les opérations de Private Container Registry, telles que le téléchargement de couches. Le dépassement de cette limite entraîne le rejet de la connexion.
Nombre maximal de requêtes par seconde (RPS) par client 60 Le nombre maximal de requêtes API (exemple : récupérations, requêtes d'authentification par jeton, vérifications d'existence de couches) qu'un client unique peut envoyer à Private Container Registry par seconde. Les requêtes excessives entraînent une erreur 429 (Trop de requêtes).

Un serveur de construction partagé qui pousse de nombreuses images en parallèle peut atteindre ces limites. Limitez les poussées parallèles par exécuteur, et réessayez une 429 avec un délai d'attente, comme vous l'avez appris pour l'API Cloud dans l'Unité 1.1.

5. Intégration CI

Le pipeline a besoin de trois valeurs en tant que secrets : le nom d'hôte, le nom d'utilisateur et le mot de passe du jeton de push. Ne commitez jamais l'une d'entre elles.

5.1 GitHub Actions

- name: Log in to the registry
  env:
    CR_HOST: ${{ secrets.CR_HOST }}
    CR_USERNAME: ${{ secrets.CR_USERNAME }}
    CR_PASSWORD: ${{ secrets.CR_PASSWORD }}
  run: echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin

5.2 GitLab CI

before_script:
  - echo "$CR_PASSWORD" | docker login "$CR_HOST" --username "$CR_USERNAME" --password-stdin

Dans GitLab, définissez CR_PASSWORD comme variable CI/CD masquée et protégée afin qu'elle ne soit disponible que sur les branches protégées. Les flux de travail complets des deux systèmes sont présentés dans l'unité 3.3.

Si vous définissez api_subnet_allow_list, l'adresse du trafic sortant du runner doit figurer dans la liste. Les runners hébergés peuvent utiliser des adresses variables, il faut donc soit exécuter des runners auto-hébergés avec une adresse connue, soit laisser la liste vide et vous fier au jeton.

Fiche de référence rapide de l'API

Principaux points de terminaison de l'API pour le sujet de cette unité :

Méthode Point de terminaison Description
GET /locations Liste les emplacements où vous pouvez créer un registre
POST /registries Crée un registre
GET /registries/{registryId} Récupère un registre, y compris hostname et l'état
POST /registries/{registryId}/tokens Crée un jeton ; la réponse contient le mot de passe une seule fois
DELETE /registries/{registryId}/repositories/{repositoryName} Supprime un dépôt (encodez le nom en URL, par exemple taskboard%2Fapi)

URL de base : https://api.ionos.com/containerregistries Authentification : Authorization: Bearer <token>

Atelier de code

Objectif : Créer un Private Container Registry avec un jeton de push et un jeton de pull, construire les images API et web de TaskBoard à l'aide de Dockerfiles multi-étapes, les pousser avec des étiquettes Git SHA et vérifier un pull avec le jeton en lecture seule.

Prérequis :

  • Compte IONOS CLOUD avec un jeton API dans IONOS_TOKEN
  • Terraform, Docker et jq installés localement
  • Un dépôt Git contenant les dossiers api/ et web/ de TaskBoard ainsi que les Dockerfiles de la section 3

Étape 1 : Écrire registry.tf

Copiez la ressource registry de la section 1, la source de données et la sortie de la section 1.3 (sans api_subnet_allow_list), ainsi que les deux jetons de la section 2.1. Utilisez votre propre suffixe de nom. Ajoutez le bloc provider de l'unité 1.2 et une sortie supplémentaire :

output "registry_id" {
  value = ionoscloud_container_registry.taskboard.id
}
terraform init

Sortie attendue :

Terraform has been successfully initialized!

Étape 2 : Appliquer

terraform apply

Sortie attendue :

ionoscloud_container_registry.taskboard: Creation complete after ...
ionoscloud_container_registry_token.ci_push: Creation complete after ...
ionoscloud_container_registry_token.k8s_pull: Creation complete after ...
Outputs:
registry_hostname = "<registry-hostname>"

Étape 3 : Se connecter avec le jeton de poussée

export CR_HOST="$(terraform output -raw registry_hostname)"
docker login "$CR_HOST" --username taskboard-ci-push --password-stdin < ci-push.pass

Sortie attendue :

Login Succeeded

Étape 4 : Construire et pousser les deux images

SHA="$(git rev-parse --short=12 HEAD)"
for svc in api web; do
  docker build -t "$CR_HOST/taskboard/$svc:$SHA" "$svc/"
  docker push "$CR_HOST/taskboard/$svc:$SHA"
done

Sortie attendue :

...
<sha>: digest: sha256:... size: ...

Étape 5 : Listez les dépôts via l'API

REGISTRY_ID="$(terraform output -raw registry_id)"
curl --silent "https://api.ionos.com/containerregistries/registries/$REGISTRY_ID/repositories" \
  --header "Authorization: Bearer $IONOS_TOKEN" | jq -r '.items[].properties.name'

Sortie attendue :

taskboard/api
taskboard/web

Étape 6 : Vérifier le jeton de récupération uniquement

docker logout "$CR_HOST"
docker login "$CR_HOST" --username taskboard-k8s-pull --password-stdin < k8s-pull.pass
docker pull "$CR_HOST/taskboard/api:$SHA"
docker push "$CR_HOST/taskboard/api:$SHA"

Sortie attendue :

Login Succeeded
...
Status: Image is up to date for <registry-hostname>/taskboard/api:<sha>
...
(the push fails with an access denied error)

Liste de contrôle de validation :

  • [ ] Le registre et les deux jetons ont été créés par terraform apply
  • [ ] Les deux images se trouvent dans le registre sous taskboard/ avec l'étiquette SHA Git
  • [ ] Le jeton de récupération permet la récupération mais pas la poussée
  • [ ] Aucun mot de passe de jeton n'est engagé dans Git

Nettoyage :

Conservez le registre et le fichier k8s-pull.pass si vous poursuivez avec l'unité 3.2. Sinon :

terraform destroy -auto-approve
rm -f ci-push.pass k8s-pull.pass

Pièges courants

Erreurs de développement à éviter avec le sujet de cette unité :

  1. Poussée de jeton sans récupération

    • Problème : docker push échoue avec une erreur d'accès refusé, bien que le jeton possède l'action push.
    • Pourquoi cela arrive : L'action de poussée nécessite l'action de récupération. Docker vérifie les couches existantes avant de les téléverser.
    • Correction : Définir actions = ["pull", "push"] dans le périmètre du jeton.
  2. Mot de passe de jeton perdu

    • Problème : Après une nouvelle extraction, terraform apply réussit, mais personne ne possède le mot de passe du jeton CI.
    • Pourquoi cela arrive : Le mot de passe n'est renvoyé qu'une seule fois, lors de la création, et save_password_to_file ne fonctionne que lors de la création.
    • Correction : Stocker le fichier immédiatement dans votre coffre de secrets. Pour effectuer une rotation, remplacer le jeton : terraform apply -replace=ionoscloud_container_registry_token.ci_push, puis mettre à jour le secret CI.
  3. Échec de la poussée CI lors de la collecte des ordures ou depuis une adresse bloquée

    • Problème : Un pipeline nocturne échoue sur docker push chaque dimanche, ou chaque poussée depuis les exécutants hébergés échoue.
    • Pourquoi cela arrive : Le registre est en lecture seule pendant l'exécution de la collecte des ordures, et api_subnet_allow_list bloque les adresses situées en dehors de la liste.
    • Correction : Déplacer garbage_collection_schedule en dehors de vos heures de construction, et conserver l'adresse de trafic sortant de l'exécutant dans la liste d'autorisation, ou laisser la liste vide.

Résumé

Vous pouvez désormais doter TaskBoard d'une chaîne d'approvisionnement privée pour les images. Terraform crée le Private Container Registry dans de/fra et un jeton de portée par consommateur. Les Dockerfiles multi-étapes permettent de garder les images de l'API et du frontend de petite taille, chaque image porte le SHA Git de son commit, et les systèmes de CI se connectent avec un jeton issu de leur coffre de secrets.

Points clés :

  • name et location d'un registre sont immuables ; le nom est unique au niveau mondial
  • L'analyse de vulnérabilités est activée par défaut dans le fournisseur ; définissez vulnerability_scanning = false à la création si vous ne le souhaitez pas
  • Les clients Docker se connectent avec des jetons de registre ; le mot de passe du jeton n'est renvoyé qu'une seule fois
  • Utilisez des jetons distincts pour la poussée (CI, avec tirage et poussée) et le tirage (cluster)
  • Étiquetez les images avec le SHA Git ; respectez les limites par client de 100 connexions et 60 requêtes par seconde

Terminologie importante :

  • Jeton de registre : Une authentification avec des portées que la CLI Docker utilise pour se connecter au registre
  • Portée : Une combinaison de type, de nom de dépôt (avec l' joker *) et d'actions (pull, push, delete)
  • Construction multi-étapes : Un Dockerfile avec une étape de construction et une étape d'exécution minimale qui ne reçoit que la sortie de la construction
  • Digest d'image : Le hachage de contenu sha256 qui fixe une image exacte, indépendamment des étiquettes
  • Collecte des ordures : L'exécution planifiée qui libère le stockage des images supprimées ; le registre est en lecture seule pendant son exécution

Prochaines étapes

Continuer l'apprentissage : Unité 3.2 : Déploiement et exploitation de Kubernetes

Sujets connexes :