Skip to content

Commit

Permalink
Merge pull request #4273 from dtzar/Podiddeprecation
Browse files Browse the repository at this point in the history 
Docs: Pod identity deprecation
  • Loading branch information
@k8s-ci-robot
k8s-ci-robot authored Nov 16, 2023
2 parents 4475fa7 + e5680c7 commit 55e0559
Show file tree
Hide file tree
Showing 4 changed files with 113 additions and 122 deletions.
7 changes: 4 additions & 3 deletions docs/book/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down
62 changes: 18 additions & 44 deletions docs/book/src/topics/identities-use-cases.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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.
70 changes: 70 additions & 0 deletions docs/book/src/topics/identities.md
View file
Original file line number Diff line number Diff line change
@@ -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).
96 changes: 21 additions & 75 deletions docs/book/src/topics/multitenancy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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>
```


0 comments on commit 55e0559

Please sign in to comment.