Managing images

Every member can browse the registry. Deleting tags, images and repositories needs a tenant admin. In the console, open Registry, then the Images tab. The CLI commands are under kupe registry repo, kupe registry image and kupe registry tag.

Repositories, images and tags

A repository holds the images pushed to one name, such as team-a/api. An image is one pushed build, identified by its digest, and a tag is a name that points at one image and can be moved by the next push to it.

kupe registry repo list
kupe registry image list team-a/api
kupe registry image get team-a/api:v1.4.2

DIGEST               TAGS            SIZE      PLATFORMS                 PUSHED
sha256:906eba7069b0  v1.4.2, latest  46.0 MiB  linux/amd64, linux/arm64  1h
sha256:09ef6aa2d53f  v1.4.1          23.0 MiB  linux/amd64               17h
sha256:cba06b5736fa  untagged        22.0 MiB  linux/amd64               10d

Images are listed newest first, 25 to a page. Each has a type: image, chart for a Helm chart, index for a multi-platform image, or other for any other OCI artifact.

Multi-platform images

A multi-platform image is an index that points to one image per platform. The image list shows it once, with type index and its platforms, and the images it points to are not listed separately.

Counts differ by where you read them. A repository’s Images count, in the console and in kupe registry repo list, counts the index and each of its platform images, so one image built for two platforms counts three. The Registry dashboard’s Images panel counts the multi-platform image once.

A platform image cannot be deleted on its own: the registry refuses it with image_in_use. Delete the multi-platform image instead.

Untagged images

An image without tags stays in the registry until you delete it. Kupe never deletes untagged images for you, because a deployment pinned to a digest, or one platform’s image inside a multi-platform index, would stop working. An image loses its last tag when that tag is deleted, or moved to a newer image by a push.

Untagged images count towards your storage limit. List them with:

kupe registry image list team-a/api --untagged --all

In the console, turn on Untagged only on the repository’s page.

Delete a tag, an image or a repository

To delete	CLI	What goes
A tag	`kupe registry tag delete team-a/api:old`	The tag only. The image and its other tags stay.
An image	`kupe registry image delete team-a/api@sha256:<digest>`	The image and every tag on it. An image is deleted by digest.
A repository	`kupe registry repo delete team-a/old-api`	Every image and tag in the repository.

The console has the same actions on the repository and image pages, and asks you to confirm each one. Deleting a repository asks you to type its name. The API routes are in Manage the registry with the API.

A deleted image or repository cannot be restored. A pod already running from a deleted image keeps running, but a new pod that needs it cannot pull it.

Storage and clean-up

Stored size is what the registry counts against your storage limit. A layer is counted once in your registry, however many images share it, and layers in other tenants’ registries are never counted in yours.

Deleting an image lowers your stored total straight away, along with the stored size. The space itself is reclaimed by a clean-up that runs once a week.

A push refused at the storage limit can leave behind the layers it uploaded before it was refused. They count towards your stored total until the next weekly clean-up removes them.

The registry has no tag retention rules and no immutable tags: any push with push access can move a tag, and an admin can delete one.