Registry

Every tenant can turn on one private container registry. Images live at registry.kupe.cloud/<tenant>/<repository>:<tag>, and only your tenant’s members, access tokens and connected clusters can reach them. Docker, Podman, Helm and any other OCI client can push to it, so container images, Helm charts and signatures are stored the same way.

Kupe operates the registry for you. You work with it through the Kupe console, the kupe CLI, the Kupe API and Terraform, with no separate installation to maintain or account to manage.

Concepts

Term	Meaning
Registry	Your tenant’s image store at `registry.kupe.cloud/<tenant>`. One per tenant, always named `registry`.
Repository	A named set of images inside the registry, such as `api` or `team-a/api`. Your first push to a name creates it.
Image	One pushed build, identified by its digest (`sha256:…`). A multi-platform image is an index that points to one image per platform.
Tag	A movable name for an image, such as `1.4.0` or `latest`. An image can have several tags, or none.
Cluster connection	Lets every pod in one of your clusters pull from the registry, and can give chosen namespaces a Secret to push with. See Connect a cluster.
Access token	A credential for CI and tools outside Kupe, pull only or push and pull, that expires 1 to 365 days after it is created. See Access tokens and CI.
Login session	The 12-hour credential `kupe registry login` gives a signed-in member. See Push and pull.

Turn on the registry

Turning the registry on needs a tenant admin.

kupe registry create

The command waits until the registry is Running. --storage-limit 10Gi sets a limit below your plan’s; --wait=false returns as soon as the request is accepted. See kupe registry create.

curl -X POST \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/registries" \
  -d '{}'

See Manage the registry with the API.

resource "kupe_registry" "this" {}

See Manage the registry with Terraform.

The registry moves through Pending and Provisioning to Running. It is Degraded when the platform cannot keep it running as configured, and Terminating while it is being deleted.

Storage limit

Each plan caps what the registry can store: see Limits. You can set a lower limit of your own, in Mi, Gi or Ti, and change it at any time. A raise above your plan’s cap is refused; a lower limit is always accepted, even below what the registry already stores.

When the registry is full, pushes are refused until you delete images or raise the limit. Pulls carry on. Stored size counts every layer once, however many images in your registry share it; see Managing images.

Suspension

While the tenant is suspended, the registry refuses pushes and pulls. A client that signed in just before the suspension can keep working for up to 30 minutes. Pods that are already running keep running, but a pod that needs to pull an image cannot start. Pushes and pulls work again when the tenant is reactivated.

Deleting the registry

Deleting the registry deletes every repository, image and tag in it, and they cannot be restored. Its cluster connections and access tokens are deleted with it, so connected clusters can no longer pull its images. A tenant cannot be deleted while it has a registry: delete the registry first.

Deletion protection is on when you create a registry, so a stray delete is refused with deletion_protected. To delete the registry, turn deletion protection off first, then delete it:

in the console, on the registry’s Settings tab;
with kupe registry update --deletion-protection=false, then kupe registry delete;
with PATCH {"deletionProtection": false} on the registry in the API, then DELETE;
with deletion_protection = false in Terraform, applied before terraform destroy.

Alerts

Every tenant with a registry gets four registry alert rules, evaluated against that tenant’s own metrics:

Alert	Severity	Fires when
`RegistryStorageAlmostFull`	warning	The registry has stored more than 80% of its storage limit for 10 minutes.
`RegistryStorageFull`	critical	The registry has stored more than 95% of its storage limit for 5 minutes. Pushes are refused once it is full.
`RegistryAccessTokenExpiring`	info	For an hour, at least one access token has been due to expire within 7 days. Login sessions are not counted.
`RegistryConnectionNotReady`	warning	A cluster connection has not been ready for 15 minutes. The alert names the cluster in its `connected_cluster` label.

The storage alerts need a limit to measure against: on a plan with unlimited storage they fire only if you set a limit of your own. Every alert carries the label registry="registry", and none carries a cluster label. Route them with a registry matcher in Notifications. The Registry dashboard shows the same figures.