Merge pull request #265 from andyzhangx/pv-parameters-doc

doc: refine PV parameters doc

Author: andyzhangx

deploy/example/pv-blobfuse-csi.yaml

@@ -17,8 +17,9 @@ spec:
     readOnly: false
     volumeHandle: uniqe-volumeid  # make sure this volumeid is unique in the cluster
     volumeAttributes:
+      resourceGroup: EXISTING_RESOURCE_GROUP_NAME
+      storageAccount: EXISTING_STORAGE_ACCOUNT_NAME
       containerName: EXISTING_CONTAINER_NAME
-      server: SERVER_ADDRESS  # optional, provide a new address to replace default "accountname.blob.core.windows.net"
     nodeStageSecretRef:
       name: azure-secret
       namespace: default

deploy/example/pv-blobfuse-nfs.yaml

@@ -0,0 +1,20 @@
+---
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: pv-blob
+spec:
+  capacity:
+    storage: 10Gi
+  accessModes:
+    - ReadWriteMany
+  persistentVolumeReclaimPolicy: Retain  # "Delete" is not supported in static provisioning
+  csi:
+    driver: blob.csi.azure.com
+    readOnly: false
+    volumeHandle: uniqe-volumeid  # make sure this volumeid is unique in the cluster
+    volumeAttributes:
+      resourceGroup: EXISTING_RESOURCE_GROUP_NAME
+      storageAccount: EXISTING_STORAGE_ACCOUNT_NAME
+      containerName: EXISTING_CONTAINER_NAME
+      protocol: nfs

docs/driver-parameters.md

@@ -6,8 +6,6 @@
  
   > [blobfuse mountOptions example](../deploy/example/storageclass-blobfuse-mountoptions.yaml)
 
-  > [blobfuse Managed Identity and Service Principal Name auth example](../deploy/example/storageclass-blobfuse-msi.yaml)
-
   > [nfs example](../deploy/example/storageclass-blob-nfs.yaml)
 
 Name | Meaning | Example | Mandatory | Default value
@@ -28,15 +26,39 @@ Blobfuse driver does not honor `fsGroup` securityContext setting, instead user c
 ### Static Provisioning(bring your own storage container)
   > [blobfuse example](../deploy/example/pv-blobfuse-csi.yaml)
 
-  > [blobfuse key vault example](../deploy/example/keyvault/pv-blobfuse-csi-keyvault.yaml)
+  > [nfs example](../deploy/example/pv-blobfuse-nfs.yaml)
+
+  > [blobfuse read account key or SAS token from key vault example](../deploy/example/keyvault/pv-blobfuse-csi-keyvault.yaml)
+
+  > [blobfuse Managed Identity and Service Principal Name auth example](../deploy/example/pv-blobfuse-auth.yaml)
 
 Name | Meaning | Available Value | Mandatory | Default value
 --- | --- | --- | --- | ---
+volumeAttributes.resourceGroup | Azure resource group name | existing resource group name | No | if empty, driver will use the same resource group name as current k8s cluster
+volumeAttributes.storageAccount | existing storage account name | existing storage account name | Yes |
 volumeAttributes.containerName | existing container name | existing container name | Yes |
-volumeAttributes.storageAccountName | existing storage account name | existing storage account name | Yes |
 volumeAttributes.protocol | specify blobfuse mount or NFSv3 mount | `fuse`, `nfs` | No | `fuse`
