OCPBUGS-55260#Add static provisioning content for Azure File

modules/persistent-storage-csi-azure-file-static-provisioning-procedure.adoc

@@ -0,0 +1,122 @@
+// Module included in the following assemblies:
+//
+// * storage/container_storage_interface/persistent_storage-csi-azure-file.adoc
+//
+:_mod-docs-content-type: PROCEDURE
+[id="persistent-storage-csi-azure-file-static-provisioning-procedure_{context}"]
+= Static provisioning for Azure File
+
+For static provisioning, cluster administrators create persistent volumes (PVs) that define the details of the real storage. Cluster users can then create persistent volume claims (PVCs) that consume these PVs.
+
+.Prerequisites
+* Access to an {product-title} cluster with administrator rights
+
+.Procedure
+To use static provisioning for Azure File:
+
+. If you have not yet created a secret for the Azure storage account, create it now:
++
+This secret must contain the Azure Storage Account name and key with the following very specific format with two key-value pairs:
+
+* `azurestorageaccountname`: <storage_account_name>
+* `azurestorageaccountkey`: <account_key>
++
+To create a secret named _azure-secret_, run the following command:
++
+[source,terminal]
+----
+oc create secret generic azure-secret  -n <namespace_name> --type=Opaque --from-literal=azurestorageaccountname="<storage_account_name>" --from-literal=azurestorageaccountkey="<account_key>" <1> <2>
+----
+<1> Set `<namespace_name>` to the namespace where the PV is consumed.
+<2> Provide your values for `<storage_account_name>` and `<account_key>`.
+
+. Create a PV by using the following example YAML file:
++
+.Example PV YAML file
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  annotations:
+    pv.kubernetes.io/provisioned-by: file.csi.azure.com
+  name: pv-azurefile
+spec:
+  capacity:
+    storage: 5Gi <1>
+  accessModes:
+    - ReadWriteMany <2>
+  persistentVolumeReclaimPolicy: Retain <3>
+  storageClassName: <sc-name> <4>
+  mountOptions:
+    - dir_mode=0777  <5>
+    - file_mode=0777
+    - uid=0
+    - gid=0
+    - cache=strict  <6>
+    - nosharesock  <7> 
+    - actimeo=30  <8> 
+    - nobrl  <9>
+  csi:
+    driver: file.csi.azure.com
+    volumeHandle: "{resource-group-name}#{account-name}#{file-share-name}" <10>
+    volumeAttributes:
+      shareName: EXISTING_FILE_SHARE_NAME  <11> 
+    nodeStageSecretRef:
+      name: azure-secret <12>
+      namespace: <my-namespace> <13>
+----
+<1> Volume size.
+<2> Access mode. Defines the read-write and mount permissions. For more information, under _Additional Resources_, see _Access modes_.
+<3> Reclaim policy. Tells the cluster what to do with the volume after it is released. Accepted values are `Retain`, `Recycle`, or `Delete`.
+<4> Storage class name. This name is used by the PVC to bind to this specific PV. For static provisioning, a `StorageClass` object does not need to exist, but the name in the PV and PVC must match.
+<5> Modify this permission if you want to enhance the security.
+<6> Cache mode. Accepted values are `none`, `strict`, and `loose`. The default is `strict`.
+<7> Use to reduce the probability of a reconnect race.
+<8> The time (in seconds) that the CIFS client caches attributes of a file or directory before it requests attribute information from a server. 
+<9> Disables sending byte range lock requests to the server, and for applications which have challenges with POSIX locks.
+<10> Ensure that `volumeHandle` is unique across the cluster. The `resource-group-name` is the Azure resource group where the storage account resides. 
+<11> File share name. Use only the file share name; do not use full path.
+<12> Provide the name of the secret created in step 1 of this procedure. In this example, it is _azure-secret_.
+<13> The namespace that the secret was created in. This must be the namespace where the PV is consumed.
+
+. Create a PVC that references the PV using the following example file:
++
+.Example PVC YAML file
+[source,yaml]
+----
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: <pvc-name> <1>
+  namespace: <my-namespace> <2>
+spec:
+  volumeName: pv-azurefile <3>
+  storageClassName: <sc-name> <4>
+  accessModes:
+    - ReadWriteMany <5>
+  resources:
+    requests:
+      storage: 5Gi <6>
+----
+<1> PVC name.
+<2> Namespace for the PVC.
+<3> The name of the PV that you created in the previous step.
+<4> Storage class name. This name is used by the PVC to bind to this specific PV. For static provisioning, a `StorageClass` object does not need to exist, but the name in the PV and PVC must match.
+<5> Access mode. Defines the requested read-write access for the PVC. Claims use the same conventions as volumes when requesting storage with specific access modes. For more information, under _Additional Resources_, see _Access modes_.
+<6> PVC size.
+
+. Ensure that the PVC is created and in `Bound` status after a while by running the following command:
++
+[source,terminal]
+----
+$ oc get pvc <pvc-name> <1>
+----
+<1> The name of your PVC.
++
+.Example output
+[source,terminal]
+----
+NAME       STATUS    VOLUME         CAPACITY   ACCESS MODES   STORAGECLASS   AGE
+pvc-name   Bound     pv-azurefile   5Gi        ReadWriteMany  my-sc          7m2s
+----

storage/container_storage_interface/persistent-storage-csi-azure-file.adoc

@@ -35,6 +35,10 @@ include::modules/persistent-storage-csi-azure-file-cross-sub-dynamic-provisionin
 
 include::modules/persistent-storage-csi-azure-file-cross-sub-dynamic-pre-provisioning-pv-pvc-procedure.adoc[leveloffset=+2]
 
+include::modules/persistent-storage-csi-azure-file-static-provisioning-procedure.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
 .Additional resources
 * xref:../../storage/persistent_storage/persistent-storage-azure-file.adoc#persistent-storage-using-azure-file[Persistent storage using Azure File]
 * xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes]
+* xref:../../storage/understanding-persistent-storage.adoc#pv-access-modes_understanding-persistent-storage[Access modes]