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 theEXP_AKS_RESOURCE_HEALTH
feature flag is enabled)
- Note: If using a new subscription, make sure to register the following resource providers:
- 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.
- Login with the Azure CLI.
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
, andclient secret
. When creating a Cluster, you will need to provide these values as a part of theAzureClusterIdentity
object. Note that authentication via environment variables is now removed and anAzureClusterIdentity
is required to be created. An exampleAzureClusterIdentity
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
Building your first cluster
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.