Concepts

Container Registry concepts

This page explains the core concepts behind Thalassa Cloud Container Registry: how images are organised, addressed, scoped, and stored.

Registry endpoint

Each cloud region has a platform-managed registry hostname. Push and pull operations go directly to this endpoint — for example registry.nl-01.thalassa.cloud. The exact hostname depends on the region you selected when creating the namespace. It is shown on the namespace detail page and in repository listings.

One regional backend serves all namespaces in that region.

Namespace

A namespace is your isolated image namespace within a region (for example acme-platform). You create namespaces explicitly; the registry hostname and namespace together form the path prefix for all images in that namespace.

Field	Notes
Region	Required — determines registry hostname and data locality
Namespace	Required — lowercase ASCII, no spaces, max 255 characters
Description	Optional

The namespace name cannot be changed after creation.

Repository

A repository is an image name inside a namespace (for example api-server). Repositories are not created manually — they appear automatically when you push an image for the first time.

Tag and artifact

Concept	Description
Tag	A mutable label pointing at an image manifest (for example `v1.2.0`, `latest`)
Artifact	An immutable image manifest identified by digest (`sha256:…`). A tag references one artifact

Multiple tags can point at the same artifact. Deleting a tag does not necessarily remove the underlying artifact if other tags still reference it.

Configuration

Each namespace can have a configuration that controls:

Visibility — private (authenticated pull) or public (anonymous pull allowed)
Retention policy — optional rules to automatically delete old tags and artifacts

Until configuration exists, namespaces behave as private. See Namespace configuration for details.

Image address format

{registry-host}/{namespace}/{repository}:{tag}

Example:

registry.nl-01.thalassa.cloud/acme-platform/api-server:v1.2.0

You can also reference images by digest:

registry.nl-01.thalassa.cloud/acme-platform/api-server@sha256:abc123…

Organisation vs project scope

Namespaces follow the same scoping model as DNS zones and VPCs:

Scope	Behaviour
Organisation-level	Visible when no project is selected
Project-level	Created and listed only within an active project context

The namespace name must be unique per organisation (or per project) within a region. You can reuse the same namespace name in different regions.

How it works

You push or pull an image (Docker / containerd / CI)
        │
        ▼
Regional registry gateway authenticates via platform OIDC token
        │
        ▼
Image stored in regional registry backend
        │
        ▼
Platform records tags, artifacts, and usage events
        │
        ▼
Console and API reflect repository metadata

Push and pull operations go directly to the regional registry endpoint. The platform API manages namespaces, configuration, and metadata — not individual layer uploads.