Accessing CleanStart images requires authentication to registry.cleanstart.com. This guide covers all authentication methods from local development to production Kubernetes clusters.

Prerequisites

Before authenticating to the CleanStart registry, ensure you have several requirements in place. You need CLI tools such as Docker or Podman installed and running on your local machine or build server. You need API credentials including your username and API key obtained from your CleanStart account dashboard. You need network access with outbound HTTPS connectivity to registry.cleanstart.com on port 443 from your location. Finally, you need an appropriate environment such as Linux, macOS, or Windows with Docker Desktop to run the authentication commands.

Authentication Methods

CleanStart registry supports five authentication approaches, each optimized for different use cases and deployment scenarios. Docker Login enables interactive authentication for local development work where a user is actively building and testing containers. API Key Authentication provides programmatic access via HTTP headers for scripts and automation that don't require interactive input. Kubernetes ImagePullSecrets work for container deployments in Kubernetes clusters, allowing pods to authenticate automatically. Service Account Authentication provides identity-based access in cloud environments through cloud provider credentials. Token-Based Authentication enables short-lived credentials for CI/CD pipelines where you need temporary access for a single build job.

Getting Your API Key

Create a new API key by logging into dashboard.cleanstart.com and navigating to Settings and API Keys. Click Generate New Key and provide a descriptive name such as "docker-cli" for local development or "production-deployment" for production systems. Select the appropriate scope either Pull for read-only access or Pull + Push for read-write access. Set the expiration to 90 days (recommended for production) or another appropriate interval. Click Create and copy the key immediately, as it will not be shown again after you close the dialog.

Store your API key securely, treating it like a password that grants access to all your container images. Never commit it to version control or log it in output where it could be captured.

Docker CLI Authentication

The simplest method for local development involves interactive login. Log into the registry and provide your credentials:

# Log in to registrydocker login registry.cleanstart.com # Prompt for credentialsUsername: your-usernamePassword: (paste your API key here)

The credentials are saved in ~/.docker/config.json.

Non-Interactive Login (Scripting)

For scripts and automation, pipe credentials to docker login:

# Option 1: Via echoecho "$REGISTRY_PASSWORD" | docker login registry.cleanstart.com \  -u "$REGISTRY_USERNAME" \  --password-stdin # Option 2: Via environment variable (not recommended for secrets)export DOCKER_CONTENT_TRUST_SERVER_PASSPHRASE="your-api-key"docker login registry.cleanstart.com -u "your-username"

Verify Authentication

# Pull a public imagedocker pull registry.cleanstart.com/library/base:latest # List tagsdocker images registry.cleanstart.com/library/base

API Key Authentication (HTTP Header)

For programmatic access without storing credentials on disk, use HTTP header authentication.

Curl Example

Create Base64-encoded credentials and use them for API requests to pull image manifest, pull image layer, and perform other registry operations.

Docker CLI with Explicit Header

Create a credentials file with Base64-encoded auth and use it with Docker.

Skopeo Tool

Skopeo enables advanced registry operations with explicit authentication including copying images between registries, inspecting images without pulling, and other registry operations.

Kubernetes ImagePullSecrets

For container deployments in Kubernetes, create a secret containing registry credentials.

Create ImagePullSecret

Create secret from Docker credentials, verify secret created, and reference it in pod specs. The secret contains Base64-encoded credentials for authentication.

Reference Secret in Pod Spec

Specify the imagePullSecrets in the pod spec to authenticate when pulling images.

Reference Secret in ServiceAccount

For cluster-wide access, attach the secret to a ServiceAccount so all pods using that account automatically authenticate.

All pods in that namespace using the default ServiceAccount will automatically use the credentials.

Reference in Deployment

Specify imagePullSecrets in Deployment specs for automatic image authentication.

Using kubectl patch

If the secret already exists, add it to a running ServiceAccount.

Service Account Authentication

For workloads running on GCP, Azure, or AWS, use Workload Identity instead of static API keys.

Google Cloud: Workload Identity

