AKS Platform: Prerequisites¶
This page lists what must exist before the platform team can deploy, per variant. In the managed model the customer provides the items marked as customer; in the self-managed model your own teams provide all of them (Operating models).
All variants¶
| Item | Detail |
|---|---|
| Azure subscription and region | Active subscription with enough quota for the node pools |
| Terraform state storage | A storage account and container for the remote state. The pipeline identity needs Storage Blob Data Contributor on it. One state key per platform and environment |
| A pipeline identity | A federated identity (OIDC, no secrets) with the roles in Deployment |
| Entra ID permissions | Permission to create groups: Microsoft Graph application permission Group.ReadWrite.All with admin consent, or the Entra role Groups Administrator for the pipeline identity |
| Pipeline agent | An agent that can reach the Terraform state storage, management.azure.com and login.microsoftonline.com. For a private cluster API it also needs a network path to the API server |
| Cluster admin group | An Entra ID group for the cluster admins (the platform admins group is passed to the cluster) |
| Configuration and variables repositories | The configuration files per environment, and the authentication variables the pipeline loads at run time |
AKS in Azure¶
| Item | Standalone | Hub-integrated |
|---|---|---|
| Address plan | VNet CIDR plus the four subnet CIDRs, a service CIDR and a pod CIDR | The four subnets and ranges from the hub, plus service and pod CIDRs |
| Spoke VNet and subnets | Created | Created by the hub: nodes, ingress, private endpoints, API server (delegated) |
| Peering and firewall rules for AKS egress | Not applicable | Required. Missing rules make the cluster bootstrap fail |
| Private DNS zones for Key Vault and container registry | Created (Key Vault) | Provided and linked by the hub |
| Spoke subscription permissions | Contributor on the subscription | Read the VNet and subnets, and create role assignments on the spoke VNet |
| Container registry (optional) | IDs in aks_acr_ids get AcrPull for the kubelet |
The same |
| Log Analytics workspace (optional) | Needed for monitoring, diagnostics, alerts and Defender | The same |
AKS on Azure Local¶
These are infrastructure resources that cannot be created remotely.
| Item | Provided by |
|---|---|
| Azure Local cluster, registered and healthy | Customer |
| Arc Resource Bridge, deployed and healthy | Customer |
| Custom location (resource ID) | Customer |
| Logical network for the node networking (resource ID) | Customer |
| Subscription ID, tenant ID, region where Azure Local is registered | Customer |
| Resource providers registered (the bootstrap checks and registers the main ones) | Pipeline or customer |
| Agent pool on Linux with bash and PowerShell, with private network access | Customer |
| Terraform state storage reachable from the agent | Customer |
| Entra ID group object ID(s) for the cluster admins | Customer |
| IP range for MetalLB, not overlapping with existing networks | Customer |
MetalLB advertise mode: ARP (default), BGP or Both. BGP needs peer name, both AS numbers and the peer address |
Customer |
| DNS servers reachable from the cluster | Customer |
Firewall path from the Arc Resource Bridge¶
Verify before the bootstrap
The Arc Resource Bridge sits on the management network. It must reach TCP port 6443 (the Kubernetes API server) on the
control plane IP of the new cluster, on the VLAN of the logical network. A default firewall rule on the customer's
on-premises network blocked this path on a previous deployment, and cluster creation failed with APIServerNotOnline.
Have the network team open the path and test it before you run the bootstrap, for example with
Test-NetConnection <control-plane-ip> -Port 6443 from the management network, or with the Microsoft diagnostic for an
unreachable AKS Arc API server.
What the pipeline creates¶
You do not need to prepare the following. The bootstrap and Terraform create them:
| Resource | Created by |
|---|---|
| Resource group for the cluster, AKS Arc cluster, OIDC issuer and workload identity | Bootstrap |
| MetalLB load balancer | Bootstrap |
| Resource provider registrations | Bootstrap |
| Arc extensions (Argo CD, Azure Policy, Arc Networking), Entra ID groups, managed identities, Key Vault, Azure Policy assignment | Terraform |
Pipeline identity for Azure Local (Azure DevOps)¶
| Role | Scope | Purpose |
|---|---|---|
| Contributor | Subscription or the cluster resource group | Resource groups, cluster, extensions, Key Vault |
| Storage Blob Data Contributor | State storage account | Read and write the state |
| User Access Administrator | Cluster resource group | Only if the identity module assigns Azure roles |
The Azure DevOps pipeline reads two values from a variable group (AZURE_SERVICE_CONNECTION and AGENT_POOL_NAME) because
Azure DevOps needs them before any step runs. Everything else is read from a configuration file in the repository
(<environment>.pipeline-vars.yml). Approval gates for apply and destroy are set on an Azure DevOps environment.
Sequence¶
- Provide the values in the tables above.
- The platform team creates the pipeline, the variable group and the environment.
- Run a
planto check connectivity and configuration. - Deploy: bootstrap (Azure Local only), then Terraform.