Aller au contenu principal

Pousser et tirer des images

Bêta

Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.

Les commandes sng registry sont en cours de diffusion sur les tenants.

Ce guide configure docker pour qu'il s'authentifie avec votre session sng, puis montre comment pousser, tirer et supprimer des images. Il se termine par l'utilisation de l'image dans une App.

Prérequis​

  • Une session de tenant : sng sso login, puis sng tenant use acme.
  • Un dépôt : déclaré par sng registry create web (Dépôts et rétention), ou créé automatiquement par sng registry build.
  • Le droit registry:push sur le dépôt (policy readwrite) pour pousser, registry:pull (policy readonly) pour tirer.
  • Docker installé, pour les étapes qui l'utilisent.

1. Brancher docker sur votre session​

sng registry login
docker now authenticates to ovh-gra-0.registry.dev.stackngo.fr with the session of tenant "acme"

La commande vérifie votre session auprès du registre, puis ajoute dans ~/.docker/config.json (ou $DOCKER_CONFIG/config.json) l'entrée "credHelpers": {"ovh-gra-0.registry.dev.stackngo.fr": "sng"}. Docker appelle alors docker-credential-sng, un lien vers sng, qui lui transmet la session courante et la renouvelle si besoin. Aucun mot de passe n'est stocké.

Si la commande avertit docker-credential-sng is not in PATH, ajoutez le dossier indiqué à votre PATH, sinon docker ne trouvera pas l'assistant.

2. Pousser une image​

Avec docker :

docker build -t ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0 .
docker push ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0

Ou avec sng, qui préfixe lui-même le registre et le tenant, pour une image déjà construite :

docker build -t web:1.0.0 .
sng registry build --from-image web:1.0.0
pushed ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0@sha256:4f1c9a…

--from-image IMAGE prend une image du démon docker local, sans reconstruire. Sans -t, il reprend le dernier composant du nom et le tag : ghcr.io/acme/tool:3 devient tool:3. Sans démon docker, poussez une archive (docker save ou archive OCI) :

sng registry build --from-tar web.tar -t web:1.0.0

3. Construire et pousser en une commande​

sng registry build . -t web:1.0.0
pushed ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0@sha256:4f1c9a…

sng registry build lance docker buildx build --push avec votre session. Il accepte -f, --platform, --build-arg et --target comme docker buildx. Sans -t, le dépôt porte le nom du dossier courant, tag latest.

Le dépôt n'a pas besoin d'exister : s'il n'est pas déclaré, sng registry build le déclare pour vous (privé, tous les tags gardés) et attend qu'il soit prêt avant de pousser. Pour régler la rétention ou la visibilité, déclarez-le d'abord avec sng registry create (Dépôts et rétention).

Une fois l'image poussée, sng registry build l'analyse sur votre poste avec trivy et affiche les vulnérabilités de sévérité HIGH ou plus (--severity pour changer le seuil). Sans trivy installé, un avertissement s'affiche et la commande réussit quand même. --fail-on CRITICAL fait échouer la commande si une vulnérabilité critique est trouvée (ou si l'analyse n'a pas pu avoir lieu) ; --no-scan saute l'analyse. Voir sng registry build.

4. Tirer une image​

docker pull ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0

ou

sng registry pull web:1.0.0
sng registry pull web@sha256:4f1c9a… --output web.tar   # archive au lieu du démon
pulled ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0@sha256:4f1c9a…

Sans tag ni digest, sng registry prend latest.

5. Utiliser l'image dans une App​

La plateforme tire l'image avec une clé d'accès au registre du tenant : votre session personnelle n'est pas transmise à vos applications. Déclarez une clé d'accès en lecture, puis citez son identifiant dans l'App.

infra/RegistryAccessKey/puller.yml
apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: puller
spec:
  repositories: [web]       # seulement le dépôt web
  actions: [pull]
infra/App/web.yml
apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: web
spec:
  imagePullSecrets: [puller-registry]   # identifiant préparé pour la clé "puller"
  services:
    web:
      image: ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0
      ports: ["8080"]
      ingress: { port: 8080 }
