|
| 1 | +## How to use Identities with CAPZ |
| 2 | + |
| 3 | +## CAPZ controller: |
| 4 | +This is the identity used by the management cluster to provision infrastructure in Azure |
| 5 | + - Env config |
| 6 | + - Service Principal: A [service principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) is an identity in AAD which is described by a TenantID, ClientID, and ClientSecret. The set of these three values will enable the holder to exchange the values for a JWT token to communicate with Azure. The values are normally stored in a file or environment variables. |
| 7 | + - Configuration: |
| 8 | + - Scope: Subscription |
| 9 | + - Role: `Contributor` since the controller is responsible for creating resource groups and cluster resources within the group. To create a resource group within a subscription, one must have subscription contributor rights. Note, this role's scope can be reduced to Resource Group Contributor if all resource groups are created prior to cluster creation. |
| 10 | + - If the workload clusters are going to use system-assigned managed identities, then the role here should be `Owner` to be able to create role assignments for system-assigned managed identity. |
| 11 | +More details in [Azure built-in roles documentation](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles). |
| 12 | + |
| 13 | + - Multi-tenant config |
| 14 | + - [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. |
| 15 | + |
| 16 | +## Azure Host Identity: |
| 17 | +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. |
| 18 | + - Service Principal |
| 19 | + - System Assigned Identity |
| 20 | + - User Assigned Identity |
| 21 | + - See details about each type in the [identity](identity.md) page |
| 22 | + |
| 23 | +## Pod Identity: |
| 24 | +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. |
| 25 | + - [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. |
| 26 | + |
| 27 | +## User Stories |
| 28 | + |
| 29 | +#### Story 1 - Locked down with Service Principal Per Subscription |
| 30 | + |
| 31 | +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 |
| 32 | +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. |
| 33 | + |
| 34 | +The current configuration exists: |
| 35 | +* Subscription for each cluster |
| 36 | +* AAD Service Principals with Subscription Owner rights for each Subscription |
| 37 | +* A management Kubernetes cluster running Cluster API Provider Azure controllers |
| 38 | + |
| 39 | +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. |
| 40 | + |
| 41 | +#### Story 2 - Locked down by Namespace and Subscription |
| 42 | + |
| 43 | +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. |
| 44 | + |
| 45 | +Erin is a security engineer in the same company as Alex. Erin is responsible for provisioning identities. Erin will create a Service Principal for use by Alex to provision the infrastructure in Alex's cluster. The identity Erin creates should only be able to be used in a predetermined Kubernetes namespace where Alex will define the workload cluster. The identity should be able to be used by CAPZ to provision workload clusters in other namespaces. |
| 46 | + |
| 47 | +The organization has adopted Cluster API in order to manage Kubernetes infrastructure, and expects 'management' clusters running the Cluster |
| 48 | +API controllers to manage 'workload' clusters in dedicated Azure Subscriptions with an AAD account which only has access to that Subscription. |
| 49 | + |
| 50 | +The current configuration exists: |
| 51 | +* Subscription for each cluster |
| 52 | +* AAD Service Principals with Subscription Owner rights for each Subscription |
| 53 | +* A management Kubernetes cluster running Cluster API Provider Azure controllers |
| 54 | + |
| 55 | +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 |
| 56 | +create/use/destroy resources in the workload cluster. |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +#### Story 3 - Using an Azure User Assigned Identity |
| 61 | + |
| 62 | +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. |
| 63 | + |
| 64 | +The current configuration exists: |
| 65 | +* Subscription for the workload cluster |
| 66 | +* A User Assigned Identity with RBAC with Subscription Owner rights for the Subscription |
| 67 | +* A management Kubernetes cluster running Cluster API Provider Azure controllers |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +#### Story 4 - Legacy Behavior Preserved |
| 72 | + |
| 73 | +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. |
| 74 | + |
0 commit comments