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
jqinstallés localement - Un dépôt Git contenant les dossiers
api/etweb/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é :
-
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'actionpush. - 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.
- Problème :
-
Mot de passe de jeton perdu
- Problème : Après une nouvelle extraction,
terraform applyré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_filene 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.
- Problème : Après une nouvelle extraction,
-
É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 pushchaque 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_listbloque les adresses situées en dehors de la liste. - Correction : Déplacer
garbage_collection_scheduleen 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.
- Problème : Un pipeline nocturne échoue sur
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 :
nameetlocationd'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
sha256qui 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 :