Skip to main content
Clusters need credentials to pull private container images. CNAP’s registry proxy centralizes this—configure your registry credentials once, and all deployments pull private images without storing credentials on clusters. All image pulls through the proxy require authentication; you must configure credentials for any registry that you want to proxy, including public registries like Docker Hub.

​
Why Use the Registry Proxy?

  • Centralized credentials - Add your GitHub PAT or registry password once, use it across all clusters
  • Your credentials stay safe - Upstream registry passwords and tokens never leave CNAP
  • Instant revocation - Disable access immediately without rotating credentials everywhere
  • Audit trail - See which deployments pulled which images and when

​
For Marketplace Products

When selling products with private images, the proxy is especially valuable:
  • Keep credentials private - Customers can pull your images without knowing your PAT
  • Per-customer control - Revoke a customer’s access without affecting others
  • No credential sharing - Your GitHub PAT gives access to all your repos, but customers only get access to what they purchased

​
How It Works

CNAP runs a registry proxy at oci.cnap.tech. When clusters pull images through this proxy, CNAP:
  1. Validates the request using install-scoped credentials
  2. Looks up your workspace’s upstream registry credentials
  3. Forwards the request to the upstream registry with your credentials
  4. Streams the response back to the cluster
Your upstream credentials (GitHub PAT, Docker Hub token, etc.) never leave CNAP’s infrastructure.

​
Using the Proxy in Your Images

To pull images through CNAP’s proxy, prefix your image references with oci.cnap.tech/: 
# Original image reference
image: ghcr.io/your-org/your-app:v1.0.0

# Through CNAP proxy
image: oci.cnap.tech/ghcr.io/your-org/your-app:v1.0.0
The format is: oci.cnap.tech/{upstream-registry}/{repository}:{tag}

​
Marketplace Products

When building products for the marketplace, reference your private images through the proxy in your Helm chart’s values.yaml: 
# values.yaml
image:
  repository: oci.cnap.tech/ghcr.io/your-org/your-app
  tag: v1.0.0
This ensures customers can deploy your product without needing access to your private registry.

​
GitHub Repository Deployments

When deploying from GitHub repositories, your workflow pushes to GHCR normally—CNAP handles the proxy routing automatically. Configure workspace credentials in Settings → Registries with a PAT that has read:packages scope, and CNAP will detect image references in your Helm values and rewrite them to use the proxy at install time.

GitHub Actions Workflows

See how to set up automated builds that push to GHCR and notify CNAP
You can control this behavior per-template with the Registry Proxy Mode setting:
  • Auto (default) - Only proxy images from registries with configured credentials
  • Always - Proxy all images from known registries (ghcr.io, docker.io, etc.)
  • Never - Don’t rewrite any image URLs

​
Setting Up Registry Credentials

1

Open Registry Settings

Navigate to Settings → Registries in your workspace. This is where you manage all registry credentials for the workspace.
2

Add a Registry

Click Add Registry and enter:
  • Name - A friendly name to identify this registry (e.g., “Production Docker Hub”)
  • Registry URL - The registry hostname (e.g., docker.io, ghcr.io, 123456789.dkr.ecr.us-east-1.amazonaws.com)
  • Authentication type - Choose based on your registry’s requirements
3

Configure Authentication

Enter your credentials based on the authentication type:
Standard authentication used by most registries:
  • Username - Your registry username
  • Password - Your registry password or access token
Used by: Docker Hub, Harbor, Nexus, JFrog Artifactory
4

Test and Save

CNAP validates your credentials before saving. If validation fails, check that your credentials have pull access to the registry.

​
Supported Registries

