> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Private container registries
> Configure authentication for private container registries to install applications with private images
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.
```mermaid theme={null}
flowchart TB
subgraph cluster["Your Cluster"]
pod["Pod pulls image\nwith install token"]
end
subgraph proxy["oci.akua.dev"]
p["Validates token\nAdds workspace creds"]
end
subgraph upstream["Upstream Registry"]
registry["ghcr.io / docker.io\nECR / etc."]
end
pod --> p --> registry
```
## Using the proxy in your images
To pull images through Akua's proxy, prefix your image references with `oci.akua.dev/`:
```yaml theme={null}
# 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 private images through the proxy in your Package resources or source inputs:
```yaml theme={null}
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.
### 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
Navigate to **Settings → Registries** in your workspace.
Click **Add Registry** and enter a friendly name, the registry hostname (for example, `docker.io` or `ghcr.io`), and the authentication type.
Standard authentication used by most registries. Enter your registry username and password or access token.
Used by: Docker Hub, Harbor, Nexus, JFrog Artifactory.
Token-based authentication for registries that use personal access tokens. Enter your PAT with read permissions.
Used by: GitHub Container Registry (ghcr.io), GitLab Container Registry.
OAuth2 client credentials for enterprise registries. Enter your client ID, client secret, and token URL.
Used by: some enterprise registry configurations.
Akua validates your credentials before saving. If validation fails, check that your credentials have pull access to the registry.
## Supported registries
| Registry | URL | Auth type | Notes |
| ----------------------------- | ------------------------------------------ | ----------------- | -------------------------------------------------------- |
| **Docker Hub** | `docker.io` | Username/password | Use access token instead of password for better security |
| **GitHub Container Registry** | `ghcr.io` | Token | Use a PAT with `read:packages` scope |
| **Amazon ECR** | `.dkr.ecr..amazonaws.com` | AWS credentials | Access Key ID, Secret Access Key, and region |
| **Google Container Registry** | `gcr.io` | Service account | Username `_json_key`, password is service account JSON |
| **Azure Container Registry** | `.azurecr.io` | Username/password | Use service principal or admin credentials |
| **GitLab Container Registry** | `registry.gitlab.com` | Token | Use a PAT or deploy token with `read_registry` scope |
| **Quay.io** | `quay.io` | Token | Use 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 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.
List, create, and delete registry credentials.
Manage the underlying workspace secrets used by registry credentials.
## Related topics
Reference private images from Package resources.
How Akua stores and rotates credentials.
How applications are installed.
How workspaces organize your resources.