Skip to main content
Each install presents its own scoped pull token to the oci.akua.dev proxy, which validates it and attaches your stored upstream credential from a vault sealed inside Akua to pull the image; one install's token is revoked without affecting the others, and clusters receive images, never your registry secret.
Clusters need credentials to pull private container images. Akua’s registry proxy centralizes this: configure your registry credentials once, and all installs pull private images without storing credentials on clusters. All image pulls through the proxy require authentication. You must configure credentials for any registry 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.
  • Credentials stay in Akua’s secret store: upstream registry passwords and tokens are stored as versioned workspace secrets and never sent to clusters directly.
  • Instant revocation: disable access immediately without rotating credentials everywhere.
  • Audit trail: see which installs pulled which images and when.

​
For marketplace products

When selling products with private images, the proxy is especially valuable:
  • Customers can pull your images without knowing your credentials.
  • You can revoke a customer’s access without affecting others.
  • Your credentials give access to all your repos, but customers only get access to what they purchased.

​
How it works

Akua runs a registry proxy at oci.akua.dev. When clusters pull images through this proxy, Akua validates the request using install-scoped credentials, looks up your workspace’s upstream registry credentials, forwards the request to the upstream registry with your credentials, and streams the response back to the cluster. Your upstream credentials (GitHub PAT, Docker Hub token, and so on) never leave Akua’s infrastructure.

​
Using the proxy in your images

To pull images through Akua’s proxy, prefix your image references with oci.akua.dev/:
The format is: oci.akua.dev/{upstream-registry}/{repository}:{tag}

​
Marketplace products

When building products for the marketplace, reference private images through the proxy in your Package resources or source inputs:
This ensures customers can deploy your product without needing access to your private registry.

​
Generated package installs

When a Package references private images, Akua handles the proxy routing automatically. Configure workspace credentials in Settings → Registries with a PAT that has read:packages scope, and Akua detects image references in Package inputs, image sources, and chart-source values before routing pulls through the proxy at install time.
You can control this behavior per product 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, and so on).
  • Never: do not rewrite any image URLs.

​
Setting up registry credentials

1

Open registry settings

Navigate to Settings → Registries in your workspace.
2

Add a registry

Click Add Registry and enter a friendly name, the registry hostname (for example, docker.io or ghcr.io), and the authentication type.
3

Configure authentication

Standard authentication used by most registries. Enter your registry username and password or access token.Used by: Docker Hub, Harbor, Nexus, JFrog Artifactory.
4

Test and save

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

​
Supported registries

For other OCI-compliant registries (Harbor, JFrog Artifactory, Nexus, and so on), 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 installs in the workspace can access images from configured registries.
  • Different workspaces can have different registry configurations.
  • Credential updates automatically apply to all installs in the workspace.

​
Syncing credentials to existing installs

When you add or update registry credentials, existing installs need to be synced. In Settings → Registries, click Sync All to push credentials to all active installs, or on an install’s detail page click Re-sync Registry Access to update a specific install. New installs receive registry access automatically 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 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 are not affected, but any new pod starts or image pulls fail until valid credentials are configured.

​
Per-install tokens

Each install receives a unique token for authenticating with the registry proxy. Revoking one install’s access does not affect others, and deleting an install automatically revokes its registry token.

​
Security

Your upstream registry credentials are stored as versioned workspace secrets and never sent to clusters directly. Clusters receive install-scoped tokens that only work with Akua’s proxy and cannot be used directly against upstream registries.
Each install receives a unique token. If a cluster is compromised, you can revoke just that install’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.
Akua logs all image pull operations, giving you visibility into which images are being accessed, by which install, and when.

​
Troubleshooting

Common causes: credentials do not have pull access to the repository, the registry URL does not match the image reference, the token has expired, or the image URL is not using the proxy format (oci.akua.dev/...).To resolve: verify your credentials work locally with docker login, check that image references use the proxy format, and update credentials in Akua if they have expired.
If newly added credentials are not working for existing installs, go to the install’s detail page and click Re-sync Registry Access, or use Sync All in Settings → Registries.
Common causes: incorrect username format, token missing required scopes, or OAuth client misconfiguration. Check the registry’s documentation for the correct authentication format and required permissions. For GitHub, ensure your PAT has read:packages scope.
If you hit registry rate limits, ensure your credentials have appropriate permissions. For Docker Hub, authenticated users have higher rate limits than anonymous access.

​
API

Manage registry credentials programmatically.

Registry API

List, create, and delete registry credentials.

Secrets API

Manage the underlying workspace secrets used by registry credentials.

Package format

Reference private images from Package resources.

Security

How Akua stores and rotates credentials.

Installations

How applications are installed.

Workspaces

How workspaces organize your resources.