CNAP has built-in support for popular registries:
RegistryURLAuth TypeNotes
Docker Hubdocker.ioUsername/PasswordUse access token instead of password for better security
GitHub Container Registryghcr.ioTokenUse a PAT with read:packages scope
Amazon ECR<account>.dkr.ecr.<region>.amazonaws.comAWS CredentialsAccess Key ID, Secret Access Key, and Region
Google Container Registrygcr.ioService AccountUsername _json_key, password is service account JSON
Azure Container Registry<name>.azurecr.ioUsername/PasswordUse service principal or admin credentials
GitLab Container Registryregistry.gitlab.comTokenUse a PAT or deploy token with read_registry scope
Quay.ioquay.ioTokenUse robot accounts for automation
For other OCI-compliant registries (Harbor, JFrog Artifactory, Nexus, etc.), use the Custom Registry option with basic authentication.
For production use, create dedicated service accounts or robot accounts with read-only access rather than using personal credentials.

​
Managing Access

​
Workspace-Level Credentials

Registry credentials are configured at the workspace level:
  • All deployments in the workspace can access images from configured registries
  • Different workspaces can have different registry configurations
  • Credential updates automatically apply to all deployments in the workspace
This lets you separate production and development registries using different workspaces, or share credentials across all products in a workspace.

​
Syncing Credentials to Existing Deployments

When you add or update registry credentials, existing deployments need to be synced to use them. You can:
  • Sync all deployments - In Settings → Registries, click “Sync All” to push credentials to all active deployments
  • Sync individual deployments - On a deployment’s detail page, click “Re-sync Registry Access” to update that specific deployment
New deployments automatically receive registry access during installation.

​
Revoking Access

To revoke access to private images:
  1. Disable a credential - Toggle the credential to disabled in Settings → Registries. This immediately invalidates all install tokens using that credential. Pods will fail to pull images until the credential is re-enabled.
  2. Delete a credential - Permanently removes the credential. Existing install tokens become invalid immediately.
Disabling or deleting credentials takes effect immediately. Running pods won’t be affected, but any new pod starts or image pulls will fail until valid credentials are configured.

​
Per-Install Tokens

Each deployment (install) receives a unique token for authenticating with the registry proxy. This means:
  • Revoking one deployment’s access doesn’t affect others
  • You can track which deployment is pulling which images
  • Deleting a deployment automatically revokes its registry token

​
Security

CNAP’s registry proxy provides several security advantages over distributing credentials directly:
Your upstream registry credentials (GitHub PAT, Docker Hub token, etc.) are stored in CNAP and never sent to clusters. Clusters receive install-scoped tokens that only work with CNAP’s proxy—they can’t be used directly against upstream registries.
Each deployment receives a unique token. If a cluster is compromised, you can revoke just that deployment’s token without affecting others.
Disable a workspace credential to immediately block all image pulls. No need to rotate tokens across multiple clusters or wait for caches to expire.
Only workspace members can view or modify registry configurations. Credentials are never displayed after saving—only the registry name and URL are visible.
CNAP logs all image pull operations, giving you visibility into which images are being accessed, by which deployment, and when.

​
Troubleshooting

Common causes:
  • Credentials don’t have pull access to the repository
  • Registry URL doesn’t match the image reference in your manifest
  • Token or password has expired
  • Image URL not using the proxy format (oci.cnap.tech/...)
Solution:
  1. Verify your credentials work by testing them locally with docker login
  2. Check that your image references use the proxy format: oci.cnap.tech/{upstream}/{repo}:{tag}
  3. Update credentials in CNAP if they’ve expired
Symptoms: Newly added credentials aren’t working for existing deployments.Solution: Existing deployments need to be synced after adding credentials. Go to the deployment’s detail page and click “Re-sync Registry Access”, or use “Sync All” in Settings → Registries.
Common causes:
  • Incorrect username format (some registries require specific formats)
  • Token missing required scopes
  • OAuth client misconfiguration
Solution: Check the registry’s documentation for the correct authentication format and required permissions. For GitHub, ensure your PAT has read:packages scope.
Common causes:
  • Registry-specific rate limits on your credentials
  • Docker Hub rate limits for authenticated users
Solution: Ensure your credentials have appropriate permissions and haven’t exceeded rate limits. For Docker Hub, authenticated users have higher rate limits than anonymous access. If you’re hitting limits, consider using a different registry or upgrading your account tier.