Using Custom ACR with Runtime¶

This guide explains how to run a Trust3 Runtime on Azure Kubernetes Service (AKS) using images from your own Azure Container Registry (ACR) instead of pulling directly from the Trust3 Docker proxy.

The default Runtime path in Run Collector (Runtime on K8s tab) uses Basic Config and the Trust3 image hub. Use this guide when your security policy requires Advanced Config and a private ACR.

For cluster and tooling prerequisites, see System Requirements (Kubernetes section).

High-level flow:

1. Create a runtime in the Trust3 portal (obtain API key and save install commands).
2. Mirror required runtime images from the Trust3 registry into your ACR.
3. Create the Kubernetes namespace and registry pull secret on your AKS cluster.
4. Run the Helm install commands from the portal to deploy the runtime agent.

Prerequisites¶

Confirm with your platform team which auth modes are standard for push (mirroring) and pull (AKS workloads).

Step 1 — Create the runtime in the Trust3 portal¶

1.1 — Open the create wizard¶

1. Log in to the Trust3 portal.
2. Go to Settings > Runtime > Create New.

1.2 — Infrastructure Setup¶

On the Infrastructure Setup page:

1. Review the prerequisites panel (for example, AKS cluster configuration, terminal access, required CLI tools) and confirm they apply to your environment. Select Download Script if provided to validate your cluster.
2. Under Configuration Mode, select Advanced Config. This unlocks the Storage & Connectivity and Cloud Permissions steps for fine-tuned setup.
3. Select your Cloud Provider (for example, Azure) and Region, then complete the remaining fields on this page using the in-app helper text.
4. Set Runtime Name — auto-generated by default; you can rename it. This value becomes the Kubernetes namespace for the runtime deployment.

1.3 — Storage & Connectivity¶

On the Storage & Connectivity page:

