Getting started with cluster-api-provider-azure

Prerequisites

Requirements

• 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)
• The Azure CLI
• A supported version of clusterctl

Setting up your Azure environment

1. Login with the Azure CLI.

az login

2. List your Azure subscriptions.

az account list -o table

3. If more than one account is present, select the account that you want to use.

az account set -s <SubscriptionId>

4. Save your Subscription ID in an environment variable.

export AZURE_SUBSCRIPTION_ID="<SubscriptionId>"

Creating an AKS Management Cluster with Workload Identity

1. Create an AKS Cluster with Workload Identity and OIDC Endpoint Enabled.

az aks create \
--resource-group <resource-group-name> \
--name <aks-cluster-name> \
--enable-oidc-issuer \
--enable-workload-identity \
--node-count 2 \
--node-vm-size Standard_B2s \
--generate-ssh-keys \
--location <region>

2. Retrieve Credentials for the AKS Cluster to interact with it using kubectl:

az aks get-credentials --resource-group <resource-group-name> --name <aks-cluster-name>

3. Retrieve the OIDC Issuer URL.

az aks show \
--resource-group <resource-group-name> \
--name <aks-cluster-name> \
--query "oidcIssuerProfile.issuerUrl" -o tsv

Hold onto the OIDC issuer URL for creating federated credentials.

4. Create a User-Assigned Managed Identity (UAMI) to use for Workload Identity.

az identity create \
--name <uami-name> \
--resource-group <resource-group-name> \
--location <region>

Hold onto the UAMI clientID and principalID for the next steps.

5. Assign the Contributor role to the UAMI so it can manage Azure resources.

az role assignment create \
--assignee <uami-principal-id> \
--role Contributor \
--scope /subscriptions/<subscription-id>

6. Add a Federated Credential to the UAMI

To configure the federated credential for the UAMI, follow the detailed instructions in Azure Workload Identity: Federated identity credential for an Azure AD application. For CAPZ, the federated credential should be configured for the capz-manager service account in the capz-system namespace, like the below:

az identity federated-credential create \
  --name <federated-credential-name> \
  --identity-name <uami-name> \
  --resource-group <resource-group-name> \
  --issuer <oidc-issuer-url> \
  --subject "system:serviceaccount:capz-system:capz-manager" \

7. Initialize the management cluster

Run the following command to initialize the management cluster with Cluster API Provider Azure (CAPZ):

clusterctl init --infrastructure azure

This command sets up the necessary components, including Cluster API Core, CAPZ, and Azure Service Operator (ASO). View the Cluster API Quick Start: Initialize the management cluster documentation for more detailed instructions. Ensure you select the "Azure" tabs for Azure-specific guidance.

7. Annotate the capz-manager service account in the capz-system namespace with the UAMI's clientId:

kubectl annotate serviceaccount capz-manager \
-n capz-system \
azure.workload.identity/client-id=<uami-client-id>

Building your First Cluster

To create a workload cluster, follow the Cluster API Quick Start: Create your first workload cluster for detailed instructions. Ensure you select the "Azure" tabs for Azure-specific guidance.