RegistryAccessKey

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

apiVersion	registry.stackngo.io/v1alpha1
kind	RegistryAccessKey
Applied by	sng apply
Related commands	sng apply, sng kind list RegistryAccessKey, sng kind delete RegistryAccessKey NAME, sng template gen RegistryAccessKey, sng registry access-key credentials NAME

What it is for

A RegistryAccessKey is an access key for your tenant's registry: a machine credential with a fixed username, accesskey/<tenant>/<nom>, and a secret generated by the platform, written to a docker-registry Secret (key .dockerconfigjson) in your tenant. This Secret can be used as is in the imagePullSecrets of an App. With ci: true, its username / password keys can also be read in the environment variables of an application of the tenant (a CI job that pushes images, for example). A key can only pull and/or push, only on the listed repositories, and never delete.

Minimal example

puller.yml

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

sng apply puller.yml

Result: a puller-registry Secret, to reference in the spec.imagePullSecrets of an App.

Complete annotated example

ci.yml

apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: ci                       # identifier: accesskey/<tenant>/ci
spec:
  repositories: [web, api]       # RegistryRepository names in the tenant (1 to 64), or "*" for all
  actions: [pull, push]          # pull and/or push; delete does not exist for a key
  ci: true                       # readable in env/envFrom of an App; default false: pulls only
  rotateEveryDays: 90            # new secret every 90 days (0 to 365; 0 = never, default)
  graceHours: 48                 # the old secret stays accepted 48 h after a renewal (0 to 720; 0 or absent = 24 h)
  secretName: ci-registry-creds  # name of the produced Secret; default: <nom>-registry

Fields

Cross-field validation rules

The schema rejects, as early as sng apply:

• an empty repositories or one with more than 64 entries; each entry is * or a valid repository name (^[a-z0-9]+([._-][a-z0-9]+)*$);
• an empty actions, one with more than 2 entries, or one containing anything other than pull and push;
• rotateEveryDays outside 0 to 365; graceHours outside 0 to 720; a secretName longer than 253 characters;
• any key other than name in metadata (label, annotation).

An App that names the Secret of a key in env or envFrom is refused at apply time as long as the key does not have ci: true. In imagePullSecrets, the Secret can be used in all cases.

An immediate rotation does not go through the manifest: use sng registry access-key rotate NAME or the console.

A repository name that is listed but not declared is not an error: the key simply has no access to it until the RegistryRepository exists.

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.

Status and conditions

The status never contains the secret, only its SHA-256 fingerprint.

Field	Content
username	accesskey/<tenant>/<nom>, to present to the registry
secretName	name of the produced Secret
secretSHA256	fingerprint of the current secret
previousSecretSHA256, previousValidUntil	fingerprint of the old secret and end of its grace period (graceHours hours after the rotation, 24 h by default)
lastRotationTime	date a secret was last issued

Condition	True when	False when
Ready	the secret is issued and the Secret is up to date (reason Reconciled)	a Secret with the same name exists and does not belong to the key (SecretOwnershipConflict)
Synced	set to True along with Ready	—

reason	Explanation	Action
Reconciled	Secret up to date	—
SecretOwnershipConflict	A Secret named like secretName (or <nom>-registry) already exists and was not created by this key; it is not overwritten	Change spec.secretName, or delete the old Secret

In this version, sng kind get RegistryAccessKey ci shows the saved manifest, without the status: a key's state cannot be read with the CLI yet. Its current credentials can, for a tenant administrator: sng registry access-key credentials ci [--show-password] (reference).

What happens when you apply

Creation. A random 256-bit secret is issued and written to the <nom>-registry Secret in your tenant, with the keys .dockerconfigjson, username, and password.

Rotation. A new secret is issued:

Trigger	Grace period of the old secret
rotateEveryDays elapsed since lastRotationTime	graceHours (24 h by default)
Secret modified or tampered with by hand	graceHours (24 h by default)
Secret deleted by hand	none (nobody holds the old one anymore)

The grace period gives the jobs and pulls that still use the old secret time to finish or to be updated: increase graceHours if a copy of the secret (a CI variable, for example) is only updated by hand.

The Secret is updated in place: the Apps that reference it use the new secret on their next image pull, without redeployment.

Update. Changing repositories, actions or graceHours takes effect within a few seconds, without a new secret (a new graceHours applies to the following renewals). Lowering rotateEveryDays below the age of the current secret triggers an immediate rotation. Changing secretName creates a new Secret with a new secret, with no grace period for the old one.

What happens when you delete

sng kind delete RegistryAccessKey ci: the key stops being accepted within a few seconds and its Secret is deleted along with it. The Apps that reference it can no longer pull a new image (containers that are already running keep running).

Common errors

Symptom	Cause	Fix
sng apply rejects: metadata : seul name est permis (annotations refusé)	Annotation (or label) in metadata	Remove it; to force a rotation, sng registry access-key rotate NAME
sng apply rejects a delete value in actions	Access keys never delete	Delete with a session (sng registry delete)
sng apply rejects an App that names the key's Secret in env or envFrom	The key does not have ci: true	Add ci: true, or use the Secret in imagePullSecrets only
Ready=False, SecretOwnershipConflict	Secret name already taken	Another spec.secretName
docker pull refused with the right secret	Repository not in repositories, undeclared repository, or another tenant's repository	Add the repository or "*"; declare the RegistryRepository
Refused after a rotation, once the grace period is over	A copy of the old secret (CI variable) was not updated	Copy the current secret again (sng registry access-key credentials NAME --show-password)

See also

• Guides: Registry access keys, Push and pull images, Build and push images from CI
• CLI: sng kind, sng apply, sng registry access-key credentials
• Other kinds: RegistryRepository, App