1. In Custom Docker Image Repository, enter your ACR login server in Docker Repository URL (no https:// prefix), for example:

   Text Only
   1	myregistry.azurecr.io

   This tells Trust3 to pull runtime component images from your ACR instead of the default Trust3 image hub.

2. Disable Automatic DNS Management — external endpoints are not required for this setup.

Complete any remaining required fields on this page, then continue.

Cloud Permissions — you can skip this page for now; it is not required for the custom ACR setup described in this guide.

Proceed to the Deploy step.

1.4 — Deploy (save installation commands)¶

On the Deploy page (final wizard step), the Installation Commands section provides the commands to run on a terminal connected to your AKS cluster.

You will see two blocks:

1. Download values — curl (or wget) to save values.yaml
2. Helm command — helm upgrade --install to deploy the runtime agent

Use the copy icon on each block to copy the full command. Save both commands in a local text file — you will run them later in Part 3.

Example of what the commands look like:

1
2
3
4

# Download values.yaml
curl -fsSX GET https://api.na.trust3ai.com/v2/runtime/runtime-plane/<plane-id>/values/download \
  -H "x-pcloud-key: pc-..." \
  -o values.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Install runtime agent (run later — after mirroring and cluster prep)
helm upgrade --install <release-name> \
  https://api.na.trust3ai.com/v2/runtime/helm/runtime-agent-1.0.0.tgz \
  --username trust3ai \
  --password pc-... \
  --pass-credentials \
  --namespace <plane-namespace> \
  --create-namespace \
  -f values.yaml \
  --set runtime-agent.runtimePrivateKey=<rsa-private-key> \
  --set runtime-agent.runtimeApiKey=<trust3-api-key>

Select Done to finish creating the runtime in the portal.

Extract your Trust3 API key¶

From the curl command, copy the value of the x-pcloud-key header (starts with pc-). The same key appears as --password and --set runtime-agent.runtimeApiKey=... in the Helm command.

Example:

1
2
3

curl -fsSX GET https://api.na.trust3ai.com/v2/runtime/runtime-plane/176/values/download \
  -H "x-pcloud-key: <your-pc-api-key-from-portal>" \
  -o values.yaml

Copy the full value from your portal command (starts with pc-). Do not use example placeholders from documentation.

Use this value as TRUST3_API_KEY in the mirror script (Part 1). Store the API key and private key securely. Do not commit them to source control.

Part 1 — 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, environment template, and versioned image list from Trust3 public artifacts.

Current active release: 9.2.29.2

Replace <release-version> with your Trust3 release (use 9.2.29.2 for the current active release):

1
2
3
4
5
6
7
8

RELEASE_VERSION=9.2.29.2
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
curl -fsSLO "https://trust3ai-artifacts.s3.amazonaws.com/runtime/mirror-images/${RELEASE_VERSION}/images.txt"

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

What the script does¶

• Pulls from the Trust3 proxy: api.na.trust3ai.com (authenticated with your TRUST3_API_KEY)
• Pushes to your ACR (TARGET_REGISTRY)
• Reads the image list from images.txt (one repository:tag per line; see Mirrored images)
• Runs up to 4 parallel pull/tag/push jobs by default (MIRROR_JOBS=4)

The source registry is fixed. Image names and tags are configured in images.txt. Target ACR settings are in .env.

Mirrored images¶

Default entries for release 9.2.29.2 (in images.txt for that version):

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

1
2
3

# repository:tag (no registry host)
runtime-agent:c4ceee1
privacera_diagnostic_client:a4f893c

Configuration (.env and images.txt)¶

Copy the example files and fill in your values:

1
2

cp .env.example .env
# Edit .env with secrets; use images.txt for the release version you downloaded

Required variables:

Target ACR authentication — set ACR_AUTH_MODE and the matching credentials:

Optional variables:

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¶

1
2
3
4
5
6
7
8

# 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

Verify images in ACR¶

1
2

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

Part 2 — Prepare your AKS cluster¶

Complete these steps before running the Helm install commands from the portal.

Step 2.1 — Create the namespace¶

Use the namespace configured for your runtime (from your values.yaml or portal configuration):

1

kubectl create namespace <plane-namespace>

Step 2.2 — Create the registry pull secret¶

Create a Docker registry secret named privacera-hub-secret in the plane namespace. Standard runtime Helm charts reference this name by default.

1
2
3
4
5

kubectl create secret docker-registry privacera-hub-secret \
  --namespace <plane-namespace> \
  --docker-server=<your-acr>.azurecr.io \
  --docker-username=<acr-username-or-sp-app-id> \
  --docker-password=<password-or-client-secret>

Optional annotation to mark the secret as manually managed:

1
2

kubectl annotate secret privacera-hub-secret -n <plane-namespace> \
  trust3ai.com/managed-by=manual

Part 3 — Install the runtime plane¶

Return to the Installation Commands you saved from the Deploy page in Step 1.4 and run them now.

Step 3.1 — Download values.yaml¶

Run the curl (or wget) command from the portal to download the latest values.yaml:

1
2
3

curl -fsSX GET https://api.na.trust3ai.com/v2/runtime/runtime-plane/<plane-id>/values/download \
  -H "x-pcloud-key: <your-pc-api-key>" \
  -o values.yaml

Confirm values.yaml references your ACR, for example:

1
2
3
4
5

runtime-agent:
  image:
    hub: "myregistry.azurecr.io"
    tag: "c4ceee1"
    pullPolicy: "Always"

Step 3.2 — Install the runtime agent with Helm¶

Run the Helm command from the portal Installation Commands section (copy the full command as shown — it includes your release name, namespace, runtimePrivateKey, runtimeApiKey, and credentials):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

helm upgrade --install <release-name> \
  https://api.na.trust3ai.com/v2/runtime/helm/runtime-agent-1.0.0.tgz \
  --username trust3ai \
  --password <trust3-api-key> \
  --pass-credentials \
  --namespace <plane-namespace> \
  --create-namespace \
  -f values.yaml \
  --set runtime-agent.runtimePrivateKey=<rsa-private-key> \
  --set runtime-agent.runtimeApiKey=<trust3-api-key>

Step 3.3 — Verify the runtime agent¶

1
2

kubectl get pods -n <plane-namespace> -l app=runtime-agent
kubectl describe pod -n <plane-namespace> -l app=runtime-agent

Expect 2/2 Running (runtime-agent + diagnostics sidecar). Images should pull from your ACR:

1
2

myregistry.azurecr.io/runtime-agent:<tag>
myregistry.azurecr.io/privacera_diagnostic_client:<tag>

Once the runtime agent is running, it polls Trust3 for configuration and automatically deploys system components (monitoring, diagnostics server, and others) into your cluster. No additional manual steps are required for those workloads.

You can monitor progress with:

1
2

kubectl get pods -n <plane-namespace>
helm list -n <plane-namespace>

Next steps — Add collectors¶

Your runtime is ready. Follow Run Collector (Runtime on K8s tab) to add the AI Assets Collector:

1. Go to Settings > Runtime and open your runtime.
2. Select the Collectors tab.
3. Select Add New and configure the AI Assets Collector.

Registry pull secret — operations notes¶

Alternative: AKS–ACR integration¶

AKS–ACR attach (pulling from ACR without per-pod registry secrets) is not supported for Trust3 runtimes at this time. Support is planned for an upcoming release.

For now, use the manual privacera-hub-secret approach described in this guide.

Troubleshooting¶

Useful commands:

1
2
3
4
5
6
7
8

# Check pull secret exists
kubectl get secret privacera-hub-secret -n <plane-namespace>

# Check pod events
kubectl get events -n <plane-namespace> --sort-by='.lastTimestamp'

# Confirm image references on a deployment
kubectl get deploy -n <plane-namespace> -o jsonpath='{range .items[*]}{.metadata.name}{": "}{range .spec.template.spec.containers[*]}{.image}{" "}{end}{"\n"}{end}'

Quick reference checklist¶

• Create runtime in Trust3 portal (Advanced Config, custom ACR URL, DNS management off)
• Save both portal commands; extract pc-... API key from the curl command
• Mirror runtime images to ACR (mirror-images-to-acr.sh, versioned images.txt)
• Create Kubernetes namespace on AKS
• Create privacera-hub-secret with ACR pull credentials before Helm install
• Run portal curl command to download values.yaml
• Run portal helm upgrade --install command
• Verify runtime-agent pod is Running
• Confirm system components appear in the namespace (deployed automatically by the agent)
• Add collectors from Run Collector (Runtime on K8s tab)

Note — initial install vs future upgrades¶

This guide covers the initial install flow using a custom ACR (release 9.2.29.2).

Future upgrades¶

Before upgrading your runtime or applications in the Trust3 portal:

1. Identify the target release version you are upgrading to.
2. Download the matching images.txt from S3 (image tags are version-specific):

1
2
3

RELEASE_VERSION=9.2.29.2   # set to your target release

curl -fsSLO "https://trust3ai-artifacts.s3.amazonaws.com/runtime/mirror-images/${RELEASE_VERSION}/images.txt"

1. Re-run the mirror script using your existing .env (API key and ACR credentials):

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.

1. Proceed with the runtime upgrade in the portal.

Each release publishes its own folder under runtime/mirror-images/<version>/ on S3. The current active release is 9.2.29.2. Download the images.txt for the version you are installing or upgrading to.