Push and pull images

Beta

Being rolled out. The interface described here is the one of the next release: it may still change, and may not be enabled on your tenant yet.

The sng registry commands are being rolled out to tenants.

This guide configures docker so that it authenticates with your sng session, then shows how to push, pull and delete images. It ends with using the image in an App.

Prerequisites

A tenant session: sng sso login, then sng tenant use acme.
A repository: declared by sng registry create web (Repositories and retention), or created automatically by sng registry build.
The registry:push right on the repository (policy readwrite) to push, registry:pull (policy readonly) to pull.
Docker installed, for the steps that use it.

1. Connect docker to your session

sng registry login

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

The command checks your session with the registry, then adds to ~/.docker/config.json (or $DOCKER_CONFIG/config.json) the entry "credHelpers": {"ovh-gra-0.registry.dev.stackngo.fr": "sng"}. Docker then calls docker-credential-sng, a link to sng, which passes it the current session and renews it if needed. No password is stored.

If the command warns docker-credential-sng is not in PATH, add the indicated folder to your PATH, otherwise docker will not find the helper.

2. Push an image

With 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

Or with sng, which prefixes the registry and the tenant itself, for an image that is already built:

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 takes an image from the local docker daemon, without rebuilding. Without -t, it reuses the last component of the name and the tag: ghcr.io/acme/tool:3 becomes tool:3. Without a docker daemon, push an archive (docker save or OCI archive):

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

3. Build and push in one command

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 runs docker buildx build --push with your session. It accepts -f, --platform, --build-arg and --target like docker buildx. Without -t, the repository is named after the current directory, tag latest.

The repository does not need to exist: if it is not declared, sng registry build declares it for you (private, all tags kept) and waits for it to be ready before pushing. To tune retention or visibility, declare it first with sng registry create (Repositories and retention).

Once the image is pushed, sng registry build scans it on your machine with trivy and lists the vulnerabilities of severity HIGH or higher (--severity to change the threshold). Without trivy installed, a warning is printed and the command still succeeds. --fail-on CRITICAL makes the command fail if a critical vulnerability is found (or if the scan could not take place); --no-scan skips the scan. See sng registry build.

4. Pull an image

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

sng registry pull web:1.0.0
sng registry pull web@sha256:4f1c9a… --output web.tar   # archive instead of the daemon

pulled ovh-gra-0.registry.dev.stackngo.fr/acme/web:1.0.0@sha256:4f1c9a…

Without a tag or digest, sng registry takes latest.

5. Use the image in an App

The platform pulls the image with a registry access key of the tenant: your personal session is not passed to your applications. Declare a read access key, then name its credential in the App.

infra/RegistryAccessKey/puller.yml
apiVersion: registry.stackngo.io/v1alpha1
kind: RegistryAccessKey
metadata:
  name: puller
spec:
  repositories: [web]       # only the web repository
  actions: [pull]

infra/App/web.yml
apiVersion: deploy.stackngo.io/v1alpha1
kind: App
metadata:
  name: web
spec:
  imagePullSecrets: [puller-registry]   # credential prepared for the key "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

The puller-registry credential is ready a few moments after the key. If it is not ready yet, the service stays pending (ImagePullSecretNotFound) and starts as soon as it appears. A public: true repository does not need an access key. See Registry access keys.

Delete an 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…

The tag is resolved to a digest and it is the image that is deleted: all tags that point to the same digest disappear with it. You need registry:delete (policy readwrite). --yes skips the confirmation, and is required outside an interactive terminal (CI).

sng registry delete web, without a tag or digest, deletes the repository's declaration: see Repositories and retention.

Verification

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

The displayed digest must be the one from the push.

Going further

Another tenant: --tenant NAME targets another tenant on which you can open a session (pull, build, delete of an image, login). The rights are then those of your policies in that tenant.
sng configuration: the host is the one of the cluster selected by sng config use-cluster (registry_url in the sng configuration, for example ovh-gra-0.registry.dev.stackngo.fr), or comes from the STNG_REGISTRY_URL variable. credHelpers holds one entry per host: run sng registry login again after switching cluster. An image from another cluster's registry is rejected when the App is applied (image … is hosted on the registry of cluster …): push it to the registry of the App's cluster. Docker launches the helper without the sng flags: if you use --config, export STNG_CONFIG=<file> so that the helper reads the same file.
Revoked rights: a removed right takes effect at most 5 minutes after the policy is modified.
Public repository: docker pull ovh-gra-0.registry.dev.stackngo.fr/acme/docs:latest works without any authentication.
OCI clients: crane, oras, skopeo or buildah use the docker configuration written by sng registry login, hence your session.

Common errors

Symptom	Cause	Fix
`registry refused the access (401)` or `(403)`	Repository not declared (or not applied yet), missing right, or expired session	`sng registry create NAME`, check the policies (`sng tenant policy list`), `sng tenant use NAME`
`invalid repository "acme/web": one lowercase component …`	The name contains a `/` or uppercase letters; the tenant is added by `sng`	Give only `web:1.0.0`
`docker push`: `error getting credentials … not authenticated`	The docker helper reads the default `sng` configuration, not that of `--config`	`export STNG_CONFIG=<file>`, or `sng sso login`
`registry authorization unavailable, retry later`	Rights cannot be checked for now; no access is granted in this case	Try again a few moments later
`-t needs a tag, not a digest`	`sng registry build -t web@sha256:…`	Give a tag
`--from-tar needs -t REPO[:TAG]`	`--from-tar` without a target	Add `-t REPO[:TAG]`
`confirmation requise : relancez avec --yes …`	`delete` run outside a terminal	Add `--yes`
App service in `Waiting`, `RegistryAccessPending`	The tenant's read access to the registry is not ready yet (tenant just created)	Wait: the service starts on its own; report it if it lasts more than a few minutes
App service in `Waiting`, `ImagePullSecretNotFound`	The App declares an `imagePullSecrets` that does not exist (yet)	Fix the name, or remove `imagePullSecrets` to go back to the default access

Prerequisites​

1. Connect docker to your session​

2. Push an image​

3. Build and push in one command​

4. Pull an image​

5. Use the image in an App​

Delete an image​

Verification​

Going further​

Common errors​

See also​