diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index f231b6c0bdb..b437fc7b3e3 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -1,7 +1,7 @@ # Summary [Introduction](./introduction.md) -[Getting Started](./getting-started.md) +[Getting Started](./getting-started-with-aks.md) [Roadmap](./roadmap.md) - [General Topics](./topics/topics.md) - [Azure Service Operator](./topics/aso.md) @@ -50,6 +50,7 @@ - [Development](./developers/development.md) - [Kubernetes Developers](./developers/kubernetes-developers.md) - [AKS as management cluster](./developers/tilt-with-aks-as-mgmt-ilb.md) + - [Getting Started with CAPI Operator](./developers/getting-started-with-capi-operator.md) - [Releasing](./developers/releasing.md) - [Jobs](./developers/jobs.md) - [Reference](./reference/reference.md) diff --git a/docs/book/src/getting-started.md b/docs/book/src/developers/getting-started-with-capi-operator.md similarity index 100% rename from docs/book/src/getting-started.md rename to docs/book/src/developers/getting-started-with-capi-operator.md diff --git a/docs/book/src/getting-started-with-aks.md b/docs/book/src/getting-started-with-aks.md new file mode 100644 index 00000000000..2bcd971e11a --- /dev/null +++ b/docs/book/src/getting-started-with-aks.md @@ -0,0 +1,120 @@ +# Getting started with cluster-api-provider-azure + +## Prerequisites + +### Requirements + + +- A [Microsoft Azure account](https://azure.microsoft.com/) + - Note: If using a new subscription, make sure to [register](https://learn.microsoft.com/azure/azure-resource-manager/management/resource-providers-and-types) 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](https://learn.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest) +- A [supported version](https://github.com/kubernetes-sigs/cluster-api-provider-azure#compatibility) of `clusterctl` + +### Setting up your Azure environment + + 1. Login with the Azure CLI. + + ```bash + az login + ``` + + 2. List your Azure subscriptions. + + ```bash + az account list -o table + ``` + + 3. If more than one account is present, select the account that you want to use. + + ```bash + az account set -s + ``` + + 4. Save your Subscription ID in an environment variable. + + ```bash + export AZURE_SUBSCRIPTION_ID="" + ``` +## Creating an AKS Management Cluster with Workload Identity + + 1. Create an AKS Cluster with Workload Identity and OIDC Endpoint Enabled. + ```bash + az aks create \ + --resource-group \ + --name \ + --enable-oidc-issuer \ + --enable-workload-identity \ + --node-count 2 \ + --node-vm-size Standard_B2s \ + --generate-ssh-keys \ + --location + ``` + + 2. Retrieve Credentials for the AKS Cluster to interact with it using kubectl: + ```bash + az aks get-credentials --resource-group --name + ``` + + 3. Retrieve the OIDC Issuer URL. + ```bash + az aks show \ + --resource-group \ + --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. + ```bash + az identity create \ + --name \ + --resource-group \ + --location + ``` + 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. + ```bash + az role assignment create \ + --assignee \ + --role Contributor \ + --scope /subscriptions/ + ``` + + 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](https://azure.github.io/azure-workload-identity/docs/topics/federated-identity-credential.html#federated-identity-credential-for-a-user-assigned-managed-identity). +For CAPZ, the federated credential should be configured for the capz-manager service account in the capz-system namespace, like the below: +```bash +az identity federated-credential create \ + --name \ + --identity-name \ + --resource-group \ + --issuer \ + --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](https://cluster-api.sigs.k8s.io/user/quick-start.html) 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: + ```bash + kubectl annotate serviceaccount capz-manager \ + -n capz-system \ + azure.workload.identity/client-id= + ``` +## Building your First Cluster + +To create a workload cluster, follow the [Cluster API Quick Start: Create your first workload cluster](https://cluster-api.sigs.k8s.io/user/quick-start.html) for detailed instructions. Ensure you select the "Azure" tabs for Azure-specific guidance. \ No newline at end of file