Clés d'accès au registre

Disponible

Fonctionnalité déployée et prise en charge. Les champs et commandes décrits ici sont stables au sein de la version v1alpha1.

Une clé d'accès au registre (RegistryAccessKey) est un identifiant machine du registre, limité à des dépôts nommés et aux actions pull et/ou push. Elle sert là où votre session sng n'est pas disponible : avant tout pour que vos App tirent les images de vos dépôts privés, et, si vous l'autorisez, pour qu'une application de votre tenant (un job de CI par exemple) pousse des images.

Prérequis

• Une session de tenant (sng tenant use acme) et le droit deploy:write (policy readwrite).
• Au moins un dépôt déclaré (Dépôts et rétention).

1. Déclarer une clé d'accès

infra/RegistryAccessKey/puller.yml

apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: puller
spec:
  repositories: [web, api]   # noms de dépôts du tenant, ou "*" pour tous
  actions: [pull]            # pull et/ou push ; jamais delete
  rotateEveryDays: 90        # nouveau secret tous les 90 jours ; 0 ou absent = jamais

sng apply infra/RegistryAccessKey/puller.yml

Pour partir d'un gabarit : sng template gen RegistryAccessKey puller > puller.yml.

Ce que vous obtenez

Quelques instants après l'application, la plateforme prépare pour cette clé un identifiant de registre nommé <clé>-registry (ici puller-registry, ou le nom donné dans spec.secretName). Son nom d'utilisateur est accesskey/acme/puller ; son mot de passe est généré par la plateforme et n'apparaît jamais dans vos manifestes.

2. Tirer les images d'une App

C'est l'usage principal : citez l'identifiant dans imagePullSecrets.

infra/App/shop.yml

apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: shop
spec:
  imagePullSecrets: [puller-registry]
  services:
    api:
      image: ovh-gra-0.registry.dev.stackngo.fr/acme/api:1.4.2
      ports: ["8080"]

sng apply infra/App/shop.yml
sng app describe shop

L'identifiant est mis à jour automatiquement à chaque renouvellement : vos App n'ont rien à changer. Pour cet usage, une clé en pull seul suffit et limite l'exposition.

3. Utiliser la clé dans une application (ci: true)

Par défaut, les identifiants d'une clé ne servent qu'au tirage des images (imagePullSecrets) : une App qui les cite dans ses variables d'environnement (env ou envFrom) est refusée à l'application. Pour qu'une application du tenant les lise, par exemple un job de CI qui pousse des images, déclarez la clé avec ci: true :

infra/RegistryAccessKey/builder.yml

apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: builder
spec:
  repositories: [web]
  actions: [pull, push]
  ci: true                   # identifiants lisibles dans les variables d'environnement
  rotateEveryDays: 30

infra/App/builder.yml

apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: builder
spec:
  services:
    build:
      kind: job
      image: ovh-gra-0.registry.dev.stackngo.fr/acme/builder:1.0.0
      env:
        REGISTRY_USERNAME: { secret: builder-registry, key: username }
        REGISTRY_PASSWORD: { secret: builder-registry, key: password }

Réservez ci: true aux clés qui en ont besoin : une clé lisible par une application peut être recopiée par elle, alors qu'une clé réservée au tirage ne quitte jamais la plateforme.

4. Lire les identifiants depuis la CLI

Pour un outil qui ne peut pas ouvrir de session de tenant, un administrateur du tenant lit les identifiants courants d'une clé :

sng registry access-key credentials builder                   # nom d'utilisateur seul
sng registry access-key credentials builder --show-password   # avec le mot de passe

Le mot de passe change à chaque renouvellement : une copie (variable de CI, par exemple) doit être mise à jour après chaque rotation. Pour une CI hors de la plateforme, préférez la session OIDC du job : aucun secret à stocker, aucun renouvellement à suivre. Voir Construire et pousser des images depuis la CI.

5. Le renouvellement

Avec rotateEveryDays: N, la plateforme génère un nouveau secret N jours après le précédent renouvellement et met l'identifiant <clé>-registry à jour. L'ancien secret reste accepté pendant graceHours heures (24 h par défaut) : les tirages en cours se terminent sans erreur. Vos App ne voient rien : leur prochain tirage utilise le nouveau secret.

Pour obtenir un nouveau secret sans attendre l'échéance, renouvelez la clé à la demande, depuis la console (Renouveler le secret dans la liste des clés) ou avec la CLI :

sng registry access-key rotate puller
sng registry access-key credentials puller --show-password

L'ancien secret reste accepté pendant la période de grâce de la clé (graceHours, 24 h par défaut) : mettez à jour les copies (variable de CI, par exemple) pendant ce délai. Seul le secret précédent reste accepté : renouveler deux fois de suite met fin à la grâce du plus ancien. Ce renouvellement est réservé aux administrateurs du tenant. La clé de pull par défaut est gérée par la plateforme et ne se renouvelle pas à la demande.

Pour couper l'accès tout de suite, sans période de grâce, supprimez la clé (sng kind delete RegistryAccessKey puller) puis réappliquez-la. L'ancien secret est refusé dès la suppression ; les tirages des App qui l'utilisent échouent jusqu'à ce que le nouvel identifiant soit prêt.

Vérification

sng app describe shop

Le service passe Ready : l'image a été tirée avec la clé. Une image d'un dépôt hors de spec.repositories est refusée.

Ce que vous pouvez en attendre

• Ce qu'une clé ne peut pas faire : supprimer une image (delete est réservé aux sessions), accéder aux dépôts d'un autre tenant, ou accéder à un dépôt non déclaré même avec "*".
• Pas de policy à écrire : une clé n'est pas évaluée par vos policies ; ses droits sont exactement spec.repositories × spec.actions. En contrepartie, tout membre qui a deploy:write peut déclarer une clé en push : réservez ce droit en conséquence.
• Usage limité au tirage par défaut : sans ci: true, aucune application ne lit les identifiants de la clé.
• Révocation : supprimer le manifeste de la clé rend son secret inutilisable en quelques secondes, et retire l'identifiant <clé>-registry.
• Nom d'utilisateur : toujours accesskey/<tenant>/<nom>.

Erreurs fréquentes

Symptôme	Cause	Correction
sng apply refuse metadata : seul name est permis (…)	Le manifeste porte un label ou une annotation	Le retirer ; voir les alternatives ci-dessus
sng apply refuse une action delete	spec.actions n'accepte que pull et push	Supprimer avec une session (sng registry delete)
sng apply refuse une App qui cite <clé>-registry dans env ou envFrom	La clé n'a pas ci: true	Ajouter ci: true à la clé, ou n'utiliser l'identifiant qu'en imagePullSecrets
App en attente ImagePullSecretNotFound	La clé vient d'être appliquée, ou imagePullSecrets ne porte pas <clé>-registry	Attendre quelques instants ; vérifier le nom (spec.secretName s'il est donné)
App toujours en attente ImagePullSecretNotFound	Un autre identifiant porte déjà ce nom	Choisir un autre spec.secretName

Voir aussi

• Pousser et tirer des images
• Construire et pousser des images depuis la CI
• Déployer sans secret (OIDC)
• Référence : RegistryAccessKey, sng registry access-key credentials