Authentication

Cloudfleet Container Registry (CFCR) supports three authentication methods for different use cases: the Docker credential helper for interactive use, API tokens for CI/CD automation, and automatic authentication for CFKE clusters.

Docker credential helper

The Cloudfleet CLI works as a Docker credential helper and authenticates without storing long-lived credentials. This is the recommended method to push and pull images from your local machine.

How it works

Docker credential helpers are external programs that Docker calls to retrieve authentication credentials. When you run docker push or docker pull, Docker:

1. Checks the Docker configuration for a credential helper
2. Calls the helper program with the registry hostname
3. Receives credentials (username and password/token)
4. Uses those credentials to authenticate the request

The Cloudfleet CLI implements this protocol. It returns short-lived tokens from your authenticated session, so Docker configuration files contain no long-lived credentials.

Setup

1. Install the Cloudfleet CLI

   Follow the instructions in Install Cloudfleet CLI.

2. Authenticate the CLI

   Add an authentication profile for your organization:

   bash Copy

   cloudfleet auth add-profile user default YOUR_ORGANIZATION_ID

   Replace YOUR_ORGANIZATION_ID with your organization’s UUID. A browser window opens to complete authentication through single sign-on.

3. Configure Docker

   Register the Cloudfleet CLI as a credential helper for your registry:

   bash Copy

   cloudfleet auth configure-docker

   The command adds entries like the following to your Docker configuration file (~/.docker/config.json):

   json Copy

   {
     "credHelpers": {
       "12345678-6651-4e5d-9c04-079f6532989b.europe.registry.cloudfleet.dev": "cloudfleet"
     }
   }

4. Verify the configuration

   Test authentication by logging in:

   bash Copy

   docker login YOUR_ORG_ID.europe.registry.cloudfleet.dev

   Docker calls the credential helper automatically. You should see:

   Copy

   Login Succeeded

Using multiple profiles

If you work with multiple organizations, create a profile for each:

cloudfleet auth add-profile user work 12345678-6651-4e5d-9c04-079f6532989b
cloudfleet auth add-profile user personal 550e8400-e29b-41d4-a716-446655440000

Switch between profiles with the --profile flag:

cloudfleet --profile work auth configure-docker

API tokens

API tokens provide programmatic access for CI/CD pipelines, scripts, and automated workflows. A token has an ID and a secret, which you use as the Docker username and password.

When to use API tokens

• CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, CircleCI)
• Build servers and automation systems
• Headless environments without browser access
• Service accounts for automated image management

Creating an API token

cloudfleet tokens create --name github-actions-registry --role Administrator

Token ID: 2iKo4Asy51EUx2gpJFW76t
Secret: cf_secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Using API tokens with Docker

Use the token ID as the username and the secret as the password:

docker login YOUR_ORG_ID.europe.registry.cloudfleet.dev \
  --username YOUR_TOKEN_ID \
  --password YOUR_TOKEN_SECRET

For non-interactive authentication (recommended for CI/CD):

echo "$TOKEN_SECRET" | docker login YOUR_ORG_ID.europe.registry.cloudfleet.dev \
  --username "$TOKEN_ID" \
  --password-stdin

Token security best practices

• Use descriptive names: Name tokens by their purpose (for example, prod-deploy-pipeline)
• Limit permissions: Use the User role for pipelines that only pull images
• Rotate regularly: Regenerate token secrets periodically
• Store securely: Use your CI/CD platform’s secret management features
• Create separate tokens: Use different tokens for different pipelines or environments

Regenerating token secrets

If a token secret is compromised, regenerate it immediately:

cloudfleet tokens regenerate TOKEN_ID

The old secret becomes invalid immediately. Update all systems that use the token.

CFKE cluster authentication

CFKE clusters authenticate to CFCR automatically, with no configuration. Reference images from your registry in Pod specifications, and the cluster pulls them.

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: my-app
    image: YOUR_ORG_ID.europe.registry.cloudfleet.dev/my-app:v1.0.0

You do not need imagePullSecrets or service account configuration.

CFKE clusters have pull-only access. To push images, use the Docker credential helper or API tokens.

CFKE clusters can only pull from their own organization’s registry. To use images from a different organization, push them to your registry first, or create an image pull secret with credentials for the external registry.

Environment variables

For scripts and automation outside CI/CD platforms, use environment variables:

export CLOUDFLEET_ORGANIZATION_ID=12345678-6651-4e5d-9c04-079f6532989b
export CLOUDFLEET_ACCESS_TOKEN_ID=your-token-id
export CLOUDFLEET_ACCESS_TOKEN_SECRET=your-token-secret

Without a profile, the CLI uses these variables automatically. Use this approach for:

• Local scripts that interact with the registry
• Development environments with ephemeral credentials
• Containers that need registry access

Comparison of authentication methods

*Requires Administrator role

Troubleshooting push errors

To push to the Cloudfleet Container Registry, your organization needs a valid billing address and payment method. Without them, the registry denies pushes with a 403 error, even when authentication succeeds.

Add the billing information in the Cloudfleet Console under Billing. After you save, it can take a few minutes before the registry accepts pushes. If pushes still fail after that, contact support.

Next steps

• Set up CI/CD integration with API tokens
• Learn about access control and roles
• Start managing artifacts