Skip to content

Commit e521dec

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #4776 from mboersma/update-azwi-docs
Clean up Azure AD Workload ID docs
2 parents c446c80 + ca91421 commit e521dec

File tree

1 file changed

+134
-135
lines changed

1 file changed

+134
-135
lines changed

‎docs/book/src/topics/workload-identity.md‎

Lines changed: 134 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,86 @@
11
# Workload Identity
22

3-
Azure AD Workload identity is the next iteration of Azure AD Pod identity
4-
that enables Kubernetes applications (e.g. CAPZ) to access Azure cloud
3+
Azure AD Workload identity is the next iteration of Azure AD Pod identity
4+
that enables Kubernetes applications such as CAPZ to access Azure cloud
55
resources securely with Azure Active Directory.
66

7-
This document describes a quick start guide of using workload identity and
8-
assumes that you have access to Azure cloud.
7+
Let's help you get started using workload identity. We assume
8+
you have access to Azure cloud services.
99

10-
Workload identity is currently worked upon and cloud provider azure
11-
integration is in progress. Please refer to [this](https://github.com/kubernetes-sigs/cluster-api-provider-azure/issues/3589) issue for details.
12-
For more information, please refer to the [proposal](https://github.com/kubernetes-sigs/cluster-api-provider-azure/blob/main/docs/proposals/20221611-workload-identity-integration.md)
10+
## Quick start
1311

14-
## Workload Identity Quick Start Guide
12+
### Set up a management cluster with kind
1513

16-
### Setting Up Management Cluster on Kind
14+
- Create a private and public key pair. For example, using OpenSSL:
1715

18-
- Create a public and private key pair. For example, you can generate the
19-
key pairs using OpenSSL.
16+
```bash
17+
openssl genrsa -out sa.key 2048
18+
openssl rsa -in sa.key -pubout -out sa.pub
19+
```
2020

21-
Generate a private key called `sa.key` using the following command:
22-
```bash
23-
$ openssl genrsa -out sa.key 2048
24-
```
21+
Set the environment variable `SERVICE_ACCOUNT_SIGNING_KEY_FILE` to the full path
22+
of the `sa.key` private key file you just generated, and set `SERVICE_ACCOUNT_KEY_FILE`
23+
to the generated `sa.pub` public key file.
2524

26-
Set the environment variable `SERVICE_ACCOUNT_SIGNING_KEY_FILE` to the path of the
27-
generated `sa.key`. This ENV var will be used in the upcoming step.
28-
Note: You can use `readlink -f sa.key` to get the absolute path of the key file.
25+
```bash
26+
export SERVICE_ACCOUNT_SIGNING_KEY_FILE=$(realpath sa.key)
27+
export SERVICE_ACCOUNT_KEY_FILE=$(realpath sa.pub)
28+
```
2929

30-
Generate a public key using the private key.
31-
```bash
32-
$ openssl rsa -in sa.key -pubout -out sa.pub
33-
```
34-
Set the environment variable `SERVICE_ACCOUNT_KEY_FILE` to the path of the
35-
generated `sa.pub`. This ENV var will be used in the upcoming step.
36-
37-
- Create and upload Discovery and JWKS document using this [link](https://azure.github.io/azure-workload-identity/docs/installation/self-managed-clusters/oidc-issuer.html)
38-
39-
- At this stage, you will need to create TWO federated identity credentials: one for CAPZ and one for ASO.
40-
- You can create those either with Azure AD application or user-assigned
41-
identity. Please note that user assigned identity will need to be created
42-
regardless because cloud provider azure integration is not yet done. The
43-
steps are mentioned in the next section of workload cluster creation.
44-
- The next list items links to steps on creating the federated
45-
identity credentials. You will need to set up several environment
46-
variables for each one:
47-
- `SERVICE_ACCOUNT_NAMESPACE` : Namespace where the capz-manager and
48-
azureserviceoperator-controller-manager pods will run.
49-
- `SERVICE_ACCOUNT_NAME` : Name of the capz-manager or azureserviceoperator-default k8s service account.
50-
- `SERVICE_ACCOUNT_ISSUER` : This is the path of the Azure storage
51-
container which you created in the previous step which is:
52-
`"https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/"`
53-
54-
- Create federated identity credentials for each of CAPZ and ASO using the steps outlined [here](https://azure.github.io/azure-workload-identity/docs/topics/federated-identity-credential.html)
55-
You can either use `user-assigned-identity` or `AD application` to create federated identity credential and add `contributor` role to it.
56-
57-
- Create a Kind cluster with necessary flags with the following command:
30+
These environment variables will be used later, when creating the kind cluster.
5831

59-
```bash
60-
cat <<EOF | kind create cluster --name azure-workload-identity --config=-
61-
kind: Cluster
62-
apiVersion: kind.x-k8s.io/v1alpha4
63-
nodes:
64-
- role: control-plane
65-
extraMounts:
66-
- hostPath: ${SERVICE_ACCOUNT_KEY_FILE}
67-
containerPath: /etc/kubernetes/pki/sa.pub
68-
- hostPath: ${SERVICE_ACCOUNT_SIGNING_KEY_FILE}
69-
containerPath: /etc/kubernetes/pki/sa.key
70-
kubeadmConfigPatches:
71-
- |
72-
kind: ClusterConfiguration
73-
apiServer:
74-
extraArgs:
75-
service-account-issuer: ${SERVICE_ACCOUNT_ISSUER}
76-
service-account-key-file: /etc/kubernetes/pki/sa.pub
77-
service-account-signing-key-file: /etc/kubernetes/pki/sa.key
78-
controllerManager:
79-
extraArgs:
80-
service-account-private-key-file: /etc/kubernetes/pki/sa.key
81-
EOF
82-
```
32+
- Create and upload a discovery document
8333

84-
- Initialize a management cluster using `clusterctl` using the below command.
85-
If you do not have `clusterctl` installed, then follow this [link](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl)
86-
to install.
87-
```bash
88-
$ clusterctl init --infrastructure azure
89-
```
34+
Create and upload a JWKS discovery document by following [these instructions](https://azure.github.io/azure-workload-identity/docs/installation/self-managed-clusters/oidc-issuer.html).
35+
36+
- Create two federated identity credentials
37+
38+
Export environment variables used for creating a federated identity credential:
39+
40+
- `SERVICE_ACCOUNT_NAMESPACE`: Namespace where the capz-manager and
41+
azureserviceoperator-controller-manager pods will run. Default is `capz-system`.
42+
- `SERVICE_ACCOUNT_NAME`: Name of the capz-manager or azureserviceoperator-default k8s service account. Default is `capz-manager` for CAPZ and `azureserviceoperator-default` for ASO.
43+
- `SERVICE_ACCOUNT_ISSUER`: Path of the Azure storage container created in the previous step, specifically:
44+
- `"https://${AZURE_STORAGE_ACCOUNT}.blob.core.windows.net/${AZURE_STORAGE_CONTAINER}/"`
45+
46+
Create two federated identity credentials, one for CAPZ and one for ASO, by following [these instructions](https://azure.github.io/azure-workload-identity/docs/topics/federated-identity-credential.html). You'll need to set `SERVICE_ACCOUNT_NAME` and `SERVICE_ACCOUNT_NAMESPACE` to different values for each credential.
47+
Use either `user-assigned-identity` or `AD application` when creating the credentials, and add the `contributor` role to each.
48+
49+
- Create a kind cluster with the following command:
50+
51+
```bash
52+
cat <<EOF | kind create cluster --name azure-workload-identity --config=-
53+
kind: Cluster
54+
apiVersion: kind.x-k8s.io/v1alpha4
55+
nodes:
56+
- role: control-plane
57+
extraMounts:
58+
- hostPath: ${SERVICE_ACCOUNT_KEY_FILE}
59+
containerPath: /etc/kubernetes/pki/sa.pub
60+
- hostPath: ${SERVICE_ACCOUNT_SIGNING_KEY_FILE}
61+
containerPath: /etc/kubernetes/pki/sa.key
62+
kubeadmConfigPatches:
63+
- |
64+
kind: ClusterConfiguration
65+
apiServer:
66+
extraArgs:
67+
service-account-issuer: ${SERVICE_ACCOUNT_ISSUER}
68+
service-account-key-file: /etc/kubernetes/pki/sa.pub
69+
service-account-signing-key-file: /etc/kubernetes/pki/sa.key
70+
controllerManager:
71+
extraArgs:
72+
service-account-private-key-file: /etc/kubernetes/pki/sa.key
73+
EOF
74+
```
75+
76+
- Initialize the kind cluster as a CAPZ management cluster using `clusterctl`:
77+
78+
```bash
79+
clusterctl init --infrastructure azure
80+
```
81+
82+
If you don't have `clusterctl` installed, follow [these instructions](https://cluster-api.sigs.k8s.io/user/quick-start.html#install-clusterctl)
83+
to install it.
9084
9185
### Creating a Workload Cluster
9286
@@ -96,76 +90,81 @@ a user-assigned managed identity in Azure. Save its name which will be used late
9690
- [Create a role assignment](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal-managed-identity)
9791
to give the identity Contributor access to the Azure subscription where the workload cluster will be created.
9892
99-
- Before generating a workload cluster YAML configuration set the
93+
- Before generating a workload cluster YAML configuration, set the
10094
following environment variables.
101-
```bash
102-
export AZURE_SUBSCRIPTION_ID=<your-azure-subscription-id>
103-
# This is the client ID of the AAD app or user-assigned identity that you used to created the federated identity.
104-
export AZURE_CLIENT_ID=<your-azure-client-id>
105-
export AZURE_TENANT_ID=<your-azure-tenant-id>
106-
export AZURE_CONTROL_PLANE_MACHINE_TYPE="Standard_B2s"
107-
export AZURE_NODE_MACHINE_TYPE="Standard_B2s"
108-
export AZURE_LOCATION="eastus"
109-
110-
# Identity secret. Though these are not used in workload identity, we still
111-
# need to set them for the sake of generating the workload cluster YAML configuration
112-
export AZURE_CLUSTER_IDENTITY_SECRET_NAME="cluster-identity-secret"
113-
export CLUSTER_IDENTITY_NAME="cluster-identity"
114-
export AZURE_CLUSTER_IDENTITY_SECRET_NAMESPACE="default"
115-
```
95+
96+
```bash
97+
export AZURE_SUBSCRIPTION_ID=<your-azure-subscription-id>
98+
# This is the client ID of the AAD app or user-assigned identity that you used to created the federated identity.
99+
export AZURE_CLIENT_ID=<your-azure-client-id>
100+
export AZURE_TENANT_ID=<your-azure-tenant-id>
101+
export AZURE_CONTROL_PLANE_MACHINE_TYPE="Standard_B2s"
102+
export AZURE_NODE_MACHINE_TYPE="Standard_B2s"
103+
export AZURE_LOCATION="eastus"
104+
105+
# Identity secret. Though these are not used in workload identity, we still
106+
# need to set them for the sake of generating the workload cluster YAML configuration
107+
export AZURE_CLUSTER_IDENTITY_SECRET_NAME="cluster-identity-secret"
108+
export CLUSTER_IDENTITY_NAME="cluster-identity"
109+
export AZURE_CLUSTER_IDENTITY_SECRET_NAMESPACE="default"
110+
```
111+
116112
- Generate a workload cluster template using the following command.
117113
118-
```bash
119-
clusterctl generate cluster azwi-quickstart --kubernetes-version v1.27.3 --worker-machine-count=3 > azwi-quickstart.yaml
120-
```
114+
```bash
115+
clusterctl generate cluster azwi-quickstart --kubernetes-version v1.27.3 --worker-machine-count=3 > azwi-quickstart.yaml
116+
```
121117
122118
- Edit the generated `azwi-quickstart.yaml` to make the following changes for
123-
workload identity to the `AzureClusterIdentity` object.
119+
workload identity to the `AzureClusterIdentity` object:
120+
124121
- Change the type to `WorkloadIdentity`.
125122
- Remove the `clientSecret` spec.
126123
127-
The AzureClusterIdentity specification should look like the following.
128-
```yaml
129-
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
130-
kind: AzureClusterIdentity
131-
metadata:
132-
name: cluster-identity
133-
spec:
134-
type: WorkloadIdentity
135-
allowedNamespaces:
136-
list:
137-
- <cluster-namespace>
138-
tenantID: <your-tenant-id>
139-
clientID: <your-client-id>
140-
```
124+
The AzureClusterIdentity specification should look like the following.
125+
```yaml
126+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
127+
kind: AzureClusterIdentity
128+
metadata:
129+
name: cluster-identity
130+
spec:
131+
type: WorkloadIdentity
132+
allowedNamespaces:
133+
list:
134+
- <cluster-namespace>
135+
tenantID: <your-tenant-id>
136+
clientID: <your-client-id>
137+
```
141138
142139
- Change the `AzureMachineTemplate` for both control plane and worker to include user-assigned-identity by
143140
adding the following in its `spec`.
144-
```yaml
145-
identity: UserAssigned
146-
userAssignedIdentities:
147-
- providerID: /subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/${USER_ASSIGNED_IDENTITY_NAME}
148-
```
149-
A sample `AzureMahineTemplate` after the edit should look like the below:
150-
151-
```yaml
152-
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
153-
kind: AzureMachineTemplate
154-
metadata:
155-
name: ${CLUSTER_NAME}-md-0
156-
namespace: default
157-
spec:
158-
template:
159-
spec:
160-
osDisk:
161-
diskSizeGB: 128
162-
osType: Linux
163-
sshPublicKey: ${AZURE_SSH_PUBLIC_KEY_B64:=""}
164-
identity: UserAssigned
165-
userAssignedIdentities:
166-
- providerID: /subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/${USER_ASSIGNED_IDENTITY_NAME}
167-
vmSize: ${AZURE_NODE_MACHINE_TYPE}
168-
```
141+
142+
```yaml
143+
identity: UserAssigned
144+
userAssignedIdentities:
145+
- providerID: /subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/${USER_ASSIGNED_IDENTITY_NAME}
146+
```
147+
148+
A sample `AzureMachineTemplate` after the edit should look like the below:
149+
150+
```yaml
151+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
152+
kind: AzureMachineTemplate
153+
metadata:
154+
name: ${CLUSTER_NAME}-md-0
155+
namespace: default
156+
spec:
157+
template:
158+
spec:
159+
osDisk:
160+
diskSizeGB: 128
161+
osType: Linux
162+
sshPublicKey: ${AZURE_SSH_PUBLIC_KEY_B64:=""}
163+
identity: UserAssigned
164+
userAssignedIdentities:
165+
- providerID: /subscriptions/${AZURE_SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/${USER_ASSIGNED_IDENTITY_NAME}
166+
vmSize: ${AZURE_NODE_MACHINE_TYPE}
167+
```
169168
170169
- At this stage, you can apply this yaml to create a workload cluster.
171170

0 commit comments

Comments
 (0)