Skip to main content

Registry tokens for docker, CI and Kubernetes

View as MarkdownOpen in ClaudeOpen in ChatGPT

A registry token is the password that docker, your CI pipelines and your Kubernetes clusters use to log in to the Cloider Container Registry. Each token has a scope (all projects or only some), a permission (Pull only or Pull & push) and an optional expiry. This page explains how tokens work and how to create, use, change, rotate and delete them with every tool.

At a glance​

UsernameYour account's registry username, the same for every token
PasswordThe token's secret, shown once when the token is created
ScopeAll projects, including ones created later, or Only specific projects
PermissionPull & push (pull, push and delete images) or Pull only (pull images)
ExpiryNever, or 1 to 3650 days. Can't be changed after creation
Limit50 tokens per account
Where to manageRegistry page, Tokens tab, or Access Control, Registry Tokens tab. Also the CLI, Terraform, API and MCP
CostFree

How registry tokens work​

A registry login is a username and a password. On Cloider:

  • The username is your account's registry username. It is created the first time you need one, from the account's email address, and never changes. Every token of the account logs in with it.
  • The password is a token's secret. The secret tells the registry which token is logging in, and so which projects it reaches and what it may do.

Docker and other clients keep one login per registry host. All projects share registry.cloider.com, so a machine is logged in with one token at a time. That's why a token can reach several projects: give each machine, pipeline or cluster one token that covers every project it needs, rather than one token per project.

What each permission allows​

ActionPull onlyPull & push
Log inYesYes
Pull images, list repositories and tagsYesYes
Push images and tagsNoYes
Delete images, tags and repositories through the registry APINoYes
Change project settings, policies or create tokensNoNo

Tokens never manage projects. Settings, policies and other tokens are changed with your Cloider login or an API token, so a leaked registry token can't make a project public, raise its storage limit or create more tokens.

Which token for which job?​

Used byScopePermissionExpiryExample name
Your computerAll projectsPull & push30 days (cloider registry login does this for you)cloider cli (macbook)
A CI pipeline that builds and pushesThe projects it pushes toPull & push90 days or 1 year, rotatedci-deploy
A Kubernetes cluster or server that runs imagesThe projects it runsPull only1 year or neverprod-cluster
A deploy step that only pullsThe projects it deploysPull only90 daysdeploy-staging

Create a token​

  1. Open Registry in the sidebar and go to the Tokens tab. (The same list is in Access Control, on the Registry Tokens tab.)
  2. Click Create Token. The button is disabled until you have a project that is Ready.
  3. In Name, describe what the token is for, for example ci-deploy or prod-cluster. Up to 64 characters.
  4. Under Projects, choose All projects, including ones created later, or Only specific projects and pick them from the list.
  5. Under Permission, choose Pull & push (pull, push and delete images) or Pull only (pull images, for clusters and deploys).
  6. In Expires, choose Never, 7 days, 30 days, 90 days or 1 year. The expiry can't be changed later.
  7. Click Create token.

The Token created dialog shows, once:

  • Registry host, Username and Secret, each copied with a click,
  • a Docker login command,
  • a Kubernetes pull secret command,
  • a Download JSON button that saves the login in Docker's config.json format, usable as ~/.docker/config.json, as GitLab's DOCKER_AUTH_CONFIG or as a Kubernetes .dockerconfigjson secret.

Copy what you need, then click I've saved the secret. The secret can't be shown again.

Access Control, Registry Tokens tab, listing tokens with their name, username, projects, permission and expiry
Registry tokens with their scope, permission and expiry.

Use a token​

docker login​

echo "$CLOIDER_REGISTRY_SECRET" | docker login registry.cloider.com -u acme --password-stdin

Podman, nerdctl, skopeo, crane and helm take the same username and secret; see Push and pull images.

Kubernetes pull secret​

kubectl create secret docker-registry cloider-registry \
  --docker-server=registry.cloider.com \
  --docker-username='acme' \
  --docker-password="$CLOIDER_REGISTRY_SECRET" \
  -n default

Secrets are per namespace: add -n <namespace> to create it where the pod runs. Then reference cloider-registry in imagePullSecrets. See Use with Kubernetes.

Docker config.json​

