Skip to main content
Container images allow you to import prebuilt container images from public sources, private AWS ECR repositories, private GCP Artifact Registry (GAR) repositories, and private Azure Container Registry (ACR) repositories. Container images are used to import prebuilt images, that have already been pushed to either a public registry, a private AWS ECR repository, a private GCP Artifact Registry repository, or a private Azure Container Registry repository.
If you have private prebuilt images in a registry other than AWS ECR, GCP Artifact Registry, or Azure Container Registry, please get in touch!
To learn more about components, see the Components concept page.

Configuring a container image component

Component configuration describes only the source image; there is no user-supplied cloud_connection_id. For private ECR, GAR, and ACR sources, register the repository in Settings → Image repositories → Add image repository and choose its pull identity — see Add an image repository. During a new configuration save or app sync, Nuon looks up the organization’s saved assignment for the exact canonical repository and pins its chosen Cloud Connection ID. Configure only the image URL, coordinates, and tag fields shown in the examples below. If the chosen connection is not verified, the save or sync fails. See how image connections are selected for the full selection and pinning rules, including how removal and deletion affect existing configurations.

Using a Public Image

To use a public image from any container registry, configure the public block.
components/public_image.toml

Using a Private AWS ECR Image

To use an image from a private ECR registry, configure the aws_ecr block.
components/ecr_image.toml
Register arn:aws:ecr:us-west-2:123456789012:repository/acme/api and explicitly choose an AWS Cloud Connection with the ecr preset in the same Nuon organization, account, and region. Configure its role for ECR read access and verify it before saving or syncing. On save or sync, Nuon pins the assignment’s chosen verified connection.

Using a Private GCP GAR Image

To use an image from a private Google Artifact Registry, configure the gcp_gar block.
components/gar_image.toml
Register projects/my-project/locations/us-central1/repositories/my-repo and explicitly choose a GCP Cloud Connection with the gar preset in the same organization, project, and location. Enter my-repo in the dashboard, not my-repo/my-image; all images in my-repo use this assignment. Apply its setup and verify the identity before saving or syncing. On save or sync, Nuon pins the assignment’s chosen verified connection.

Using a Private Azure ACR Image

Nuon exchanges a short-lived OIDC token through Microsoft Entra to authenticate to the registry. In Settings → Image repositories → Add image repository, enter acme/api and choose an existing Azure pull identity or create one inline. You can select an existing principal or add a new one. The underlying Cloud Connection must use the acr preset in the same organization and match the registry. Nuon saves the actual login hostname and exact repository path, such as acmeimages.azurecr.io/acme/api, with the identity you chose.
components/acr_image.toml
The connection authenticates an existing Microsoft Entra application through Nuon’s connection-specific OIDC subject. The saved repository assignment selects that connection; its detail page provides Azure CLI and Terraform instructions for federation and Container Registry Repository Reader with ABAC conditions for the repository. Have the cloud administrator apply the appropriate commands, then verify the identity. Follow the access setup directions.
OIDC setup requires an ABAC-enabled registry. Nuon does not change existing registry permission modes.
Source-registry credentials are used by Nuon’s builds and metadata fetches. They never land in a customer cloud account, and access is shared across all installs of the app template rather than configured per install.

Verifying signed images

Container image components can require the resolved image digest to be signed by a trusted Sigstore keyless identity or Cosign public key. Verification happens before Nuon copies the image, and a failed verification fails the component build. See Verify Container Image Signatures for keyless and key-based configuration, authority matching, and guidance on combining verification with OPA policies.

Deployments

Container image components cannot be deployed directly in a customer install. When an image is released, it will be synced into the customer install and made available to other components via variables. To deploy a Container image component, reference the image from a Helm component or Terraform component:
components/eks_deployment.toml
components/ecs_service.toml
components/eks_job.toml

Image Syncing

When a Container image component is released, Nuon will automatically sync the image into the end customer account. This image is stored in a local registry that is provisioned in the customer account. OCI referrers and legacy Cosign digest tags are copied with the image so signatures, SBOMs, provenance, and other attestations remain available in the destination registry. Nuon image syncing allows you to sync images into accounts, without worrying about cross account permissions, registry authentication or publishing public images. Any Dockerfile in a repo can be built, and synced. The sync process works by creating a 1-time authentication flow that grants the install runner access to pull the image from the org data plane, and copy it into the local registry.

Granting Nuon Access to Pull Images

Your vendor cloud administrator applies source-registry setup in the account or project containing your images. End customers do not need access to that registry, and setup is not repeated for every install. Nuon never applies cloud writes automatically. See who sets up image repository access, Grant access to another repository, and Register image repositories through the API for setup, permissions, and registration details. After verification, fetch component metadata and run a build with an existing private image to check current permissions and exercise manifest and layer downloads.

AWS ECR Access IAM Role

Set up the identity, trust, and repository permissions through the ECR guide: register the repository in Settings → Image repositories, apply the generated setup, and verify the connection. Then save or sync the component with its source image URL, tag, and matching region; Nuon pins the assignment’s chosen verified ecr connection. Tag resolution with update_policy requires ecr:ListImages on the repository. See the full set of aws_ecr fields in the container-image config reference.

GCP GAR Access

Set up the service account, federation, and repository-reader bindings through the GAR guide: register the repository in Settings → Image repositories, apply the generated setup, and verify the connection. Then save or sync the component with its source image URL, tag, project ID, and region; Nuon pins the assignment’s chosen verified gar connection. The assignment covers all images in that GAR repository. See the full set of gcp_gar fields in the container-image config reference.

Azure ACR Access

Set up the Entra application, federation, and repository-conditioned Reader grant through the ACR guide: the registry must already use RBAC Registry + ABAC Repository Permissions, and Nuon does not change an existing registry’s mode. Register the repository in Settings → Image repositories, apply the generated setup, and verify the connection. Then save or sync the component with its source image URL, registry login hostname, and tag; Nuon pins the assignment’s chosen verified acr connection. See the full set of azure_acr fields in the container-image config reference.

Importing Images Outside of Supported Registries

We currently support public container images, private AWS ECR repositories, private GCP Artifact Registry repositories, and private Azure Container Registry repositories. If your registry is supported by AWS ECR’s pull through cache, the easiest way to import the images into Nuon is to setup a pull through cache and configure your container image to use it. This works for Docker Hub, Github Container Registry and Microsoft Azure Container Registry.
If you would like to use a different private container registry, we would love to know more. Please get in touch to tell us more about your use case.