Recommended for deployments on Google Kubernetes Engine (GKE).

Create Google Service Account, grant artifact registry access, create Kubernetes ServiceAccount, bind to Google Service Account, and reference in Pod.

Azure: Managed Identity

For Azure Kubernetes Service (AKS) deployments.

Create Managed Identity, configure RBAC to grant access, and reference in Pod.

AWS: IAM Roles for Service Accounts (IRSA)

For Amazon EKS deployments.

Create IAM role with trust policy, attach policy for ECR access, and reference in Pod.

CI/CD Integration

Authenticate to the registry in continuous integration pipelines.

GitHub Actions

Store API key as a GitHub Secret, use the secret in workflow with docker/login-action, and build/push with docker/build-push-action.

GitLab CI

Add credentials to CI/CD variables and use in .gitlab-ci.yml by logging in before building.

Jenkins

Add credentials to Jenkins and reference them in your pipeline by logging in and building/pushing.

CircleCI

Add API key as environment variable and use in configuration by logging in and building/pushing.

Credential Rotation

Rotate API keys regularly to minimize risk if credentials are exposed.

Rotation Workflow

Generate a new API key in the dashboard. Deploy with the new key by updating secrets in Kubernetes or CI/CD. Test that image pull works with new credentials. Revoke the old API key. Review audit logs for any failed attempts.

Kubernetes Secret Rotation

Create new secret with updated credentials, update ServiceAccount to use new secret, and delete old secret after verifying.

Automated Rotation

For production, use secret management tools like ArgoCD Sealed Secrets or HashiCorp Vault with automatic rotation on schedule.

Air-Gapped and Mirror Setups

In offline or restricted environments, mirror registry images locally.

Sync Images to Local Registry

Authenticate to both registries, pull from CleanStart, tag for local registry, and push to local registry.

Bulk Sync with Skopeo

For many images, use Skopeo for batch operations by syncing entire repositories or syncing by tag pattern.

Configure Containerd for Mirror

For Kubernetes clusters using containerd, configure registry mirrors and then restart containerd.

Troubleshooting Authentication

"Unauthorized: authentication required"

The registry rejected your credentials. Verify your API key is correct by re-copying it from the dashboard and testing with curl.

Check Docker login by clearing local credentials and re-logging in.

"Error response from daemon: Get ... x509: certificate signed by unknown authority"

TLS certificate verification failed. If behind a corporate proxy with MITM inspection, import the CA certificate.

"Get https://registry.cleanstart.com/v2/: dial tcp: lookup registry.cleanstart.com: no such host"

DNS resolution failed. Verify DNS resolves correctly and test connectivity.

If blocked by firewall, configure Docker daemon to use an HTTP proxy.

"Error: No such image"

Image doesn't exist or is in a different registry. Verify the image exists using skopeo or curl.

"Kubernetes pod stuck in ImagePullBackOff"

Pod cannot pull image due to authentication failure. Check that the ImagePullSecret exists and is referenced.

Run diagnostics pod to test registry reachability.

Rate Limiting

CleanStart registry enforces rate limits to prevent abuse.

Default Limits: The limits are 1,000 pulls per hour per API key, 100 pulls per minute per IP address, and 10 concurrent pulls per API key.

When rate limited, the registry returns HTTP 429 (Too Many Requests).

Increase Limits: Contact support@cleanstart.com for higher limits, provide your use case and expected pull volume, and note that premium accounts receive elevated limits.

Avoid Rate Limiting: Cache images locally instead of repeated pulls, use Docker BuildKit layer caching, implement exponential backoff for retries, and tag images with fixed versions instead of latest.

Security Best Practices

Never commit API keys to git repositories or configuration files. Use short-lived tokens in CI/CD with 10 to 60 minute expiration windows. Rotate credentials at least quarterly and monitor audit logs for unauthorized access attempts. Use read-only API keys for deployments that only pull images, and enable RBAC in Kubernetes to restrict secret access. Always scan images for vulnerabilities before deploying, and sign images with cosign to prevent tampering.