Merge pull request #4273 from dtzar/Podiddeprecation

k8s-ci-robot · web-flow · commit 55e055917e3d · 2023-11-16T19:58:52.000+01:00
Docs: Pod identity deprecation
diff --git 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
@@ -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.
 
-<aside class="note warning"> 
-
-<h1> Warning </h1> 
-
-The capability to set credentials using environment variables has been removed, the required approach is to use `AzureClusterIdentity` as explained [here](multitenancy.md) 
-
-</aside>
-
-## 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
@@ -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
+
+<aside class="note warning">
+
+<h1> Warning </h1>
+The capability to set credentials using environment variables has been removed, the required approach is to use `AzureClusterIdentity` as shown with the below supported identity examples.
+</aside>
+
+<aside class="note warning">
+<h1> Warning </h1>
+All of the methods which utilize AAD Pod Identity will no longer function starting in the 1.13 release of CAPZ.
+</aside>
+
+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: <your-tenant-id>
+  clientID: <your-client-id>
+  allowedNamespaces:
+    list:
+    - <cluster-namespace>
+```
+
+## 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: <azure-tenant-id>
+  clientID: <client-id-of-SP-identity>
+  clientSecret: {"name":"<secret-name-for-client-password>","namespace":"default"}
+  allowedNamespaces:
+    list:
+    - <cluster-namespace>
+```
+
+## 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
@@ -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: <your-tenant-id>
-  clientID: <your-client-id>
-  allowedNamespaces:
-    list:
-    - <cluster-namespace>
-```
+## Deprecated Identity Types
+
+<aside class="note warning">
+
+<h1> Warning </h1>
+The capability to set credentials using environment variables has been removed, the required approach is to use `AzureClusterIdentity` as seen in the [identities](identities.md) page.
+</aside>
+
+<aside class="note warning">
+<h1> Warning </h1>
+All of the remaining methods utilize AAD Pod Identity and will no longer function starting in the 1.13 release of CAPZ.
+</aside>
 
 ### 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: <azure-tenant-id>
-  clientID: <client-id-of-SP-identity>
-  clientSecret: {"name":"<secret-name-for-client-password>","namespace":"default"}
-  allowedNamespaces:
-    list:
-    - <cluster-namespace>
-```
-
-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: <AZURE_SUBSCRIPTION_ID>
-  identityRef:
-    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
-    kind: AzureClusterIdentity
-    name: <name-of-identity>
-    namespace: <namespace-of-identity>
-```
-
-
