sigs.k8s.io/cluster-api-provider-azure@v1.17.0/docs/book/src/topics/identities.md (about)

     1  # Supported Identity methods
     2  
     3  Identities are used on the management cluster and the VMs/clusters/workloads which get provisioned by the management cluster.
     4  Also see relevant [identities use cases](identities-use-cases.md), [Azure Active Directory integration](aad-integration.md), and [Multi-tenancy](multitenancy.md) pages.
     5  
     6  ## Deprecated Identity Types
     7  
     8  <aside class="note warning">
     9  <h1> Warning </h1>
    10  The ability to set credentials using environment variables has been removed. Instead, use <code class="hjls">AzureClusterIdentity</code> as described below.
    11  </aside>
    12  
    13  <aside class="note warning">
    14  <h1> Warning </h1>
    15  The identity type <code class="hjls">ManualServicePrincipal</code> has been deprecated because it is now identical to <code class="hjls">ServicePrincipal</code> and therefore redundant. None of the identity types use AAD Pod Identity any longer.
    16  </aside>
    17  
    18  For details on the deprecated identity types, [see this page](multitenancy.md#deprecated-identity-types).
    19  
    20  ## Workload Identity (Recommended)
    21  
    22  Follow this [link](./workload-identity.md) for a quick start guide on setting up workload identity.
    23  
    24  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:
    25  
    26  ```yaml
    27  apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    28  kind: AzureClusterIdentity
    29  metadata:
    30    name: cluster-identity
    31  spec:
    32    type: WorkloadIdentity
    33    tenantID: <your-tenant-id>
    34    clientID: <your-client-id>
    35    allowedNamespaces:
    36      list:
    37      - <cluster-namespace>
    38  ```
    39  
    40  ## Service Principal
    41  
    42  Service Principal identity uses the service principal's `clientSecret` in a Kubernetes Secret. To use this type of identity, set the identity type as `ServicePrincipal` in `AzureClusterIdentity`. For example,
    43  
    44  ```yaml
    45  apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    46  kind: AzureClusterIdentity
    47  metadata:
    48    name: example-identity
    49    namespace: default
    50  spec:
    51    type: ServicePrincipal
    52    tenantID: <azure-tenant-id>
    53    clientID: <client-id-of-SP-identity>
    54    clientSecret: {"name":"<secret-name-for-client-password>","namespace":"default"}
    55    allowedNamespaces:
    56      list:
    57      - <cluster-namespace>
    58  ```
    59  
    60  Deploy this resource to your cluster:
    61  ```bash
    62  kubectl apply -f azure-cluster-identity.yaml
    63  ```
    64  
    65  A Kubernetes Secret should also be created to store the client password:
    66  
    67  ```bash
    68  kubectl create secret generic "${AZURE_CLUSTER_IDENTITY_SECRET_NAME}" --from-literal=clientSecret="${AZURE_CLIENT_SECRET}"
    69  ```
    70  
    71  The resulting Secret should look similar to the following example:
    72  
    73  ```yaml
    74  apiVersion: v1
    75  kind: Secret
    76  metadata:
    77    name: <secret-name-for-client-password>
    78  type: Opaque
    79  data:
    80    clientSecret: <client-secret-of-SP-identity>
    81  ```
    82  
    83  ## Service Principal With Certificate
    84  
    85  Once a new SP Identity is created in Azure, the corresponding values should be used to create an `AzureClusterIdentity` resource:
    86  
    87  ```yaml
    88  apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    89  kind: AzureClusterIdentity
    90  metadata:
    91    name: example-identity
    92    namespace: default
    93  spec:
    94    type: ServicePrincipalCertificate
    95    tenantID: <azure-tenant-id>
    96    clientID: <client-id-of-SP-identity>
    97    clientSecret: {"name":"<secret-name-for-client-password>","namespace":"default"}
    98    allowedNamespaces:
    99      list:
   100      - <cluster-namespace>
   101  ```
   102  
   103  If needed, convert the PEM file to PKCS12 and set a password:
   104  
   105  ```bash
   106  openssl pkcs12 -export -in fileWithCertAndPrivateKey.pem -out ad-sp-cert.pfx -passout pass:<password>
   107  ```
   108  
   109  Create a k8s secret with the certificate and password:
   110  
   111  ```bash
   112  kubectl create secret generic "${AZURE_CLUSTER_IDENTITY_SECRET_NAME}" --from-file=certificate=ad-sp-cert.pfx --from-literal=password=<password>
   113  ```
   114  
   115  The resulting Secret should look similar to the following example:
   116  
   117  ```yaml
   118  apiVersion: v1
   119  kind: Secret
   120  metadata:
   121    name: <secret-name-for-client-password>
   122  type: Opaque
   123  data:
   124    certificate: CERTIFICATE
   125    password: PASSWORD
   126  ```
   127  
   128  ## User-Assigned Managed Identity
   129  
   130  <aside class="note">
   131  
   132  <h1> Note </h1>
   133  
   134  This option is only available when the cluster is managed from a Kubernetes cluster running on Azure.
   135  
   136  </aside>
   137  
   138  #### Prerequisites
   139  
   140  1. [Create](https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity) a user-assigned managed identity in Azure.
   141  2. [Create a role assignment](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-assign-access-azure-resource?pivots=identity-mi-access-portal#use-azure-rbac-to-assign-a-managed-identity-access-to-another-resource-using-the-azure-portal) to give the identity Contributor access to the Azure subscription where the workload cluster will be created.
   142  3. Configure the identity on the management cluster nodes by adding it to each worker node VM. If using AKS as the management cluster see [these instructions](https://learn.microsoft.com/azure/aks/use-managed-identity).
   143  
   144  #### Creating the AzureClusterIdentity
   145  
   146  After a user-assigned managed identity is created in Azure and assigned to the management cluster, the corresponding values should be used to create an `AzureClusterIdentity` resource:
   147  
   148  ```yaml
   149  apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
   150  kind: AzureClusterIdentity
   151  metadata:
   152    name: example-identity
   153    namespace: default
   154  spec:
   155    type: UserAssignedMSI
   156    tenantID: <azure-tenant-id>
   157    clientID: <client-id-of-user-assigned-identity>
   158    allowedNamespaces:
   159      list:
   160      - <cluster-namespace>
   161  ```
   162  
   163  ### Assigning VM identities for cloud provider authentication (self-managed)
   164  
   165  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 Azure Cloud Provider to use. See [here](../self-managed/vm-identity.md#managed-identities) for more information.
   166  
   167  
   168  ## Azure Host Identity
   169  
   170  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.
   171  
   172  - User-assigned Managed Identity
   173  - System-assigned Managed Identity
   174  - Service Principal
   175  - See details about each type in the [VM identity](../self-managed/vm-identity.md) page
   176  
   177  More details in [Azure built-in roles documentation](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles).