Authentication

Cloudfleet Container Registry (CFCR) supports three authentication methods designed 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 functions as a Docker credential helper, providing seamless authentication without storing long-lived credentials. This is the recommended method for developers pushing and pulling images from their local machines.

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 generated from your authenticated session, so no long-lived credentials are stored in Docker configuration files.

Setup

1. Install the Cloudfleet CLI

   Follow the instructions in Install Cloudfleet CLI.

2. Authenticate the CLI

   Add an authentication profile for your organization:

   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 via single sign-on.

3. Configure Docker

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

   cloudfleet auth configure-docker
   

   This updates your Docker configuration file (~/.docker/config.json) with entries like:

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

4. Verify the configuration

   Test authentication by logging in:

   docker login YOUR_ORG_ID.europe.registry.cloudfleet.dev
   

   Docker calls the credential helper automatically. You should see:

   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 using the --profile flag:

cloudfleet --profile work auth configure-docker

API tokens

API tokens provide programmatic access for CI/CD pipelines, scripts, and automated workflows. Tokens consist of an ID and secret that you use as 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 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 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 using that token.

CFKE cluster authentication

CFKE clusters authenticate to CFCR automatically. No configuration required. Reference images from your registry in pod specifications and they pull successfully.

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

No imagePullSecrets needed. No service accounts to configure.

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

The CLI automatically uses these variables when no profile is specified. This approach works well 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

Next steps

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