Deploy AKKO on Azure AKS¶

Azure Kubernetes Service 1.30+ is a supported AKKO target. Combine the managed AKS Web App Routing (or AGIC) for ingress, Azure Disk CSI for storage, and Workload Identity for pod → Azure APIs.

Prerequisites¶

Requirement	Version
AKS	1.30+ (3 × Standard_D4s_v5 minimum — scale for OpenMetadata)
Azure Disk CSI	enabled (default)
Web App Routing (or AGIC)	enabled on the cluster
Workload Identity	enabled (`--enable-workload-identity` at cluster creation)
cert-manager	1.16+ (or AKS managed certs)
`kubectl` + `az` CLI	configured
Helm	≥ 3.14

One-command install¶

AKKO_DOMAIN=akko.customer.example \
AKKO_VERSION=2026.04 \
AKKO_VALUES_EXTRA=helm/examples/values-aks.yaml \
  bash deploy-from-harbor.sh

AKS-specific notes¶

Storage¶

managed-csi-premium is the Azure Premium SSD storage class. For cheaper Standard SSD, swap global.storageClass: managed-csi. Azure Files (RWX) requires the azurefile-csi add-on; not required by AKKO 2026.04.

Ingress¶

AKS "Web App Routing" is the managed NGINX option — cheapest and simplest. If you prefer Azure Application Gateway (layer 7 native + WAF), install AGIC and override:

global:
  ingressClassName: "azure-application-gateway"
ingressAnnotations:
  appgw.ingress.kubernetes.io/ssl-redirect: "true"
  appgw.ingress.kubernetes.io/cookie-based-affinity: "true"

Workload Identity (instead of Pod Identity v1)¶

For pods that need Azure access (e.g. Key Vault reads, Cosmos DB):

az identity federated-credential create \
  --name akko-minio \
  --identity-name akko-platform \
  --resource-group <rg> \
  --issuer <OIDC_ISSUER_URL> \
  --subject system:serviceaccount:akko:akko-minio

Annotate the SA:

akko-minio:
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: "<managed-identity-client-id>"

ACR mirror (private image source)¶

az acr login --name myacr
for img in cockpit postgres spark notebook trino ai-service mlflow \
           airflow dbt mcp-trino mcp-openmetadata docs aden \
           catalog-manager; do
  skopeo copy \
    docker://harbor.akko-ai.com/akko/akko-${img}:2026.04 \
    docker://myacr.azurecr.io/akko/akko-${img}:2026.04
done

Override global.image.registry: myacr.azurecr.io.

Verify¶

kubectl -n akko get pods
kubectl -n akko get ingress
az aks show -g <rg> -n <cluster> --query fqdn -o tsv
kubectl -n akko exec svc/akko-trino -c trino -- trino --execute "SHOW CATALOGS"

Troubleshooting¶

Symptom	Cause	Fix
Ingress address empty	AKS Web App Routing add-on missing	`az aks approuting enable -g <rg> -n <cluster>`
PVC `Pending`	Azure Disk quota exhausted	Azure Portal → Subscription → Quotas
Pod `FailedCreatePodSandBox` with MSI error	Workload Identity annotation missing on SA	Re-annotate and restart the pod
Image pull from ACR failing	AKS has no pull role on the ACR	`az aks update -a monitoring,azure-keyvault-secrets-provider --attach-acr <acr>`