Runtime Manage APIs¶

This guide walks through the full runtime lifecycle: create a runtime, install it on your cluster, check its status, upgrade it, and delete it.

Two keys are used on this page:

Key	When to use it
`TRUST3_API_KEY`	Create the runtime and look up release versions. Mint it in the portal with scope Runtime (manage).
`RUNTIME_SCOPED_KEY`	Status, upgrade, and delete after the runtime exists. Returned in the create response. Runtime apps and collectors also use it.

Why two keys?

TRUST3_API_KEY is an account key used to create runtimes. RUNTIME_SCOPED_KEY belongs to one runtime only, so two runtimes cannot cross-contaminate each other — a key from runtime A cannot status, upgrade, or delete runtime B.

Create and install the runtime¶

These steps use TRUST3_API_KEY.

1. Set your API key¶

To create a key in the Trust3 AI portal:

Sign in at https://na.trust3ai.com.
Go to Settings → API Keys.
Select Generate scoped key, name it, and choose the expiry and scope Runtime (manage).
Copy the key value — it is shown only once.

Set it once in your terminal.

Bash
TRUST3_API_KEY="<your-trust3-api-key>"

2. Pick the release version¶

The runtime is pinned to a release version at create time. Fetch the latest release, or choose a specific one.

Use the latest release¶

Bash
RELEASE_VERSION=$(curl -s -H "x-trust3ai-key: $TRUST3_API_KEY" \
  "https://api.na.trust3ai.com/runtime/releases" | jq -r '.latestVersion')

OR Use a specific release¶

Bash
RELEASE_VERSION=9.2.37.2

3. Create the runtime¶

This example creates an Azure (AKS) runtime with the D2P deployment type, auto-upgrade turned off, a custom registry (imageHub), Key Vault secrets (secretStoreRef is AKV/<vault-name>), and a user-assigned Managed Identity. DNS is managed manually, and t3aiVersion is the RELEASE_VERSION you set above. Replace every <placeholder> before you run the command.

Bash
RUNTIME_NAME="<your-runtime-name>"
AZURE_MANAGED_IDENTITY_CLIENT_ID="<managed-identity-client-id>"
IMAGE_HUB="<your-custom-acr>"
CREDENTIALS_SECRET_STORE=AKV
SECRET_STORE_NAME="<azure-key-vault-name>"
STORAGE_CLASS="<storage-class>"
REGION="<azure-region>"

curl -s -X POST "https://api.na.trust3ai.com/runtime/runtime-plane" \
  -H "x-trust3ai-key: $TRUST3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"$RUNTIME_NAME"'",
    "deploymentType": "D2P",
    "platform": "AKS",
    "autoUpgrade": false,
    "t3aiVersion": "'"$RELEASE_VERSION"'",
    "region": "'"$REGION"'",
    "runtimeConfigs": {
      "namespace": "'"$RUNTIME_NAME"'",
      "azureManagedIdentityClientId": "'"$AZURE_MANAGED_IDENTITY_CLIENT_ID"'",
      "imageHub": "'"$IMAGE_HUB"'",
      "secretStoreRef": "'"$CREDENTIALS_SECRET_STORE/$SECRET_STORE_NAME"'",
      "dnsManagement": "manual",
      "portalBrand": "T3",
      "helm": {
        "persistentVolumeClaims": {
          "trust3-data": { "storageClass": "'"$STORAGE_CLASS"'" }
        }
      }
    }
  }' > create-response.json

echo "Status: $(jq -r '.status' create-response.json)"

4. Read the create response¶

The create call writes the full response to create-response.json and prints only the status (for example CREATED). That file carries the Helm-related commands you need next: a curl command that downloads values.yaml, and the Helm command that installs the runtime. They arrive as one combined helmCommand, so this splits them into separate variables.

Bash
RUNTIME_SCOPED_KEY=$(jq -r '.apiKey' create-response.json)

FULL=$(jq -r '.helmCommand' create-response.json)

VALUES_CMD="${FULL%%helm upgrade*}"

HELM_CMD="helm upgrade${FULL#*helm upgrade}"

echo "RUNTIME_SCOPED_KEY: $RUNTIME_SCOPED_KEY"
echo "VALUES_CMD:"
echo "$VALUES_CMD"
echo "HELM_CMD:"
echo "$HELM_CMD"

Note

Save RUNTIME_SCOPED_KEY. You need it for status, upgrade, and delete below. Runtime apps on the cluster also use it internally, and you can use it later to create collectors in this runtime.

5. Download `values.yaml`¶

Run VALUES_CMD — it calls GET /runtime/runtime-plane/values/download and writes values.yaml.

Bash
bash -c "$VALUES_CMD"

6. Install the runtime with Helm¶

Point kubectl at the AKS cluster you want, then run HELM_CMD. It uses the values.yaml from the previous step.

Bash
kubectl config use-context "<your-aks-cluster>"
bash -c "$HELM_CMD"

Operate the runtime¶

These steps use RUNTIME_SCOPED_KEY from step 4. TRUST3_API_KEY will not work here.

7. Check the runtime status¶

Keep polling this API until status is RUNNING.

Bash
curl -s -H "x-trust3ai-key: $RUNTIME_SCOPED_KEY" "https://api.na.trust3ai.com/runtime/runtime-plane" \
  | jq '{name, status}'

8. Upgrade the runtime¶

Look up the latest version with TRUST3_API_KEY, then send the upgrade with RUNTIME_SCOPED_KEY.

Upgrade to the latest release¶

Bash
RELEASE_VERSION=$(curl -s -H "x-trust3ai-key: $TRUST3_API_KEY" \
  "https://api.na.trust3ai.com/runtime/releases" | jq -r '.latestVersion')

curl -s -X POST "https://api.na.trust3ai.com/runtime/runtime-plane/upgrade" \
  -H "x-trust3ai-key: $RUNTIME_SCOPED_KEY" -H "Content-Type: application/json" \
  -d '{"t3aiVersion":"'"$RELEASE_VERSION"'"}'

OR Upgrade to a specific release¶

Set RELEASE_VERSION to the release you want, then upgrade.

Bash
RELEASE_VERSION=9.2.37.2
curl -s -X POST "https://api.na.trust3ai.com/runtime/runtime-plane/upgrade" \
  -H "x-trust3ai-key: $RUNTIME_SCOPED_KEY" -H "Content-Type: application/json" \
  -d '{"t3aiVersion":"'"$RELEASE_VERSION"'"}'

9. Delete the runtime¶

Bash
curl -s -X DELETE -H "x-trust3ai-key: $RUNTIME_SCOPED_KEY" "https://api.na.trust3ai.com/runtime/runtime-plane"

Returns 200. The in-cluster agent uninstalls all applications, including itself, and removes the TLS secret.