Skip to content

Commit e2d3f30

Browse files
cvvzcvvz
committed
add docs
1 parent a094561 commit e2d3f30

File tree

1 file changed

+165
-0
lines changed

1 file changed

+165
-0
lines changed

‎docs/workload-identity.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# How to Use workload identity with Azurefile
2+
3+
## Prerequisites
4+
5+
This document is mainly refer to [Azure AD Workload Identity Quick Start](https://azure.github.io/azure-workload-identity/docs/quick-start.html). Please Complete the [Installation guide](https://azure.github.io/azure-workload-identity/docs/installation.html) before the following steps.
6+
7+
After you finish the Installation guide, you should have already:
8+
9+
* installed the mutating admission webhook
10+
* obtained your cluster’s OIDC issuer URL
11+
12+
## 1. Enable Azure Workload Identity Mutating Webhook injection to Pod in the `kube-system` namespace
13+
14+
Per [azure-workload-identity Known Issues](https://github.com/Azure/azure-workload-identity/blob/main/docs/book/src/known-issues.md#environment-variables-not-injected-into-pods-deployed-in-the-kube-system-namespace-in-an-aks-cluster), if you're deploying Azurefile in the `kube-system` namespace of an AKS cluster, add the `"admissions.enforcer/disabled": "true"` label or annotation in the [MutatingWebhookConfiguration](https://github.com/Azure/azure-workload-identity/blob/8644a217f09902fa1ac63e05cf04d9a3f3f1ebc3/deploy/azure-wi-webhook.yaml#L206-L235).
15+
16+
## 2. Export environment variables
17+
18+
```shell
19+
export CLUSTER_NAME="<your cluster name>"
20+
export CLUSTER_RESOURCE_GROUP="<cluster resource group name>"
21+
export LOCATION="<location>"
22+
export OIDC_ISSUER="<your cluster’s OIDC issuer URL>"
23+
24+
# [OPTIONAL] resource group where Azurefile storage account reside
25+
export AZURE_FILE_RESOURCE_GROUP="<resource group where Azurefile storage account reside>"
26+
27+
# environment variables for the AAD application
28+
# [OPTIONAL] Only set this if you're using a Azure AD Application as part of this tutorial
29+
export APPLICATION_NAME="<your application name>"
30+
31+
# environment variables for the user-assigned managed identity
32+
# [OPTIONAL] Only set this if you're using a user-assigned managed identity as part of this tutorial
33+
export USER_ASSIGNED_IDENTITY_NAME="<your user-assigned managed identity name>"
34+
export IDENTITY_RESOURCE_GROUP="<resource group where your user-assigned managed identity reside>"
35+
36+
# Azurefile CSI Driver Service Account and namespace
37+
export SA_LIST=( "csi-azurefile-controller-sa" "csi-azurefile-node-sa" )
38+
export NAMESPACE="kube-system"
39+
```
40+
41+
## 3. Create Azurefile resource group
42+
43+
If you are using AKS, you can get the resource group where Azurefile storage class reside by running:
44+
45+
```shell
46+
export AZURE_FILE_RESOURCE_GROUP="$(az aks show --name $CLUSTER_NAME --resource-group $CLUSTER_RESOURCE_GROUP --query "nodeResourceGroup" -o tsv)"
47+
```
48+
49+
You can also create resource group by yourself, but you must [specify the resource group](https://github.com/kubernetes-sigs/azurefile-csi-driver/blob/master/docs/driver-parameters.md#:~:text=current%20k8s%20cluster-,resourceGroup,No,-if%20empty%2C%20driver) in the storage class while using Azurefile.
50+
51+
```shell
52+
az group create -n $AZURE_FILE_RESOURCE_GROUP -l $LOCATION
53+
```
54+
55+
## 4. Create an AAD application or user-assigned managed identity and grant required permissions
56+
57+
```shell
58+
# create an AAD application if using Azure AD Application for this tutorial
59+
az ad sp create-for-rbac --name "${APPLICATION_NAME}"
60+
```
61+
62+
```shell
63+
# create a user-assigned managed identity if using user-assigned managed identity for this tutorial
64+
az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}"
65+
```
66+
67+
Grant required permission to the AAD application or user-assigned managed identity, for simplicity, we just assign Contributor role to the resource group where Azurefile storage class reside:
68+
69+
If using Azure AD Application:
70+
71+
```shell
72+
export APPLICATION_CLIENT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appId' -otsv)"
73+
export AZURE_FILE_RESOURCE_GROUP_ID="$(az group show -n $AZURE_FILE_RESOURCE_GROUP --query 'id' -otsv)"
74+
az role assignment create --assignee $APPLICATION_CLIENT_ID --role Contributor --scope $AZURE_FILE_RESOURCE_GROUP_ID
75+
```
76+
77+
if using user-assigned managed identity:
78+
79+
```shell
80+
export USER_ASSIGNED_IDENTITY_OBJECT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}" --query 'principalId' -otsv)"
81+
export AZURE_FILE_RESOURCE_GROUP_ID="$(az group show -n $AZURE_FILE_RESOURCE_GROUP --query 'id' -otsv)"
82+
az role assignment create --assignee $USER_ASSIGNED_IDENTITY_OBJECT_ID --role Contributor --scope $AZURE_FILE_RESOURCE_GROUP_ID
83+
```
84+
85+
## 5. Establish federated identity credential between the identity and the Azurefile service account issuer & subject
86+
87+
If using Azure AD Application:
88+
89+
```shell
90+
# Get the object ID of the AAD application
91+
export APPLICATION_OBJECT_ID="$(az ad app show --id ${APPLICATION_CLIENT_ID} --query id -otsv)"
92+
93+
# Add the federated identity credential:
94+
for SERVICE_ACCOUNT_NAME in "${SA_LIST[@]}"
95+
do
96+
cat <<EOF > params.json
97+
{
98+
"name": "${SERVICE_ACCOUNT_NAME}",
99+
"issuer": "${OIDC_ISSUER}",
100+
"subject": "system:serviceaccount:${NAMESPACE}:${SERVICE_ACCOUNT_NAME}",
101+
"description": "Kubernetes service account federated credential",
102+
"audiences": [
103+
"api://AzureADTokenExchange"
104+
]
105+
}
106+
EOF
107+
az ad app federated-credential create --id ${APPLICATION_OBJECT_ID} --parameters @params.json
108+
done
109+
```
110+
111+
If using user-assigned managed identity:
112+
113+
```shell
114+
for SERVICE_ACCOUNT_NAME in "${SA_LIST[@]}"
115+
do
116+
az identity federated-credential create \
117+
--name "${SERVICE_ACCOUNT_NAME}" \
118+
--identity-name "${USER_ASSIGNED_IDENTITY_NAME}" \
119+
--resource-group "${IDENTITY_RESOURCE_GROUP}" \
120+
--issuer "${OIDC_ISSUER}" \
121+
--subject system:serviceaccount:"${NAMESPACE}":"${SERVICE_ACCOUNT_NAME}"
122+
done
123+
```
124+
125+
## 6. Deploy Azurefile
126+
127+
Deploy storageclass:
128+
129+
```shell
130+
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/azurefile-csi-driver/master/deploy/example/storageclass-azurefile-csi.yaml
131+
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/azurefile-csi-driver/master/deploy/example/storageclass-azurefile-nfs.yaml
132+
```
133+
134+
Deploy Azurefile(If you are using AKS, please disable the managed Azurefile CSI driver by `--disable-file-driver` first)
135+
136+
If using Azure AD Application:
137+
138+
```shell
139+
export CLIENT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appId' -otsv)"
140+
export TENANT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appOwnerOrganizationId' -otsv)"
141+
helm install azurefile-csi-driver charts/latest/azurefile-csi-driver \
142+
--namespace $NAMESPACE \
143+
--set workloadIdentity.clientID=$CLIENT_ID
144+
--set workloadIdentity.tenantID=$TENANT_ID
145+
```
146+
147+
If using user-assigned managed identity:
148+
149+
```shell
150+
export CLIENT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}" --query 'clientId' -otsv)"
151+
export TENANT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}" --query 'tenantId' -otsv)"
152+
helm install azurefile-csi-driver charts/latest/azurefile-csi-driver \
153+
--namespace $NAMESPACE \
154+
--set workloadIdentity.clientID=$CLIENT_ID
155+
--set workloadIdentity.tenantID=$TENANT_ID
156+
```
157+
158+
## 7. Deploy application using Azurefile
159+
160+
```shell
161+
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/azurefile-csi-driver/master/deploy/example/nfs/statefulset.yaml
162+
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/azurefile-csi-driver/master/deploy/example/deployment.yaml
163+
```
164+
165+
Please make sure all the Pods are running.

0 commit comments

Comments
 (0)