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)
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.

az login

List your Azure subscriptions.

az account list -o table

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

az account set -s <SubscriptionId>

Save your Subscription ID in an environment variable.

export AZURE_SUBSCRIPTION_ID="<SubscriptionId>"

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}"

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:

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AzureClusterIdentity
metadata:
  labels:
    clusterctl.cluster.x-k8s.io/move-hierarchy: "true"
  name: <cluster-identity-name>
  namespace: default
spec:
  allowedNamespaces: {}
  clientID: <clientID>
  clientSecret:
    name: <client-secret-name>
    namespace: <client-secret-namespace>
  tenantID: <tenantID>
  type: ServicePrincipal

The recommended way to build a cluster is to install a CAPZ management cluster using Cluster API Operator, then utilizing a Helm chart to create a workload cluster, specifically an ASO Managed Cluster.

To create a cluster manually, check out the Cluster API Quick Start for in-depth instructions. 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.

Creating a CAPZ Management Cluster with CAPI Operator

First, it is a common practice to create a temporary, local bootstrap cluster to deploy the management cluster. You can either use an existing Kubernetes cluster, or create a kind cluster for this purpose.

kind create cluster

Add the CAPI Operator and cert-manager Helm repositories, which we will use to install the management cluster.

helm repo add capi-operator https://kubernetes-sigs.github.io/cluster-api-operator
helm repo add jetstack https://charts.jetstack.io --force-update
helm repo update

Install cert manager:

helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set installCRDs=true

Create a values.yaml file for the CAPI Operator Helm chart like so:

core: "cluster-api:v1.9.4"
infrastructure: "azure:v1.17.2"
addon: "helm:v0.2.5"
manager:
  featureGates:
    core:
      ClusterTopology: true

Install the CAPI Operator:

helm install capi-operator capi-operator/cluster-api-operator --create-namespace -f values.yaml --wait --timeout 90s

Creating an ASO Managed workload cluster

Once your management cluster is up and running, you can create an ASO Managed Cluster using the azure-aks-aso Helm chart.

Add the cluster-api-charts Helm repository:

helm repo add capi https://mboersma.github.io/cluster-api-charts

Specify values for the CAPZ AKS-ASO Helm chart in a values.yaml file. For example:

credentialSecretName: "aso-credentials"
createCredentials: true
subscriptionID: "subscription-id"
tenantID: "tenant-id"
clientID: "client-id"
# Leave clientSecret blank if using WorkloadIdentity
clientSecret: "client-secret"
# set to podIdentity for managed identity or service principal even if NOT using pod identity
authMode: "podIdentity"

# clusterName defaults to the name of the Helm release
clusterName: ""
location: westus3

managedMachinePoolSpecs:
  pool0:
    count: 1
    mode: System
    vmSize: Standard_DS2_v2
    type: VirtualMachineScaleSets
  pool1:
    count: 1
    mode: User
    vmSize: Standard_DS2_v2
    type: VirtualMachineScaleSets

Install the Helm chart:

helm install quick-start capi/azure-aks-aso -f values.yaml

For more information on the azure-aks-aso Helm chart, see the chart documentation.

Warning

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

Documentation

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

The Cluster API Provider Azure Book