diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index da5989fa07d..4d724f7760e 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -21,11 +21,13 @@ - [GPU-enabled Clusters](./topics/gpu.md) - [Confidential VMs](./topics/confidential-vms.md) - [Trusted Launch for VMs](./topics/trusted-launch-for-vms.md) - - [Identity use cases](./topics/identities-use-cases.md) + - [Identities](./topics/identities.md) + - [Identity use cases](./topics/identities-use-cases.md) + - [Multi-tenancy](./topics/multitenancy.md) + - [Workload Identity](./topics/workload-identity.md) - [IPv6](./topics/ipv6.md) - [Machine Pools (VMSS)](./topics/machinepools.md) - [Managed Clusters (AKS)](./topics/managedcluster.md) - - [Multitenancy](./topics/multitenancy.md) - [Node Outbound Connection](./topics/node-outbound-connection.md) - [OS Disk](./topics/os-disk.md) - [Spot Virtual Machines](./topics/spot-vms.md) @@ -35,7 +37,6 @@ - [Windows](./topics/windows.md) - [Flatcar](./topics/flatcar.md) - [WebAssembly / WASI Pods](./topics/wasi.md) - - [Workload Identity](./topics/workload-identity.md) - [Development](./developers/development.md) - [Kubernetes Developers](./developers/kubernetes-developers.md) - [Releasing](./developers/releasing.md) diff --git a/docs/book/src/topics/identities-use-cases.md b/docs/book/src/topics/identities-use-cases.md index 98e88b34288..a7df39c459e 100644 --- a/docs/book/src/topics/identities-use-cases.md +++ b/docs/book/src/topics/identities-use-cases.md @@ -1,45 +1,22 @@ -## How to use Identities with CAPZ +# Identity User Stories -## CAPZ controller: -This is the identity used by the management cluster to provision infrastructure in Azure - - Multi-tenant config via AzureClusterIdentity - - [AAD Pod Identity](https://azure.github.io/aad-pod-identity/) using Service Principals and Managed Identities: by default, the identity used by the workload cluster running on Azure is the same Service Principal assigned to the management cluster. If an identity is specified on the Azure Cluster Resource, that identity will be used when creating Azure resources related to that cluster. See [Multi-tenancy](multitenancy.md) page for details. -More details in [Azure built-in roles documentation](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles). +This describes some common user stories for identities being utilized with CAPZ. +Please see the core [identities page](identities.md) first. +Also see related [identities use cases](identities-use-cases.md) and [Multi-tenancy](multitenancy.md) pages. - - -## Azure Host Identity: -The identity assigned to the Azure host which in the control plane provides the identity to Azure Cloud Provider, and can be used on all nodes to provide access to Azure services during cloud-init, etc. - -- User-assigned Managed Identity -- System-assigned Managed Identity -- Service Principal -- See details about each type in the [VM identity](vm-identity.md) page - -## Pod Identity: -The identity used by pods running within the workload cluster to provide access to Azure services during runtime. For example, to access blobs stored in Azure Storage or to access Azure database services. - - [AAD Pod Identity](https://azure.github.io/aad-pod-identity/): The workload cluster requires an identity to communicate with Azure. This identity can be either a managed identity (in the form of system-assigned identity or user-assigned identity) or a service principal. The AAD Pod Identity pod allows the cluster to use the Identity referenced by the Azure CLuster to access cloud resources securely with Azure Active Directory. - -## User Stories - -#### Story 1 - Locked down with Service Principal Per Subscription +## Story 1 - Locked down with Service Principal Per Subscription Alex is an engineer in a large organization which has a strict Azure account architecture. This architecture dictates that Kubernetes clusters must be hosted in dedicated Subscriptions with AAD identity having RBAC rights to provision the infrastructure only in the Subscription. The workload clusters must run with a System Assigned machine identity. The organization has adopted Cluster API in order to manage Kubernetes infrastructure, and expects 'management' clusters running the Cluster API controllers to manage 'workload' clusters in dedicated Azure Subscriptions with an AAD account which only has access to that Subscription. The current configuration exists: -* Subscription for each cluster -* AAD Service Principals with Subscription Owner rights for each Subscription -* A management Kubernetes cluster running Cluster API Provider Azure controllers + +- Subscription for each cluster +- AAD Service Principals with Subscription Owner rights for each Subscription +- A management Kubernetes cluster running Cluster API Provider Azure controllers Alex can provision a new workload cluster in the specified Subscription with the corresponding AAD Service Principal by creating new Cluster API resources in the management cluster. Each of the workload cluster machines would run as the System Assigned identity described in the Cluster API resources. The CAPZ controller in the management cluster uses the Service Principal credentials when reconciling the AzureCluster so that it can create/use/destroy resources in the workload cluster. -#### Story 2 - Locked down by Namespace and Subscription +## Story 2 - Locked down by Namespace and Subscription Alex is an engineer in a large organization which has a strict Azure account architecture. This architecture dictates that Kubernetes clusters must be hosted in dedicated Subscriptions with AAD identity having RBAC rights to provision the infrastructure only in the Subscription. The workload clusters must run with a System Assigned machine identity. @@ -49,26 +26,23 @@ The organization has adopted Cluster API in order to manage Kubernetes infrastru API controllers to manage 'workload' clusters in dedicated Azure Subscriptions with an AAD account which only has access to that Subscription. The current configuration exists: -* Subscription for each cluster -* AAD Service Principals with Subscription Owner rights for each Subscription -* A management Kubernetes cluster running Cluster API Provider Azure controllers + +- Subscription for each cluster +- AAD Service Principals with Subscription Owner rights for each Subscription +- A management Kubernetes cluster running Cluster API Provider Azure controllers Alex can provision a new workload cluster in the specified Subscription with the corresponding AAD Service Principal by creating new Cluster API resources in the management cluster in the predetermined namespace. Each of the workload cluster machines would run as the System Assigned identity described in the Cluster API resources. The CAPZ controller in the management cluster uses the Service Principal credentials when reconciling the AzureCluster so that it can create/use/destroy resources in the workload cluster. Erin can provision an identity in a namespace of limited access and define the allowed namespaces, which will include the predetermined namespace for the workload cluster. -#### Story 3 - Using an Azure User Assigned Identity +## Story 3 - Using an Azure User Assigned Identity Erin is an engineer working in a large organization. Erin does not want to be responsible for ensuring Service Principal secrets are rotated on a regular basis. Erin would like to use an Azure User Assigned Identity to provision workload cluster infrastructure. The User Assigned Identity will have the RBAC rights needed to provision the infrastructure in Erin's subscription. The current configuration exists: -* Subscription for the workload cluster -* A User Assigned Identity with RBAC with Subscription Owner rights for the Subscription -* A management Kubernetes cluster running Cluster API Provider Azure controllers +- Subscription for the workload cluster +- A User Assigned Identity with RBAC with Subscription Owner rights for the Subscription +- A management Kubernetes cluster running Cluster API Provider Azure controllers Erin can provision a new workload cluster in the specified Subscription with the Azure User Assigned Identity by creating new Cluster API resources in the management cluster. The CAPZ controller in the management cluster uses the User Assigned Identity credentials when reconciling the AzureCluster so that it can create/use/destroy resources in the workload cluster. - -#### Story 4 - Legacy Behavior Preserved - -Dascha is an engineer in a smaller, less strict organization with a few Azure accounts intended to build all infrastructure. There is a single Azure Subscription named 'dev', and Dascha wants to provision a new cluster in this Subscription. An existing Kubernetes cluster is already running the Cluster API operators and managing resources in the dev Subscription. Dascha can provision a new cluster by creating Cluster API resources in the existing cluster, omitting the ProvisionerIdentity field in the AzureCluster spec. The CAPZ operator will use the Azure credentials provided in its deployment template. diff --git a/docs/book/src/topics/identities.md b/docs/book/src/topics/identities.md new file mode 100644 index 00000000000..b510cf788b0 --- /dev/null +++ b/docs/book/src/topics/identities.md @@ -0,0 +1,70 @@ +# Supported Identity methods + +Identities are used on the management cluster and the VMs/clusters/workloads which get provisioned by the management cluster. +Also see relevant [identities use cases](identities-use-cases.md), [Azure Active Directory integration](aad-integration.md), and [Multi-tenancy](multitenancy.md) pages. + +## Deprecated Identity Types + + + + + +For more details on the deprecated Pod identity types, [see this page](multitenancy.md#deprecated-identity-types) + +## Workload Identity (Recommended) + +Follow this [link](./workload-identity.md) for a quick start guide on setting up workload identity. + +Once you've set up the management cluster with the workload identity (see link above), the corresponding values should be used to create an `AzureClusterIdentity` resource. Create an `azure-cluster-identity.yaml` file with the following content: + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: AzureClusterIdentity +metadata: + name: cluster-identity +spec: + type: WorkloadIdentity + tenantID: + clientID: + allowedNamespaces: + list: + - +``` + +## Manual Service Principal Identity + +Manual Service Principal Identity uses the service principal's `clientSecret` directly fetched from the secret containing it. To use this type of identity, set the identity type as `ManualServicePrincipal` in `AzureClusterIdentity`. For example, + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: AzureClusterIdentity +metadata: + name: example-identity + namespace: default +spec: + type: ManualServicePrincipal + tenantID: + clientID: + clientSecret: {"name":"","namespace":"default"} + allowedNamespaces: + list: + - +``` + +## Azure Host Identity + +The identity assigned to the Azure host which in the control plane provides the identity to Azure Cloud Provider, and can be used on all nodes to provide access to Azure services during cloud-init, etc. + +- User-assigned Managed Identity +- System-assigned Managed Identity +- Service Principal +- See details about each type in the [VM identity](vm-identity.md) page + +More details in [Azure built-in roles documentation](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles). diff --git a/docs/book/src/topics/multitenancy.md b/docs/book/src/topics/multitenancy.md index 1dee83eb304..d7b35757953 100644 --- a/docs/book/src/topics/multitenancy.md +++ b/docs/book/src/topics/multitenancy.md @@ -2,29 +2,32 @@ To enable single controller multi-tenancy, a different Identity can be added to the Azure Cluster that will be used as the Azure Identity when creating Azure resources related to that cluster. -This is achieved using [workload identity](https://azure.github.io/azure-workload-identity). Workload identity is the next iteration of the now deprecated [aad-pod-identity](https://azure.github.io/aad-pod-identity). +This is achieved using [workload identity](workload-identity.md). -## Identity Types +## Supported Identity Types -### Workload Identity (Recommended) +Please read the [identities](identities.md) page for more information on the supported identity types. -Follow this [link](./workload-identity.md) for a quick start guide on setting up workload identity. +### allowedNamespaces -Once you've set up the management cluster with the workload identity (see link above), the corresponding values should be used to create an `AzureClusterIdentity` resource. Create an `azure-cluster-identity.yaml` file with the following content: +AllowedNamespaces is used to identify the namespaces the clusters are allowed to use the identity from. Namespaces can be selected either using an array of namespaces or with label selector. +An empty allowedNamespaces object indicates that AzureClusters can use this identity from any namespace. +If this object is nil, no namespaces will be allowed (default behavior, if this field is not provided) +A namespace should be either in the NamespaceList or match with Selector to use the identity. +Please note NamespaceList will take precedence over Selector if both are set. -```yaml -apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 -kind: AzureClusterIdentity -metadata: - name: cluster-identity -spec: - type: WorkloadIdentity - tenantID: - clientID: - allowedNamespaces: - list: - - -``` +## Deprecated Identity Types + + + + ### AAD Pod Identity using Service Principal With Client Password (Deprecated) @@ -153,60 +156,3 @@ spec: #### Assigning VM identities for cloud-provider authentication When using a user-assigned managed identity to create the workload cluster, a VM identity should also be assigned to each control-plane machine in the workload cluster for Cloud Provider to use. See [here](../topics/vm-identity.md#managed-identities) for more information. - -### Manual Service Principal Identity - -Manual Service Principal Identity is similar to [Service Principal Identity](https://capz.sigs.k8s.io/topics/multitenancy.html#service-principal-identity) except that the service principal's `clientSecret` is directly fetched from the secret containing it. -To use this type of identity, set the identity type as `ManualServicePrincipal` in `AzureClusterIdentity`. For example, - -```yaml -apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 -kind: AzureClusterIdentity -metadata: - name: example-identity - namespace: default -spec: - type: ManualServicePrincipal - tenantID: - clientID: - clientSecret: {"name":"","namespace":"default"} - allowedNamespaces: - list: - - -``` - -The rest of the configuration is the same as that of service principal identity. This useful in scenarios where you don't want to have a dependency on [aad-pod-identity](https://azure.github.io/aad-pod-identity). - -## allowedNamespaces - -AllowedNamespaces is used to identify the namespaces the clusters are allowed to use the identity from. Namespaces can be selected either using an array of namespaces or with label selector. -An empty allowedNamespaces object indicates that AzureClusters can use this identity from any namespace. -If this object is nil, no namespaces will be allowed (default behaviour, if this field is not provided) -A namespace should be either in the NamespaceList or match with Selector to use the identity. -Please note NamespaceList will take precedence over Selector if both are set. - -## IdentityRef in AzureCluster - -The Identity can be added to an `AzureCluster` by using `IdentityRef` field: - -```yaml -apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 -kind: AzureCluster -metadata: - name: example-cluster - namespace: default -spec: - location: eastus - networkSpec: - vnet: - name: example-cluster-vnet - resourceGroup: example-cluster - subscriptionID: - identityRef: - apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 - kind: AzureClusterIdentity - name: - namespace: -``` - -