Azure Kubernetes Service (AKS) provisioner backend

Provision Nora agents into Azure Kubernetes Service (AKS) using Nora’s generic Kubernetes adapter and Admin cluster registry.

AKS uses the same Kubernetes adapter as every Kubernetes provider. Nora stores provider, namespace, exposure, and load-balancer settings on the Admin cluster row; docker-compose.kubernetes.yml only mounts kubeconfig files into the control-plane containers.

Step-by-step setup

1. Prerequisites

Azure subscription with permission to create AKS clusters.
An existing AKS cluster (or create one — Azure Portal → Kubernetes services → Create).

Use the cluster Overview blade to confirm the AKS cluster name and resource group before running the CLI commands below.

Azure Portal — AKS cluster overview (cluster name and resource group)

2. Install and log in with Azure CLI

Install the Azure CLI on the host that runs Nora, then authenticate against the Azure subscription that owns the AKS cluster. Azure Cloud Shell already includes az, but the kubeconfig file still needs to be saved on the Nora host.

# macOS
brew update && brew install azure-cli

# Ubuntu/Debian/WSL
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Windows PowerShell
winget install -e --id Microsoft.AzureCLI

After installation, confirm the CLI is available and sign in:

az version
az login

# Use this instead when the host has no browser:
az login --use-device-code

az account set --subscription <subscription-id>
az account show --query "{subscription:name, id:id, tenant:tenantId}" --output table

For other package managers or locked-down hosts, use Microsoft’s Azure CLI install guide and Azure CLI authentication guide.

3. Install kubectl

Install kubectl on the same host where you will run Nora setup and verification commands. For AKS, the shortest path is Azure CLI’s Kubernetes tool installer:

az aks install-cli
kubectl version --client

If you prefer an OS package manager:

# macOS
brew install kubectl

# Ubuntu with snap
sudo snap install kubectl --classic

# Windows PowerShell
winget install -e --id Kubernetes.kubectl

For other Linux distributions or direct binary installs, use the official Kubernetes kubectl install guide.

4. Create the kubeconfig

mkdir -p .secrets
az aks get-credentials \
  --resource-group <resource-group> \
  --name <cluster-name> \
  --admin \
  --file ./.secrets/aks-kubeconfig \
  --overwrite-existing

You can copy this command directly from the cluster’s Connect blade in the Azure Portal.

AKS Connect blade — Azure Portal — Cluster → Connect: copy the get-credentials command

5. Verify access from the host

kubectl --kubeconfig ./.secrets/aks-kubeconfig get nodes

6. Configure Nora

Set the generic Kubernetes mount variable in .env:

mkdir -p ./.secrets/kubeconfigs
cp ./.secrets/aks-kubeconfig ./.secrets/kubeconfigs/aks-eastus2
NORA_KUBECONFIGS_DIR=./.secrets/kubeconfigs

For two or more AKS clusters, put each kubeconfig under NORA_KUBECONFIGS_DIR and use Admin paths such as /kubeconfigs/aks-eastus2 and /kubeconfigs/aks-westus2.

7. Start the stack

docker compose -f docker-compose.yml -f docker-compose.kubernetes.yml up -d --build

This smoke-mode command is for the local nginx config (NGINX_CONFIG_FILE=nginx.conf, usually NGINX_HTTP_PORT=8080). If your .env already points to the public TLS config (NGINX_CONFIG_FILE=nginx.public.conf), include the tracked infra/docker-compose.public-tls.yml layer as shown in Promote to production; otherwise nginx will not mount /etc/letsencrypt and Cloudflare can return 521 because the origin web server is down.

8. Register this cluster in Admin

Open Admin -> Kubernetes, click Add cluster, and use these values:

Field	Value
Cluster id	`aks-eastus2`
Label	`AKS East US 2`
Provider	`AKS`
Actual cluster name	The Azure AKS cluster name, for example `nora-dns-vjb9kjjz`
Credential mode	`Mounted kubeconfig path`
Kubeconfig path	`/kubeconfigs/aks-eastus2`
Fallback namespace	`nora-openclaw-agents`
OpenClaw namespace	`nora-openclaw-agents`
Hermes namespace	`nora-hermes-agents`
Exposure mode	`LoadBalancer`
Service annotations JSON	`{}` for public load balancers, or `{"service.beta.kubernetes.io/azure-load-balancer-internal":"true"}` for internal load balancers
Source ranges	Your Nora control-plane egress CIDR when you can restrict access
Load balancer class	Leave empty for normal AKS Services

Do not put ./.secrets/aks-kubeconfig in the Admin Kubeconfig path when Nora runs in Docker Compose. That is the host-side path; the containers see files from NORA_KUBECONFIGS_DIR under /kubeconfigs.

9. Deploy test agents

Open the dashboard at http://127.0.0.1:8080, sign in, and create an OpenClaw agent with the AKS cluster label you registered. To validate Hermes on AKS, create a second agent with Runtime = Hermes and the same AKS execution target.

Backend picker — Nora deploy wizard — Backend dropdown showing Kubernetes on AKS

Kubernetes selected — Nora deploy wizard — Kubernetes on AKS selected

Agent detail K8s — Agent detail — status running with the AKS LoadBalancer address

AKS Service options