The Download JSON button, or this command, gives the login in Docker's config.json format:

AUTH=$(printf '%s:%s' acme "$CLOIDER_REGISTRY_SECRET" | base64 | tr -d '\n')
cat > cloider-registry.json <<EOF
{
  "auths": {
    "registry.cloider.com": {
      "username": "acme",
      "password": "$CLOIDER_REGISTRY_SECRET",
      "auth": "$AUTH"
    }
  }
}
EOF

Use it as ~/.docker/config.json, as a CI variable such as GitLab's DOCKER_AUTH_CONFIG, or as the .dockerconfigjson key of a Kubernetes Secret.

cloider registry login for your own computer​

For your own machine you don't need to create a token by hand: cloider registry login creates one labelled cloider cli (<hostname>) that reaches every project, with a 30 day expiry by default, and logs docker in with it. Running it again replaces that token. See Push and pull images.

List tokens​

Open Registry, Tokens (or Access Control, Registry Tokens). The table shows each token's Name, Username, Projects (All projects, the project names, or None left when every project it named was deleted), Permission (Pull & push or Pull only), and Expires (a date, Never, or Expired).

Change a token​

You can change a token's name, projects and permission. The change applies to the existing secret, so nothing has to log in again. The expiry can't be changed: create a new token instead.

  1. In the token list, click the pencil (Edit) next to the token.
  2. Change Name, Projects or Permission.
  3. Click Save changes.

Delete a token​

Deleting a token revokes it right away: anything still logged in with it can no longer pull or push. Clusters that already pulled an image keep running it, but can't pull again (for example on a new node or a restart).

  1. In the token list, click the trash icon (Delete) next to the token.
  2. In Delete Token, click Delete.

Rotate a token​

To replace a token's secret without downtime:

  1. Create a new token with the same scope and permission, for example ci-deploy-2027.
  2. Put the new secret everywhere the old one is used: CI variables, Kubernetes Secrets, servers.
  3. Check that pulls and pushes work with the new secret.
  4. Delete the old token.

For a Kubernetes pull secret, replace it in place:

kubectl create secret docker-registry cloider-registry \
  --docker-server=registry.cloider.com \
  --docker-username='acme' \
  --docker-password="$NEW_SECRET" \
  -n default --dry-run=client -o yaml | kubectl apply -f -

With Terraform, the time_rotating resource and create_before_destroy rotate a token on a schedule; see cloider_registry_token.

Expired tokens​

When a token reaches its expiry, the registry stops accepting it, and pulls and pushes with it fail with unauthorized. The token stays in the list with an Expired tag until you delete it. Its expiry can't be extended: create a new token, swap the secret, and delete the expired one.

Security best practices​

  • Give every machine, pipeline and cluster its own token, so you can revoke one without touching the others.
  • Use Pull only wherever nothing is pushed: clusters, servers, deploy jobs.
  • Scope tokens to Only specific projects when a consumer needs just one or two.
  • Set an expiry on push tokens and rotate them.
  • Store secrets in a secret manager or your CI's masked variables, never in a repository.
  • Pass secrets with --password-stdin, never as -p on the command line, where they end up in shell history and process lists.

Troubleshooting​

ErrorCause and fix
Create Token is disabled, or Choose a project that is ready, or create one firstA token needs at least one project that is Ready to reach. Create a project first
Choose at least one projectWith Only specific projects, pick at least one
One of the projects doesn't exist any more, reload and try againA chosen project was deleted. Reload and choose again
An account can have up to 50 registry tokens, delete one you no longer use!Delete unused tokens
Expiry must be between 1 and 3650 days, or neverChoose an expiry in that range, or 0 for never
Name must not be empty or Name must not exceed 64 charactersGive the token a label of 1 to 64 characters
You have read-only access to this account, you can not create registry tokens!Your role is Restricted or your API token is read-only
The registry token must be ready to be changed.The token is being created or deleted. Wait a moment
The registry token is busy, try again in a moment!The token is being created or deleted. Retry
unauthorized when logging inThe secret is wrong, the token expired or was deleted, or the username is not your registry username
Lost the secretSecrets can't be recovered. Delete the token and create a new one

Next steps​

Last updated on