Getting started with cluster-api-provider-azure



  • A Microsoft Azure account
    • Note: If using a new subscription, make sure to register the following resource providers:
      • Microsoft.Compute
      • Microsoft.Network
      • Microsoft.ContainerService
      • Microsoft.ManagedIdentity
      • Microsoft.Authorization
      • Microsoft.ResourceHealth (if the EXP_AKS_RESOURCE_HEALTH feature flag is enabled)
  • Install the Azure CLI
  • A supported version of clusterctl

Setting up your Azure environment

An Azure Service Principal is needed for deploying Azure resources. The below instructions utilize environment-based authentication.

  1. Login with the Azure CLI.
az login
  1. List your Azure subscriptions.
az account list -o table
  1. If more than one account is present, select the account that you want to use.
az account set -s <SubscriptionId>
  1. Save your Subscription ID in an environment variable.
export AZURE_SUBSCRIPTION_ID="<SubscriptionId>"
  1. Create an Azure Service Principal by running the following command or skip this step and use a previously created Azure Service Principal. NOTE: the “owner” role is required to be able to create role assignments for system-assigned managed identity.
az ad sp create-for-rbac --role contributor --scopes="/subscriptions/${AZURE_SUBSCRIPTION_ID}"
  1. Save the output from the above command somewhere easily accessible and secure. You will need to save the tenantID, clientID, and client secret. When creating a Cluster, you will need to provide these values as a part of the AzureClusterIdentity object. Note that authentication via environment variables is now removed and an AzureClusterIdentity is required to be created. An example AzureClusterIdentity object is shown below:
kind: AzureClusterIdentity
  labels: "true"
  name: <cluster-identity-name>
  namespace: default
  allowedNamespaces: {}
  clientID: <clientID>
    name: <client-secret-name>
    namespace: <client-secret-namespace>
  tenantID: <tenantID>
  type: ServicePrincipal

Building your first cluster

Check out the Cluster API Quick Start to create your first Kubernetes cluster on Azure using Cluster API. Make sure to select the “Azure” tabs.

If you are looking to install additional ASO CRDs, set ADDITIONAL_ASO_CRDS to the list of CRDs you want to install. Refer to adding additional CRDs for Azure Service Operator here.


Not all versions of clusterctl are supported. Please see which versions are currently supported


Please see the CAPZ book for in-depth user documentation.