For a public load balancer, leave Service annotations JSON empty and restrict access with Source ranges when possible. For an internal AKS load balancer:

{ "service.beta.kubernetes.io/azure-load-balancer-internal": "true" }

Confirm the LoadBalancer SKU in the Azure Portal under Settings → Networking matches what your subnet policies allow.

AKS networking settings — Azure Portal — Cluster → Settings → Networking (LoadBalancer SKU)

Do not set the Admin Runtime host to the AKS API server address. Nora uses the Kubernetes API through kubeconfig, and agent gateway/runtime traffic uses the per-agent Service address.

Verification

kubectl --kubeconfig ./.secrets/aks-kubeconfig -n nora-openclaw-agents get deploy,svc,pods
# If Hermes is enabled and deployed:
kubectl --kubeconfig ./.secrets/aks-kubeconfig -n nora-hermes-agents get deploy,svc,pods
docker compose -f docker-compose.yml -f docker-compose.kubernetes.yml logs worker-provisioner

For real e2e, enable the Kubernetes matrix cell:

cd e2e
REAL_ENABLE_OPENCLAW_DOCKER=0 REAL_ENABLE_OPENCLAW_K8S=1 \
  REAL_ENABLE_HERMES_DOCKER=0 REAL_ENABLE_HERMES_K8S=1 \
  BASE_URL=http://localhost:8080 npm run test:real:matrix

Agent logs K8s — Logs tab — worker-provisioner output during a successful AKS deploy

Automated smoke

Once your AKS kubeconfig is in place, run the shared lifecycle smoke. The AKS script deploys both OpenClaw and Hermes by default:

cd e2e
KUBECONFIG_PATH=$PWD/../.secrets/aks-kubeconfig npm run smoke:k8s-aks

This script is operator-run only — it provisions real workloads against a live AKS cluster and is not part of CI. Set K8S_SMOKE_RUNTIME_FAMILIES=openclaw for a single-runtime check, K8S_SMOKE_CELLS=openclaw:nemoclaw plus NVIDIA_API_KEY for a NemoClaw run, or KEEP_ENV=true to leave the stack running after the script finishes.

Promote to production

Once the smoke is green, switch from the dev-mode stack to the prod-mode stack. The only changes vs the testing setup are nginx (public config + TLS) and Compose mode (infra/docker-compose.public-tls.yml for prod Dockerfiles, TLS mounts, public ports, and restart policies).

1. Tighten the LoadBalancer source ranges

Replace the smoke-time <nora-control-plane-egress-cidr> placeholder with your production control plane’s actual egress CIDR (e.g. the public IP of the host running Nora). Combine with internal-LB annotations if you’re keeping agents on a private subnet.

2. Switch nginx to public + TLS

In .env:

NGINX_CONFIG_FILE=nginx.public.conf
NGINX_HTTP_PORT=80

Provision Let’s Encrypt certs once:

sudo ./infra/setup-tls.sh <your-domain>

3. Stop the smoke-mode stack

docker compose -f docker-compose.yml -f docker-compose.kubernetes.yml down

4. Start the prod-mode stack

docker compose \
  -f docker-compose.yml \
  -f infra/docker-compose.public-tls.yml \
  -f docker-compose.kubernetes.yml \
  up -d --build

5. Confirm

docker compose ps
curl -fsS https://<your-domain>/api/health
docker compose logs worker-provisioner | tail -50

Deploy a real agent from the UI and confirm it reaches running and the AKS LoadBalancer assigns an external IP.

Getting started

Concepts

Configuration

Guides

API Reference

Support

Kubernetes aks

Azure Kubernetes Service (AKS) provisioner backend

Step-by-step setup

1. Prerequisites

2. Install and log in with Azure CLI

3. Install kubectl

4. Create the kubeconfig

5. Verify access from the host

6. Configure Nora

7. Start the stack

8. Register this cluster in Admin

9. Deploy test agents

AKS Service options

Verification

Automated smoke

Promote to production

1. Tighten the LoadBalancer source ranges

2. Switch nginx to public + TLS

3. Stop the smoke-mode stack

4. Start the prod-mode stack

5. Confirm

See also

​Azure Kubernetes Service (AKS) provisioner backend

​Step-by-step setup

​1. Prerequisites

​2. Install and log in with Azure CLI

​3. Install kubectl

​4. Create the kubeconfig

​5. Verify access from the host

​6. Configure Nora

​7. Start the stack

​8. Register this cluster in Admin

​9. Deploy test agents

​AKS Service options

​Verification

​Automated smoke

​Promote to production

​1. Tighten the LoadBalancer source ranges

​2. Switch nginx to public + TLS

​3. Stop the smoke-mode stack

​4. Start the prod-mode stack

​5. Confirm

​See also

Azure Kubernetes Service (AKS) provisioner backend

Step-by-step setup

1. Prerequisites

2. Install and log in with Azure CLI

3. Install kubectl

4. Create the kubeconfig

5. Verify access from the host

6. Configure Nora

7. Start the stack

8. Register this cluster in Admin

9. Deploy test agents

AKS Service options

Verification

Automated smoke

Promote to production

1. Tighten the LoadBalancer source ranges

2. Switch nginx to public + TLS

3. Stop the smoke-mode stack

4. Start the prod-mode stack

5. Confirm

See also