Skip to main content
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. This example uses GHCR and a direct Install on a hosted Cluster. It assumes you know how to author a Package. Attached clusters, private control planes, and automatic upgrades of existing nodes are outside this guide.

Prerequisites

  • An authenticated CLI, 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.

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:
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:
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:
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:
The result is digest-pinned, with this shape:
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:
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:
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; 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:
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 and Offer 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:
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:
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:
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.