Skip to main content

Documentation Index

Fetch the complete documentation index at: https://akua-1dce587a.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Clusters need credentials to pull private container images. Akua’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 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 deployments 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/: 
# Original image reference
image: ghcr.io/your-org/your-app:v1.0.0

# Through Akua proxy
image: oci.akua.dev/ghcr.io/your-org/your-app:v1.0.0
The format is: oci.akua.dev/{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: 
image:
  repository: oci.akua.dev/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. 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 your Helm values and rewrites them to use 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

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, 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 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.

​
Syncing credentials to existing deployments

When you add or update registry credentials, existing deployments need to be synced. In Settings → Registries, click Sync All to push credentials to all active deployments, or on a deployment’s detail page click Re-sync Registry Access to update a specific deployment. New deployments 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 deployment receives a unique token for authenticating with the registry proxy. Revoking one deployment’s access does not affect others, and deleting a deployment 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 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.
Akua logs all image pull operations, giving you visibility into which images are being accessed, by which deployment, 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 deployments, 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, 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.

GitHub integration

Connect GitHub to pull from GHCR automatically.

Security

How Akua stores and rotates credentials.

Deployments

How applications are installed.

Workspaces

How workspaces organize your resources.