Using Custom ACR with Runtime¶

This guide explains how to mirror the Trust3 runtime images into your own Azure Container Registry (ACR), so that your Kubernetes workloads pull from your registry instead of the Trust3 Docker proxy.

Use it when your security policy requires runtime images to be served from a private registry.

Prerequisites¶

Requirement	Notes
Trust3 portal access	Needed to create the API key used for mirroring
Azure ACR	Registry created; you can push and pull images
Tools	`docker`, `curl`, `jq`, and Azure CLI (`az`) for ACR auth
ACR push access	`AcrPush` (or equivalent) for the identity used to mirror images

Confirm with your platform team which auth mode is standard for push (mirroring).

Create a TRUST3 API key¶

Log in to the Trust3 AI portal, go to Settings in the left navigation, then select API Keys.
Select Generate scoped key, give it a meaningful name, and choose the scope Runtime (manage).
Copy the key value (shown once; starts with pc-) and save it. It won't be displayed again.

The script uses this key for two things: looking up the release to mirror, and pulling images from the Trust3 proxy. You will set it as TRUST3_API_KEY in the steps below. Store it securely.

Mirror images to your ACR¶

Trust3 provides a bash script that copies the standard runtime image set from the Trust3 Docker proxy into your ACR.

Download the script¶

Download the mirror script and the environment template from Trust3 public artifacts.

File	URL
Mirror script	`https://trust3ai-artifacts.s3.amazonaws.com/runtime/mirror-images/mirror-images-to-acr.sh`
Environment template	`https://trust3ai-artifacts.s3.amazonaws.com/runtime/mirror-images/.env.example`

Bash
mkdir -p mirror-images && cd mirror-images

curl -fsSLO https://trust3ai-artifacts.s3.amazonaws.com/runtime/mirror-images/mirror-images-to-acr.sh

curl -fsSLO https://trust3ai-artifacts.s3.amazonaws.com/runtime/mirror-images/.env.example

chmod +x mirror-images-to-acr.sh

What the script does¶

Resolves the release to mirror: the latest release by default, or the release you pin with RELEASE_VERSION
Downloads that release's images.txt into the current directory
Pulls from the Trust3 proxy: api.na.trust3ai.com (authenticated with your TRUST3_API_KEY)
Pushes to your ACR (TARGET_REGISTRY)
Runs up to 4 parallel pull/tag/push jobs by default (MIRROR_JOBS=4)

The source registry is fixed. Target ACR settings are in .env.

Configuration (`.env`)¶

Copy the example file and fill in your values:

Bash
1	`cp .env.example .env`

Required variables:

Variable	Description
`TRUST3_API_KEY`	Your `runtime:manage` API key (`pc-...`) — see Create a runtime:manage API key
`TARGET_REGISTRY`	ACR login server, e.g. `myregistry.azurecr.io`

Target ACR authentication — set ACR_AUTH_MODE and the matching credentials:

Mode	When to use	Configuration
`az-login`	Local use after interactive `az login`	`ACR_AUTH_MODE=az-login`
`az-sp`	CI or automation with a service principal	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`
`token`	After `az login`; uses short-lived ACR token	`ACR_AUTH_MODE=token`
`docker`	Generic registry username/password (e.g. SP as docker user)	`ACR_USERNAME`, `ACR_PASSWORD`
`acr-admin`	ACR admin account enabled (often disabled in production)	`ACR_USERNAME`, `ACR_PASSWORD`
`auto`	Default — tries docker creds → az-sp → `az login`	No extra vars if one method already works

Optional variables:

Variable	Default	Description
`RELEASE_VERSION`	Latest release	Pin the release to mirror, e.g. `9.2.37.2`. Leave unset to mirror the latest release
`IMAGES_FILE`	Downloaded per release	Use your own image list file instead of the release manifest
`ACR_NAME`	Derived from `TARGET_REGISTRY`	ACR resource name for `az` CLI
`MIRROR_JOBS`	`4`	Parallel workers; use `1` for serial
`SKIP_EXISTING`	`false`	Skip push if tag already exists in ACR
`DRY_RUN`	`false`	Print actions only

Tip

Quote AZURE_CLIENT_SECRET in .env if it contains special characters (~, $, etc.).

Shell environment variables override .env. The script loads ./.env from the current directory, or .env next to the script if you run it from another path.

Running the script¶

Bash
# Preview actions
./mirror-images-to-acr.sh --dry-run

# Mirror all images
./mirror-images-to-acr.sh

# Skip images already present in ACR
./mirror-images-to-acr.sh --skip-existing

The script logs the release it resolved and the images it will mirror before pushing anything.

Verify images in ACR¶

Bash
az acr repository list --name <acr-name> -o table
az acr repository show-tags --name <acr-name> --repository runtime-agent -o table

Mirrored images¶

The exact image set for a release — each entry as repository:tag — is published as a version-specific manifest (images.txt), so the list is never maintained by hand.

Manifest for the current release: 9.2.37.2 — view images.txt

The manifest for any release is also linked from the Manifest column of the Release Notes.

images.txt format — one image per line, comments start with #:

Text Only
1 2 3 4	`# repository:tag (no registry host) runtime-agent:<image-tag> privacera_diagnostic_client:<image-tag> trust3-ai-assets-collector:<image-tag>`

Upgrades¶

Image tags are release-specific, so mirror again before upgrading your runtime or applications.

Bash
1	`./mirror-images-to-acr.sh --skip-existing`

Use --skip-existing so images already present in your ACR from a prior release are not re-pulled and re-pushed.

The script mirrors the latest release unless RELEASE_VERSION is set in .env. If you pinned a version earlier, update or remove that value before you re-run the script — otherwise you will mirror the old release again.

Troubleshooting¶

Symptom	Likely cause	Action
Script fails during release lookup	Invalid `TRUST3_API_KEY`, or `jq` / `curl` missing	Re-mint your `runtime:manage` API key from the portal (API Keys) and confirm `jq` and `curl` are installed
Mirror script fails on pull	`TRUST3_API_KEY` lacks access to the Docker registry routes	Re-mint / re-copy your `runtime:manage` API key from the portal (API Keys)
Mirror script fails on push	ACR auth	Try `ACR_AUTH_MODE=az-login` after `az login`, or configure `az-sp` / `docker` mode
Image list download fails	`RELEASE_VERSION` points to a release that has no published manifest	Check the version against the Manifest column of the Release Notes, or unset `RELEASE_VERSION` to use the latest release

Quick reference checklist¶

Mint a runtime:manage API key in the Trust3 portal
Download mirror-images-to-acr.sh and .env.example
Fill in .env (TRUST3_API_KEY, TARGET_REGISTRY, ACR auth); set RELEASE_VERSION only to pin a release
Preview with ./mirror-images-to-acr.sh --dry-run
Mirror the images and verify them in ACR