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.3that serves HTTP on port80, plus a read-only registry credential for that repository. For GHCR, use a dedicated account’s token withread:packagesand 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.
jqfor the shell examples. Keep the read-only credential in a local fileregistry-token.txt, containing only the exact token bytes, with no trailing newline. Don’t commit this file.
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:etag. Upstream creation never grants itself access or changes this policy.
Connect and test the Upstream
Create an Upstream for your organization prefix. Thepath is removed from the resolved Akua image’s repository segment:
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 exactimage value the API returns:
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 soAKUA_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:
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 bypackages get:
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: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:
vaults set-iam-policy using a freshly read policy and etag, then delete the secret:
Troubleshoot a pull
- Registry cannot read the secret: check your own
vault.versions.accesspermission and the explicitservice:registrybinding. 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.