RegistryAccessKey

Disponible

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

apiVersion	registry.stackngo.io/v1alpha1
kind	RegistryAccessKey
Appliqué par	sng apply
Commandes liées	sng apply, sng kind list RegistryAccessKey, sng kind delete RegistryAccessKey NAME, sng template gen RegistryAccessKey, sng registry access-key credentials NAME

À quoi ça sert

Une RegistryAccessKey est une clé d'accès au registre de votre tenant : un identifiant machine avec un nom d'utilisateur fixe, accesskey/<tenant>/<nom>, et un secret généré par la plateforme, écrit dans un Secret de type docker-registry (clé .dockerconfigjson) de votre tenant. Ce Secret s'utilise tel quel en imagePullSecrets d'une App. Avec ci: true, ses clés username / password peuvent aussi être lues dans les variables d'environnement d'une application du tenant (un job de CI qui pousse des images, par exemple). Une clé ne peut que pull et/ou push, uniquement sur les dépôts listés, et jamais supprimer.

Exemple minimal

puller.yml

apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: puller
spec:
  repositories: ["*"]
  actions: [pull]

sng apply puller.yml

Résultat : un Secret puller-registry, à référencer dans spec.imagePullSecrets d'une App.

Exemple complet commenté

ci.yml

apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: ci                       # identifiant : accesskey/<tenant>/ci
spec:
  repositories: [web, api]       # noms de RegistryRepository du tenant (1 à 64), ou "*" pour tous
  actions: [pull, push]          # pull et/ou push ; delete n'existe pas pour une clé
  ci: true                       # lisible dans env/envFrom d'une App ; défaut false : tirage seul
  rotateEveryDays: 90            # nouveau secret tous les 90 jours (0 à 365 ; 0 = jamais, défaut)
  graceHours: 48                 # l'ancien secret reste accepté 48 h après un renouvellement (0 à 720 ; 0 ou absent = 24 h)
  secretName: ci-registry-creds  # nom du Secret produit ; défaut : <nom>-registry

Champs

Règles de validation croisées

Le schéma refuse, dès sng apply :

• repositories vide ou de plus de 64 entrées ; chaque entrée est * ou un nom de dépôt valide (^[a-z0-9]+([._-][a-z0-9]+)*$) ;
• actions vide, de plus de 2 entrées, ou contenant autre chose que pull et push ;
• rotateEveryDays hors de 0 à 365 ; graceHours hors de 0 à 720 ; secretName de plus de 253 caractères ;
• une autre clé que name dans metadata (label, annotation).

Une App qui cite le Secret d'une clé dans env ou envFrom est refusée à l'application tant que la clé n'a pas ci: true. En imagePullSecrets, le Secret s'utilise dans tous les cas.

Une rotation immédiate ne passe pas par le manifeste : utilisez sng registry access-key rotate NAME ou la console.

Un nom de dépôt listé mais non déclaré n'est pas une erreur : la clé n'y a simplement aucun accès tant que le RegistryRepository n'existe pas.

RegistryAccessKey

RegistryAccessKey est une clé d'accès au registre, limitée aux dépôts de votre espace. La plateforme crée dans votre espace un secret d'authentification au registre (format docker config, utilisateur accesskey/<espace>/<nom>), utilisable par vos services pour tirer leurs images. Le statut n'affiche que l'empreinte SHA-256 du secret, jamais sa valeur.

Champ	Description	Défaut	Validation
apiVersion string	registry.stackngo.io/v1alpha1
kind string	RegistryAccessKey
metadata ObjectMeta	Seul metadata.name est à renseigner (nom de la ressource dans votre tenant).
spec RegistryAccessKeySpec
status RegistryAccessKeyStatus

RegistryAccessKeySpec

RegistryAccessKeySpec décrit les droits et le renouvellement de la clé d'accès.

Champ	Description	Défaut	Validation
repositories string array	Repositories : noms des RegistryRepository de votre espace accessibles avec cette clé, ou "*" pour tous.		MaxItems: 64 MinItems: 1 items:Pattern: ^(\*|[a-z0-9]+([._-][a-z0-9]+)*)$
actions AccessKeyAction array	Actions accordées sur ces dépôts : pull, push, ou les deux.		Enum: [pull push] MaxItems: 2 MinItems: 1
rotateEveryDays integer	RotateEveryDays renouvelle le secret tous les N jours (0 à 365) ; 0 désactive le renouvellement automatique.		Maximum: 365 Minimum: 0 Optional: {}
graceHours integer	GraceHours est la durée, en heures, pendant laquelle l'identifiant précédent reste valide après un renouvellement, pour ne pas couper les jobs qui l'utilisent encore. 0 : valeur par défaut de la plateforme (24 heures).		Maximum: 720 Minimum: 0 Optional: {}
secretName string	SecretName est le nom du secret créé dans votre espace (défaut : <nom>-registry).		MaxLength: 253 Optional: {}
ci boolean	CI autorise une application de votre espace à lire les identifiants de cette clé dans ses variables d'environnement (typiquement un job de CI qui pousse des images). Sans ce champ, les identifiants ne servent qu'aux tirages d'images (imagePullSecrets).	false	Optional: {}

RegistryAccessKeyStatus

RegistryAccessKeyStatus est l'état de la clé d'accès constaté par la plateforme.