sng apply infra/RegistryAccessKey/puller.yml
sng apply infra/App/web.yml

L'identifiant puller-registry est prêt quelques instants après la clé. S'il ne l'est pas encore, le service reste en attente (ImagePullSecretNotFound) et démarre dès qu'il apparaît. Un dépôt public: true n'a pas besoin de clé d'accès. Voir Clés d'accès au registre.

Supprimer une image​

sng registry delete web:1.0.0
⚠ Suppression de l'image ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0 (tous les tags du même digest)
Tapez « oui » pour confirmer : oui
deleted ovh-gra-0.registry.dev.stackngo.fr/acme/web@sha256:4f1c9a…

Le tag est résolu en digest et c'est l'image qui est supprimée : tous les tags qui pointent vers le même digest disparaissent avec elle. Il faut registry:delete (policy readwrite). --yes saute la confirmation, et est obligatoire hors terminal interactif (CI).

sng registry delete web, sans tag ni digest, supprime la déclaration du dépôt : voir Dépôts et rétention.

Vérification​

sng registry pull web:1.0.0 --output /tmp/web.tar

Le digest affiché doit être celui de la poussée.

Pour aller plus loin​

  • Autre tenant : --tenant NAME vise un autre tenant sur lequel vous pouvez ouvrir une session (pull, build, delete d'une image, login). Les droits sont alors ceux de vos policies dans ce tenant.
  • Configuration de sng : l'hôte est celui du cluster choisi par sng config use-cluster (registry_url dans la configuration de sng, par exemple ovh-gra-0.registry.dev.stackngo.fr), ou de la variable STNG_REGISTRY_URL. credHelpers contient une entrée par hôte : relancez sng registry login après avoir changé de cluster. Une image du registre d'un autre cluster est refusée à l'application de l'App (image … is hosted on the registry of cluster …) : poussez-la sur le registre du cluster de l'App. Docker lance l'assistant sans les flags de sng : si vous utilisez --config, exportez STNG_CONFIG=<fichier> pour que l'assistant lise le même fichier.
  • Droits révoqués : un droit retiré prend effet au plus 5 minutes après la modification de la policy.
  • Dépôt public : docker pull ovh-gra-0.registry.dev.stackngo.fr/acme/docs:latest fonctionne sans aucune authentification.
  • Clients OCI : crane, oras, skopeo ou buildah utilisent la configuration docker écrite par sng registry login, donc votre session.

Erreurs fréquentes​

SymptômeCauseCorrection
registry refused the access (401) ou (403)Dépôt non déclaré (ou pas encore appliqué), droit manquant, ou session expiréesng registry create NAME, vérifier les policies (sng tenant policy list), sng tenant use NAME
invalid repository "acme/web": one lowercase component …Le nom contient un / ou des majuscules ; le tenant est ajouté par sngDonner seulement web:1.0.0
docker push : error getting credentials … not authenticatedL'assistant docker lit la configuration par défaut de sng, pas celle de --configexport STNG_CONFIG=<fichier>, ou sng sso login
registry authorization unavailable, retry laterLes droits ne peuvent pas être vérifiés pour l'instant ; aucun accès n'est accordé dans ce casRéessayer quelques instants plus tard
-t needs a tag, not a digestsng registry build -t web@sha256:…Donner un tag
--from-tar needs -t REPO[:TAG]--from-tar sans cibleAjouter -t REPO[:TAG]
confirmation requise : relancez avec --yes …delete lancé hors terminalAjouter --yes
Service d'App en Waiting, RegistryAccessPendingL'accès en lecture du tenant au registre n'est pas encore prêt (tenant tout juste créé)Attendre : le service démarre de lui-même ; signaler si cela dure plus de quelques minutes
Service d'App en Waiting, ImagePullSecretNotFoundL'App déclare un imagePullSecrets qui n'existe pas (encore)Corriger le nom, ou retirer imagePullSecrets pour revenir à l'accès par défaut

Voir aussi​