> ## 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 images

> Connect an image registry, publish a private Package, and let customer workloads pull through Akua

Use this guide when your Package needs a private container image. You connect your registry as an **Upstream**, resolve an image to its Akua path, and publish that path in a Package. Customer workloads pull through Akua; image layers stay in your registry.

Your customer

Their workload
pulls your image

no credential

Akua

Adds your read credential
kept in your Vault

with your credential

You

Your private registry
image layers stay here

This example uses GHCR and a direct Install on a hosted Cluster. It assumes you know how to author a [Package](https://docs.akua.dev/packages.md). Attached clusters, private control planes, and automatic upgrades of existing nodes are outside this guide.

## Prerequisites

* An authenticated [CLI](https://docs.akua.dev/cli.md), your selected Workspace, and permission to publish Packages, manage Upstreams, create Vault secrets, and set the Vault's IAM policy. Creating the Upstream also requires permission to access the secret version.
* A private image `ghcr.io/acme/web:1.2.3` that serves HTTP on port `80`, plus a read-only registry credential for that repository. For GHCR, use a dedicated account's token with `read:packages` and any organization authorization GHCR requires.
* A hosted Cluster with a Ready worker bootstrapped by Akua with the image credential provider. Existing workers are not upgraded automatically.
* `jq` for the shell examples. Keep the read-only credential in a local file `registry-token.txt`, containing only the exact token bytes, with no trailing newline. Don't commit this file.

Replace `acme`, the registry username, and the image tag throughout with your own values. For a self-hosted registry, also replace every `ghcr.io` with its public DNS hostname and optional port. The registry must serve OCI images over HTTPS with a publicly trusted certificate and accept a username and read credential; don't include `https://` in `--host` or image references. For CI, supply `AKUA_API_TOKEN`; interactive CLI setup is covered in the [CLI guide](https://docs.akua.dev/cli.md).

## Store the read credential

Create a dedicated Vault. The Registry service's binding applies to the whole Vault, so don't mix unrelated secrets into it:

```bash theme={null}
akua vaults create --vault-id image-registry --display-name 'Image registry'
jq -Rs '{body: {secret_id: "ghcr-read", payload: .}}' registry-token.txt |
    akua secrets create image-registry --input -
```

The credential travels through stdin, not a command-line argument. Registry responses contain only the secret version's name, never its value. Authorized Vault secret accessors can still read a generic Vault secret; this is not an inject-only Connection.

Read the new Vault's policy and explicitly grant Registry read access:

```bash theme={null}
akua vaults get-iam-policy image-registry --json > registry-policy.json
jq '{
  headers: {"if-match": .data.etag},
  body: {bindings: (.data.bindings + [{
    role: "roles/vault.secretAccessor",
    members: ["service:registry"]
  }])}
}' registry-policy.json |
    akua vaults set-iam-policy image-registry --input -
```

This preserves existing bindings. If the policy changed concurrently, read it again and retry with its new `etag`. Upstream creation never grants itself access or changes this policy.

## Connect and test the Upstream

Create an Upstream for your organization prefix. The `path` is removed from the resolved Akua image's repository segment:

```bash theme={null}
akua registry create-upstream \
    --upstream-id ghcr-acme \
    --host ghcr.io \
    --path acme \
    --username REGISTRY_USERNAME \
    --secret vaults/image-registry/secrets/ghcr-read \
    --test-image ghcr.io/acme/web:1.2.3
akua registry list-upstreams
```

Replace `REGISTRY_USERNAME` with the account that owns the read credential. Creation performs a real test pull by default. It rejects an invalid credential or missing image with the upstream registry's reason, without echoing the credential. `--skip-test` explicitly skips that check; it doesn't prove that later pulls will work.

The secret reference is pinned to its current version on creation. Adding another version to the secret doesn't silently rotate an existing Upstream. Public HTTPS registry DNS hosts are supported, including GHCR, Docker Hub, GitLab, and self-hosted registries. IP literals, private hostnames, and Akua-served hosts are rejected. Don't assume support for provider-specific token renewal.

## Resolve the image

Resolve the full upstream image, then keep the exact `image` value the API returns:

```bash theme={null}
AKUA_IMAGE=$(akua registry resolve-image ghcr-acme \
    --image ghcr.io/acme/web:1.2.3 --json | jq -er '.data.image')
```

The result is digest-pinned, with this shape:

```text theme={null}
pkg.akua.dev/WORKSPACE_ID/images/ghcr-acme/web@sha256:DIGEST
```

`WORKSPACE_ID` is your Workspace, not your customer's. `DIGEST` identifies the resolved image manifest. Use the returned hostname, especially on a preview: don't substitute the production registry hostname into another environment's path.

## Put the path in a native Package

Initialize a Package, then replace its scaffolded program with a Deployment and Service. Run these commands in the same shell so `AKUA_IMAGE` is available:

```bash theme={null}
akua pkg init private-web
cd private-web
cat > package.k <<EOF
import akua.ctx
import k8s.api.apps.v1 as appsv1
import k8s.api.core.v1 as corev1

schema Input:
    namespace: str = "default"
    release_name: str = "private-web"

input: Input = ctx.input()
resources = [
    appsv1.Deployment {
        metadata = {name = input.release_name, namespace = input.namespace}
        spec = {
            replicas = 1
            selector.matchLabels.app = input.release_name
            template = {
                metadata.labels.app = input.release_name
                spec.containers = [{
                    name = "web"
                    image = "$AKUA_IMAGE"
                    ports = [{containerPort = 80}]
                }]
            }
        }
    }
    corev1.Service {
        metadata = {name = input.release_name, namespace = input.namespace}
        spec = {
            selector.app = input.release_name
            ports = [{port = 80, targetPort = 80}]
        }
    }
]
EOF
cat > inputs.example.yaml <<EOF
namespace: default
release_name: private-web
EOF
akua pkg lock
akua pkg check
akua pkg render --inputs inputs.example.yaml
akua pkg publish
```

`namespace` and `release_name` receive the Install's own values. The image is a Package constant, not a customer-editable input. No `imagePullSecrets`, reserved pull-secret input, image rewrite, or registry password belongs in the Package.

`pkg init` creates files without downloading dependencies. `pkg lock` fetches the pinned Kubernetes schemas before the offline `pkg check`; don't skip it on a new machine or in CI.

Publication renders default inputs and checks Akua image paths in standard Pod specs, including init containers and controller templates. Public images and images created indirectly by custom-resource operators are not validated by this check. An unresolvable private image fails publication with `image-unresolvable`; the CLI lists each image's reason and a `resolve-image` command to diagnose it.

Hosted publication is private by default and waits for the version's publication result. Its output includes an OCI reference containing `/packages/PACKAGE_ID/`. Read that Package to find its published version:

```bash theme={null}
akua packages get PACKAGE_ID --json
```

Replace `PACKAGE_ID` with the ID from the publication reference. For a chart instead of a native Package, follow [Push a Helm chart from CI](https://docs.akua.dev/packages.md#push-a-helm-chart-from-ci); use the same resolved image path in its rendered Pod specs.

## Install and let the workload pull

Create a direct Install, using the version shown by `packages get`:

```bash theme={null}
akua installs create \
    --package-id PACKAGE_ID \
    --package-version-pin '{"kind":"pinned","version":"0.1.0"}' \
    --cluster-id CLUSTER_ID
akua operations wait OPERATION_ID --timeout 60
akua installs get INSTALL_ID
```

Replace `PACKAGE_ID`, `CLUSTER_ID`, and `OPERATION_ID` with the Package, target Cluster, and returned Operation IDs. Use the returned Operation's `owner_id` as `INSTALL_ID`; its `response` can be `null`, even after success. Replace `0.1.0` if you changed the scaffold's version. Repeat the wait while `done` is `false`; require `state: SUCCEEDED`, then check the Install's readiness. This example creates an internal Service, not a public endpoint.

For a customer purchase, a [Product](https://docs.akua.dev/products.md) and [Offer](https://docs.akua.dev/marketplace/offers.md) use the same Package version. Customers don't need your registry credential or permission to download the private Package archive.

Akua grants the Install access to its rendered private-image repositories before applying its workloads. The node's kubelet credential provider supplies the Pod's short-lived ServiceAccount token to Akua. Pulls must match the hosted Cluster, Install namespace, and repositories in your Workspace authorized for that Install. Another namespace or Cluster doesn't inherit the grant. Launch grants authorize repositories, not individual digests; updates retain the Install's previously granted repositories until deletion.

Neither your credential nor a stored Install pull token is placed in a customer Kubernetes Secret. Akua streams authorized manifests and blobs from the Upstream instead of redirecting the customer to an authenticated upstream URL.

## Revoke access and clean up

Delete the Install and wait for deletion to finish:

```bash theme={null}
akua installs get INSTALL_ID --json > install.json
akua installs delete INSTALL_ID \
    --if-match "$(jq -er '.data.etag' install.json)"
akua operations wait DELETE_OPERATION_ID --timeout 60
```

Replace `DELETE_OPERATION_ID` with the deletion Operation ID. Repeat the wait until it is done and successful. Install deletion revokes its image grant before terminal completion, including repositories retained across updates. Revocation denies new proxy requests; it doesn't stop running Pods, undo in-flight bytes, or erase images already downloaded to a node.

To stop every Install using this Upstream, delete the Upstream:

```bash theme={null}
akua registry delete-upstream ghcr-acme
```

Deleting the Upstream leaves its Vault secret and owner-managed IAM binding intact. If this dedicated Vault is no longer used, remove the binding with `vaults set-iam-policy` using a freshly read policy and `etag`, then delete the secret:

```bash theme={null}
akua secrets delete image-registry ghcr-read
```

To rotate credentials without breaking old versions, add a secret version, create a new Upstream ID referencing it, resolve the image again, and publish and install a new Package version. Delete the old Upstream only after migrating its consumers. Disabling the pinned secret version or removing Registry's Vault access also blocks new pulls.

## Troubleshoot a pull

* **Registry cannot read the secret:** check your own `vault.versions.access` permission and the explicit `service:registry` binding. The referenced version must be enabled.
* **Test or resolution fails:** run `akua registry test-upstream ghcr-acme`. Check the repository prefix, tag, token permissions, and provider's reported reason.
* **Publication fails:** use the per-image command printed by `akua pkg publish`. Keep your Workspace and stage registry hostname in the image path.
* **Pod cannot pull:** inspect the Install's status and pull error. Check its namespace and Cluster and confirm that the worker was bootstrapped with the credential provider. A Package source download credential is not an image-pull credential.

## Related topics

* [Packages](https://docs.akua.dev/packages.md)
* [Package format](https://docs.akua.dev/akua/package-format.md)
* [Install lifecycle](https://docs.akua.dev/installs/lifecycle.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.