Champ	Description	Défaut	Validation
observedGeneration integer	ObservedGeneration est la dernière version du manifeste prise en compte.
conditions Condition array	Conditions : Ready (ressource prête), Synced (registre à jour), Deleting (suppression en cours).
username string	Username est l'identifiant de connexion au registre : accesskey/<espace>/<nom>.
secretName string	SecretName est le nom du secret qui contient l'identifiant.
secretSHA256 string	SecretSHA256 est l'empreinte SHA-256 (hexadécimale) du secret courant, jamais sa valeur.
previousSecretSHA256 string	PreviousSecretSHA256 est l'empreinte de l'ancien secret, qui reste valide jusqu'à PreviousValidUntil pour que les téléchargements en cours survivent à un renouvellement.
previousValidUntil Time	PreviousValidUntil est la fin de validité de l'ancien secret.
lastRotationTime Time	LastRotationTime est la date d'émission du secret courant.
rotationToken string	RotationToken est réservé à la plateforme (renouvellement à la demande, pas encore disponible).

AccessKeyAction

Type sous-jacent : string

AccessKeyAction est une action accordée à une clé d'accès : pull ou push. La suppression est réservée aux utilisateurs.

Règles de validation :

• Enum: [pull push]

Valeur	Description
pull	Télécharger des images du dépôt.
push	Publier des images dans le dépôt.

Statut et conditions

Le status ne contient jamais le secret, seulement son empreinte SHA-256.

Champ	Contenu
username	accesskey/<tenant>/<nom>, à présenter au registre
secretName	nom du Secret produit
secretSHA256	empreinte du secret courant
previousSecretSHA256, previousValidUntil	empreinte de l'ancien secret et fin de sa période de grâce (graceHours heures après la rotation, 24 h par défaut)
lastRotationTime	date de la dernière émission d'un secret

Condition	True quand	False quand
Ready	le secret est émis et le Secret à jour (raison Reconciled)	un Secret du même nom existe et n'appartient pas à la clé (SecretOwnershipConflict)
Synced	posée à True avec Ready	—

reason	Explication	Action
Reconciled	Secret à jour	—
SecretOwnershipConflict	Un Secret nommé comme secretName (ou <nom>-registry) existe déjà et n'a pas été créé par cette clé ; il n'est pas écrasé	Changer spec.secretName, ou supprimer l'ancien Secret

Dans cette version, sng kind get RegistryAccessKey ci affiche le manifeste enregistré, sans le status : l'état d'une clé n'est pas encore lisible avec la CLI. Ses identifiants courants le sont, pour un administrateur du tenant : sng registry access-key credentials ci [--show-password] (référence).

Ce qui se passe à l'application

Création. Un secret aléatoire de 256 bits est émis et écrit dans le Secret <nom>-registry de votre tenant, avec les clés .dockerconfigjson, username et password.

Rotation. Un nouveau secret est émis :

Déclencheur	Période de grâce de l'ancien secret
rotateEveryDays échu depuis lastRotationTime	graceHours (24 h par défaut)
Secret modifié ou altéré à la main	graceHours (24 h par défaut)
Secret supprimé à la main	aucune (plus personne ne détient l'ancien)

La période de grâce laisse aux jobs et aux tirages qui utilisent encore l'ancien secret le temps de se terminer ou d'être mis à jour : allongez graceHours si une copie du secret (une variable de CI, par exemple) n'est mise à jour qu'à la main.

Le Secret est mis à jour en place : les App qui le référencent utilisent le nouveau secret au prochain tirage d'image, sans redéploiement.

Mise à jour. Changer repositories, actions ou graceHours prend effet en quelques secondes, sans nouveau secret (une nouvelle graceHours vaut pour les renouvellements suivants). Abaisser rotateEveryDays sous l'âge du secret courant déclenche une rotation immédiate. Changer secretName crée un nouveau Secret avec un nouveau secret, sans période de grâce pour l'ancien.

Ce qui se passe quand vous supprimez

sng kind delete RegistryAccessKey ci : la clé cesse d'être acceptée en quelques secondes et son Secret est supprimé avec lui. Les App qui le référencent ne peuvent plus tirer de nouvelle image (les conteneurs déjà démarrés continuent de tourner).

Erreurs fréquentes

Symptôme	Cause	Correction
sng apply refuse : metadata : seul name est permis (annotations refusé)	Annotation (ou label) dans metadata	La retirer ; pour forcer une rotation, sng registry access-key rotate NAME
sng apply refuse une valeur delete dans actions	Les clés d'accès ne suppriment jamais	Supprimer avec une session (sng registry delete)
sng apply refuse une App qui cite le Secret de la clé dans env ou envFrom	La clé n'a pas ci: true	Ajouter ci: true, ou n'utiliser le Secret qu'en imagePullSecrets
Ready=False, SecretOwnershipConflict	Nom de Secret déjà pris	Autre spec.secretName
docker pull refusé avec le bon secret	Dépôt hors de repositories, dépôt non déclaré, ou dépôt d'un autre tenant	Ajouter le dépôt ou "*" ; déclarer le RegistryRepository
Refus après une rotation, une fois la période de grâce passée	Une copie de l'ancien secret (variable CI) n'a pas été mise à jour	Recopier le secret courant (sng registry access-key credentials NAME --show-password)

Voir aussi

• Guides : Clés d'accès au registre, Pousser et tirer des images, Construire et pousser des images depuis la CI
• CLI : sng kind, sng apply, sng registry access-key credentials
• Autres kinds : RegistryRepository, App