Skip to content

doc: refine workload identity doc #938

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andyzhangx merged 1 commit into from
May 17, 2023
Merged

doc: refine workload identity doc #938

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ This option does not depend on cloud provider config file, supports cross subscr
- [Basic usage](./deploy/example/e2e_usage.md)
- [NFSv3](./deploy/example/nfs)
- [fsGroupPolicy](./deploy/example/fsgroup)
- [Workload identity](./docs/workload-identity.md)

### Troubleshooting
- [CSI driver troubleshooting guide](./docs/csi-debug.md)
Expand Down
67 changes: 21 additions & 46 deletions docs/workload-identity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,14 @@
# How to Use workload identity with Blob CSI driver
# workload identity support
> Note:
> - supported version: v1.22.0
> - workload identity is supported on OpenShift, capz and other self-managed clusters
> - workload identity is NOT supported on AKS **managed** Blob CSI driver since the driver controller is managed by AKS control plane which is already using [managed identity](https://learn.microsoft.com/en-us/azure/aks/use-managed-identity) by default, it's not necessary to use workload identity for AKS managed Blob CSI driver.

## Prerequisites

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.
Before proceeding with the following steps, please ensure that you have completed the [Workload Identity installation guide](https://azure.github.io/azure-workload-identity/docs/installation.html). After completing the installation, you should have already installed the mutating admission webhook and obtained the OIDC issuer URL for your cluster.

After you finish the Installation guide, you should have already:

* installed the mutating admission webhook
* obtained your cluster’s OIDC issuer URL

## 1. Export environment variables
## 1. Set environment variables

```shell
export CLUSTER_NAME="<your cluster name>"
Expand All @@ -34,54 +33,40 @@ export SA_LIST=( "csi-blob-controller-sa" "csi-blob-node-sa" )
export NAMESPACE="kube-system"
```

## 2. Create Blob resource group

If you are using AKS, you can get the resource group where Blob storage class reside by running:

```shell
export AZURE_BLOB_RESOURCE_GROUP="$(az aks show --name $CLUSTER_NAME --resource-group $CLUSTER_RESOURCE_GROUP --query "nodeResourceGroup" -o tsv)"
```

You can also create resource group by yourself, but you must [specify the resource group](https://github.com/cvvz/blob-csi-driver/blob/workload_identity/docs/driver-parameters.md) in the storage class while using Blob CSI driver:
## 2. Create an AAD application or user-assigned managed identity and grant required permissions

```shell
az group create -n $AZURE_BLOB_RESOURCE_GROUP -l $LOCATION
```

## 3. Create an AAD application or user-assigned managed identity and grant required permissions

```shell
# create an AAD application if using Azure AD Application for this tutorial
# create an AAD application if you are using Azure AD Application
az ad sp create-for-rbac --name "${APPLICATION_NAME}"
```

```shell
# create a user-assigned managed identity if using user-assigned managed identity for this tutorial
# create a user-assigned managed identity if you are using user-assigned managed identity
az group create -n ${IDENTITY_RESOURCE_GROUP} -l $LOCATION
az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}"
```

Grant required permission to the AAD application or user-assigned managed identity, for simplicity, we just assign Contributor role to the resource group where Blob storage class reside:

If using Azure AD Application:
- if you are using Azure AD Application:

```shell
export APPLICATION_CLIENT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appId' -otsv)"
export AZURE_BLOB_RESOURCE_GROUP_ID="$(az group show -n $AZURE_BLOB_RESOURCE_GROUP --query 'id' -otsv)"
az role assignment create --assignee $APPLICATION_CLIENT_ID --role Contributor --scope $AZURE_BLOB_RESOURCE_GROUP_ID
```

if using user-assigned managed identity:
- if you are using user-assigned managed identity:

```shell
export USER_ASSIGNED_IDENTITY_OBJECT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}" --query 'principalId' -otsv)"
export AZURE_BLOB_RESOURCE_GROUP_ID="$(az group show -n $AZURE_BLOB_RESOURCE_GROUP --query 'id' -otsv)"
az role assignment create --assignee $USER_ASSIGNED_IDENTITY_OBJECT_ID --role Contributor --scope $AZURE_BLOB_RESOURCE_GROUP_ID
```

## 4. Establish federated identity credential between the identity and the Blob service account issuer & subject
## 3. Establish federated identity credential between the identity and the Blob service account issuer & subject

If using Azure AD Application:
- if you are using Azure AD Application:

```shell
# Get the object ID of the AAD application
Expand All @@ -105,7 +90,7 @@ az ad app federated-credential create --id ${APPLICATION_OBJECT_ID} --parameters
done
```

If using user-assigned managed identity:
- if you are using user-assigned managed identity:

```shell
for SERVICE_ACCOUNT_NAME in "${SA_LIST[@]}"
Expand All @@ -119,18 +104,10 @@ az identity federated-credential create \
done
```

## 5. Deploy Blob CSI Driver
## 4. Install CSI driver manually
> workload identity is NOT supported on AKS **managed** Blob CSI driver

Deploy storageclass:

```shell
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/blob-csi-driver/master/deploy/example/storageclass-blobfuse.yaml
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/blob-csi-driver/master/deploy/example/storageclass-blob-nfs.yaml
```

Deploy Blob CSI Driver

If using Azure AD Application:
- if you are using Azure AD Application:

```shell
export CLIENT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appId' -otsv)"
Expand All @@ -141,7 +118,7 @@ helm install blob-csi-driver charts/latest/blob-csi-driver \
--set workloadIdentity.tenantID=$TENANT_ID
```

If using user-assigned managed identity:
- if you are using user-assigned managed identity:

```shell
export CLIENT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${IDENTITY_RESOURCE_GROUP}" --query 'clientId' -otsv)"
Expand All @@ -152,11 +129,9 @@ helm install blob-csi-driver charts/latest/blob-csi-driver \
--set workloadIdentity.tenantID=$TENANT_ID
```

## 6. Deploy application using Blob CSI driver
## 5. Deploy application using CSI driver volume

```shell
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/blob-csi-driver/master/deploy/example/storageclass-blobfuse.yaml
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/blob-csi-driver/master/deploy/example/nfs/statefulset.yaml
kubectl create -f https://raw.githubusercontent.com/kubernetes-sigs/blob-csi-driver/master/deploy/example/deployment.yaml
```

Please make sure all the Pods are running.