+nodeStageSecretRef.name | secret name that stores(check below examples):<br>`azurestorageaccountkey`<br>`azurestorageaccountsastoken`<br>`msisecret`<br>`azurestoragespnclientsecret` | existing Kubernetes secret name |  No  |
+nodeStageSecretRef.namespace | namespace where the secret is | k8s namespace  |  Yes  |
+--- | **Following parameters are only for feature: blobfuse [Managed Identity and Service Principal Name auth](https://github.com/Azure/azure-storage-fuse#environment-variables)** | --- | --- |
+volumeAttributes.AzureStorageAuthType | Authentication Type | `Key`, `SAS`, `MSI`, `SPN` | No | `Key`
+volumeAttributes.AzureStorageIdentityClientID | Identity Client ID |  | No |
+volumeAttributes.AzureStorageIdentityObjectID | Identity Object ID |  | No |
+volumeAttributes.AzureStorageIdentityResourceID | Identity Resource ID |  | No |
+volumeAttributes.MSIEndpoint | MSI Endpoint |  | No |
+volumeAttributes.AzureStorageSPNClientID | SPN Client ID |  | No |
+volumeAttributes.AzureStorageSPNTenantID | SPN Tenant ID |  | No |
+volumeAttributes.AzureStorageAADEndpoint | AADEndpoint |  | No |
+--- | **Following parameters are only for feature: blobfuse read account key or SAS token from key vault** | --- | --- |
 volumeAttributes.keyVaultURL | Azure Key Vault DNS name | existing Azure Key Vault DNS name | No |
 volumeAttributes.keyVaultSecretName | Azure Key Vault secret name | existing Azure Key Vault secret name | No |
 volumeAttributes.keyVaultSecretVersion | Azure Key Vault secret version | existing version | No |if empty, driver will use "current version"
-nodeStageSecretRef.name | secret name that stores storage account name and key(or sastoken) | existing Kubernetes secret name |  No  |
-nodeStageSecretRef.namespace | namespace where the secret is | k8s namespace  |  Yes  |
+
+
+ - create a Kubernetes secret for `nodeStageSecretRef.name`
+ ```console
+kubectl create secret generic azure-secret --from-literal azurestorageaccountkey="xxx" --type=Opaque
+kubectl create secret generic azure-secret --from-literal azurestorageaccountsastoken="xxx" --type=Opaque
+kubectl create secret generic azure-secret --from-literal msisecret="xxx" --type=Opaque
+kubectl create secret generic azure-secret --from-literal azurestoragespnclientsecret="xxx" --type=Opaque
+ ```

pkg/blob/blob.go

@@ -40,33 +40,39 @@ import (
 
 const (
 	// DriverName holds the name of the csi-driver
-	DriverName               = "blob.csi.azure.com"
-	separator                = "#"
-	volumeIDTemplate         = "%s#%s#%s"
-	secretNameTemplate       = "azure-storage-account-%s-secret"
-	fileMode                 = "file_mode"
-	dirMode                  = "dir_mode"
-	vers                     = "vers"
-	defaultFileMode          = "0777"
-	defaultDirMode           = "0777"
-	defaultVers              = "3.0"
-	serverNameField          = "server"
-	tagsField                = "tags"
-	protocolField            = "protocol"
-	storageAccountField      = "storageaccount"
-	storageAccountTypeField  = "storageaccounttype"
-	skuNameField             = "skuname"
-	resourceGroupField       = "resourcegroup"
-	locationField            = "location"
-	secretNamespaceField     = "secretnamespace"
-	containerNameField       = "containername"
-	storeAccountKeyField     = "storeaccountkey"
-	storeAccountKeyFalse     = "false"
-	defaultSecretAccountName = "azurestorageaccountname"
-	defaultSecretAccountKey  = "azurestorageaccountkey"
-	defaultSecretNamespace   = "default"
-	fuse                     = "fuse"
-	nfs                      = "nfs"
+	DriverName                 = "blob.csi.azure.com"
+	separator                  = "#"
+	volumeIDTemplate           = "%s#%s#%s"
+	secretNameTemplate         = "azure-storage-account-%s-secret"
+	fileMode                   = "file_mode"
+	dirMode                    = "dir_mode"
+	vers                       = "vers"
+	defaultFileMode            = "0777"
+	defaultDirMode             = "0777"
+	defaultVers                = "3.0"
+	serverNameField            = "server"
+	tagsField                  = "tags"
+	protocolField              = "protocol"
+	accountNameField           = "accountname"
+	accountKeyField            = "accountkey"
+	storageAccountField        = "storageaccount"
+	storageAccountTypeField    = "storageaccounttype"
+	skuNameField               = "skuname"
+	resourceGroupField         = "resourcegroup"
+	locationField              = "location"
+	secretNamespaceField       = "secretnamespace"
+	containerNameField         = "containername"
+	storeAccountKeyField       = "storeaccountkey"
+	keyVaultURLField           = "keyvaulturl"
+	keyVaultSecretNameField    = "keyvaultsecretname"
+	keyVaultSecretVersionField = "keyvaultsecretversion"
+	storageAccountNameField    = "storageaccountname"
+	storeAccountKeyFalse       = "false"
+	defaultSecretAccountName   = "azurestorageaccountname"
+	defaultSecretAccountKey    = "azurestorageaccountkey"
+	defaultSecretNamespace     = "default"
+	fuse                       = "fuse"
+	nfs                        = "nfs"
 
 	// See https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata#container-names
 	containerNameMinLength = 3
@@ -263,15 +269,15 @@ func (d *Driver) GetAuthEnv(ctx context.Context, volumeID, protocol string, attr
 		switch strings.ToLower(k) {
 		case containerNameField:
 			containerName = v
-		case "keyvaulturl":
+		case keyVaultURLField:
 			keyVaultURL = v
-		case "keyvaultsecretname":
+		case keyVaultSecretNameField:
 			keyVaultSecretName = v
-		case "keyvaultsecretversion":
+		case keyVaultSecretVersionField:
 			keyVaultSecretVersion = v
 		case storageAccountField:
 			accountName = v
-		case "storageaccountname": // for compatibility
+		case storageAccountNameField: // for compatibility
 			accountName = v
 		case "azurestorageauthtype":
 			authEnv = append(authEnv, "AZURE_STORAGE_AUTH_TYPE="+v)
@@ -334,13 +340,13 @@ func (d *Driver) GetAuthEnv(ctx context.Context, volumeID, protocol string, attr
 		} else {
 			for k, v := range secrets {
 				switch strings.ToLower(k) {
-				case "accountname":
+				case accountNameField:
 					accountName = v
-				case "azurestorageaccountname": // for compatibility with built-in blobfuse plugin
+				case defaultSecretAccountName: // for compatibility with built-in blobfuse plugin
 					accountName = v
-				case "accountkey":
+				case accountKeyField:
 					accountKey = v
-				case "azurestorageaccountkey": // for compatibility with built-in blobfuse plugin
+				case defaultSecretAccountKey: // for compatibility with built-in blobfuse plugin
 					accountKey = v
 				case "azurestorageaccountsastoken":
 					accountSasToken = v
@@ -368,7 +374,7 @@ func (d *Driver) GetAuthEnv(ctx context.Context, volumeID, protocol string, attr
 	return accountName, containerName, authEnv, err
 }
 
-// GetStorageAccountAndContainer: get storage account and container info
+// GetStorageAccountAndContainer get storage account and container info
 // returns <accountName, accountKey, accountSasToken, containerName>
 // only for e2e testing
 func (d *Driver) GetStorageAccountAndContainer(ctx context.Context, volumeID string, attrib, secrets map[string]string) (string, string, string, string, error) {
@@ -390,15 +396,15 @@ func (d *Driver) GetStorageAccountAndContainer(ctx context.Context, volumeID str
 		switch strings.ToLower(k) {
 		case containerNameField:
 			containerName = v
-		case "keyvaulturl":
+		case keyVaultURLField:
 			keyVaultURL = v
-		case "keyvaultsecretname":
+		case keyVaultSecretNameField:
 			keyVaultSecretName = v
-		case "keyvaultsecretversion":
+		case keyVaultSecretVersionField:
 			keyVaultSecretVersion = v
 		case storageAccountField:
 			accountName = v
-		case "storageaccountname":
+		case storageAccountNameField: // for compatibility
 			accountName = v
 		}
 	}
@@ -479,22 +485,22 @@ func getStorageAccount(secrets map[string]string) (string, string, error) {
 	var accountName, accountKey string
 	for k, v := range secrets {
 		switch strings.ToLower(k) {
-		case "accountname":
+		case accountNameField:
 			accountName = v
-		case "azurestorageaccountname": // for compatibility with built-in azurefile plugin
+		case defaultSecretAccountName: // for compatibility with built-in azurefile plugin
 			accountName = v
-		case "accountkey":
+		case accountKeyField:
 			accountKey = v
-		case "azurestorageaccountkey": // for compatibility with built-in azurefile plugin
+		case defaultSecretAccountKey: // for compatibility with built-in azurefile plugin
 			accountKey = v
 		}
 	}
 
 	if accountName == "" {
-		return "", "", fmt.Errorf("could not find accountname or azurestorageaccountname field secrets(%v)", secrets)
+		return accountName, accountKey, fmt.Errorf("could not find %s or %s field secrets(%v)", accountNameField, defaultSecretAccountName, secrets)
 	}
 	if accountKey == "" {
-		return "", "", fmt.Errorf("could not find accountkey or azurestorageaccountkey field in secrets(%v)", secrets)
+		return accountName, accountKey, fmt.Errorf("could not find %s or %s field in secrets(%v)", accountKeyField, defaultSecretAccountKey, secrets)
 	}
 
 	klog.V(4).Infof("got storage account(%s) from secret", accountName)