Skip to content

Deploy on AKS

Learn how to deploy the DocumentDB Kubernetes Operator on AKS.

Quick start

Before you begin, make sure you have:

  • Azure CLI installed
  • Logged in with az login

For automated deployment, use the playground scripts:

cd documentdb-playground/aks-setup/scripts
./create-cluster.sh --deploy-instance

For complete automation details, see the AKS setup README.

Understanding the configuration

Azure load balancer annotations

When using AKS, set the DocumentDB spec.environment field to aks. Supported values are aks, eks, and gke. If you omit this field, the operator does not apply cloud-specific service annotations. For field details, see the API reference.

spec:
  environment: "aks"

When spec.environment: "aks" is set, the operator adds Azure-specific service annotations:

annotations:
  service.beta.kubernetes.io/azure-load-balancer-external: "true"

The service.beta.kubernetes.io/azure-load-balancer-external annotation is set by the operator for AKS deployments. It is not a generic Kubernetes annotation. This setting helps AKS provision an external load balancer with an IP address that can be reached outside the cluster. For AKS behavior and supported service Use a standard public load balancer in AKS and AKS load balancer annotations.

Storage class

AKS uses the built-in managed-csi storage class by default (StandardSSD_LRS). For production workloads, use a Premium SSD class such as managed-csi-premium.

spec:
  resource:
    storage:
      storageClass: managed-csi-premium

For available classes, see

Monitoring and troubleshooting

Common issues

If the service remains in Pending, verify AKS network profile and load balancer configuration:

az aks show --resource-group RESOURCE_GROUP --name CLUSTER_NAME --query networkProfile

If PVCs do not bind, verify your storage classes and that Azure Disk CSI driver pods are healthy:

kubectl get storageclass
kubectl get pods -n kube-system | grep csi-azuredisk

Cost and security considerations

Cost optimization

  • Use smaller virtual machine (VM) sizes for development, such as Standard_B2s
  • Reduce node count in non-production environments
  • Use Standard SSD where Premium SSD is not required
  • Review AKS pricing for current rates

Security baseline

Hardening examples

Use AKS add-ons to enforce policy and integrate external secret sources. Learn more about Azure Policy for Kubernetes and the Key Vault Secrets Store CSI Driver.

az aks enable-addons \
  --resource-group RESOURCE_GROUP \
  --name CLUSTER_NAME \
  --addons azure-policy

az aks enable-addons \
  --resource-group RESOURCE_GROUP \
  --name CLUSTER_NAME \
  --addons azure-keyvault-secrets-provider

Additional resources