From ad5f3f4cff921cd25f062acffba4565a48d75ac2 Mon Sep 17 00:00:00 2001 From: Christian Huffman Date: Fri, 27 Sep 2019 19:36:35 -0400 Subject: [PATCH] OSDOCS-702: Included instructions for Azure File. --- _topic_map.yml | 2 + ...ynamic-provisioning-available-plugins.adoc | 13 +++- ...ic-provisioning-azure-disk-definition.adoc | 24 +++--- ...ic-provisioning-azure-file-definition.adoc | 58 +++++++++++++++ ...age-persistent-storage-azure-file-pod.adoc | 37 ++++++++++ ...storage-persistent-storage-azure-file.adoc | 73 +++++++++++++++++++ modules/storage-persistent-storage-pv.adoc | 8 +- storage/dynamic-provisioning.adoc | 5 +- .../persistent-storage-azure-file.adoc | 33 +++++++++ 9 files changed, 232 insertions(+), 21 deletions(-) create mode 100644 modules/dynamic-provisioning-azure-file-definition.adoc create mode 100644 modules/storage-persistent-storage-azure-file-pod.adoc create mode 100644 modules/storage-persistent-storage-azure-file.adoc create mode 100644 storage/persistent-storage/persistent-storage-azure-file.adoc diff --git a/_topic_map.yml b/_topic_map.yml index 8181734bab..78585e64be 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -364,6 +364,8 @@ Topics: File: persistent-storage-aws - Name: Persistent storage using Azure Disk File: persistent-storage-azure + - Name: Persistent storage using Azure File + File: persistent-storage-azure-file - Name: Persistent storage using Fibre Channel File: persistent-storage-fibre - Name: Persistent storage using GCE Persistent Disk diff --git a/modules/dynamic-provisioning-available-plugins.adoc b/modules/dynamic-provisioning-available-plugins.adoc index 7e3bbddeec..93ec434809 100644 --- a/modules/dynamic-provisioning-available-plugins.adoc +++ b/modules/dynamic-provisioning-available-plugins.adoc @@ -32,6 +32,15 @@ where `` and `` are unique per cluster. |Dynamic provisioning is accomplished through the EFS provisioner pod and not through a provisioner plug-in. +|Azure Disk +|`kubernetes.io/azure-disk` +| + +|Azure File +|`kubernetes.io/azure-file` +|The `persistent-volume-binder` ServiceAccount requires permissions to create +and get Secrets to store the Azure storage account and keys. + |GCE Persistent Disk (gcePD) |`kubernetes.io/gce-pd` |In multi-zone configurations, it is advisable to run one {product-title} @@ -54,10 +63,6 @@ no node in the current cluster exists. //|`kubernetes.io/vsphere-volume` //| -//|Azure Disk -//|`kubernetes.io/azure-disk` -//| - //|HPE Nimble Storage //|`hpe.com/nimble` //|Dynamic provisioning of HPE Nimble Storage resources using the diff --git a/modules/dynamic-provisioning-azure-disk-definition.adoc b/modules/dynamic-provisioning-azure-disk-definition.adoc index 4078c364da..eb518cf8cc 100644 --- a/modules/dynamic-provisioning-azure-disk-definition.adoc +++ b/modules/dynamic-provisioning-azure-disk-definition.adoc @@ -18,25 +18,25 @@ parameters: storageaccounttype: Standard_LRS <2> kind: Dedicated <3> ---- -<1> Azure storage account name. This must reside in the same resource -group as the cluster. If a storage account is specified, the `location` -is ignored. If a storage account is not specified, a new storage -account gets created in the same resource group as the cluster. If you +<1> Azure storage account name. This must reside in the same resource +group as the cluster. If a storage account is specified, the `location` +is ignored. If a storage account is not specified, a new storage +account gets created in the same resource group as the cluster. If you are specifying a `storageAccount`, the value for `kind` must be `Dedicated`. -<2> Azure storage account SKU tier. Default is empty. Note that Premium -VMs can attach both _Standard_LRS_ and _Premium_LRS_ disks, Standard VMs -can only attach _Standard_LRS_ disks, Managed VMs can only attach +<2> Azure storage account SKU tier. Default is empty. Note that Premium +VMs can attach both `Standard_LRS` and `Premium_LRS` disks, Standard VMs +can only attach `Standard_LRS` disks, Managed VMs can only attach managed disks, and unmanaged VMs can only attach unmanaged disks. <3> Possible values are `Shared` (default), `Dedicated`, and `Managed`. + -.. If `kind` is set to `Shared`, Azure creates all unmanaged disks in a +.. If `kind` is set to `Shared`, Azure creates all unmanaged disks in a few shared storage accounts in the same resource group as the cluster. .. If `kind` is set to `Managed`, Azure creates new managed disks. -.. If `kind` is set to `Dedicated` and a `storageAccount` is specified, -Azure uses the specified storage account for the new unmanaged disk in +.. If `kind` is set to `Dedicated` and a `storageAccount` is specified, +Azure uses the specified storage account for the new unmanaged disk in the same resource group as the cluster. For this to work: * The specified storage account must be in the same region. * Azure Cloud Provider must have a write access to the storage account. -.. If `kind` is set to `Dedicated` and a `storageAccount` is not -specified, Azure creates a new dedicated storage account for the new +.. If `kind` is set to `Dedicated` and a `storageAccount` is not +specified, Azure creates a new dedicated storage account for the new unmanaged disk in the same resource group as the cluster. diff --git a/modules/dynamic-provisioning-azure-file-definition.adoc b/modules/dynamic-provisioning-azure-file-definition.adoc new file mode 100644 index 0000000000..c7dc7682bd --- /dev/null +++ b/modules/dynamic-provisioning-azure-file-definition.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies +// +// * storage/dynamic-provisioning.adoc + +[id="azure-file-definition_{context}"] += Azure File object definition + +The Azure File StorageClass uses secrets to store the Azure storage account name +and the storage account key that are required to create an Azure Files share. These +permissions are created as part of the following procedure. + +.Procedure + +. Define a ClusterRole that allows access to create and view secrets: ++ +[source,yaml] +---- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: +# name: system:azure-cloud-provider + name: <1> +rules: +- apiGroups: [''] + resources: ['secrets'] + verbs: ['get','create'] +---- +<1> The name of the ClusterRole to view and create secrets. + +. Add the ClusterRole to the ServiceAccount: ++ +---- +$ oc adm policy add-cluster-role-to-user system:serviceaccount:kube-system:persistent-volume-binder +---- + +. Create the Azure File StorageClass: ++ +[source,yaml] +---- +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: <1> +provisioner: kubernetes.io/azure-file +parameters: + location: eastus <2> + skuName: Standard_LRS <3> + storageAccount: <4> +reclaimPolicy: Delete +volumeBindingMode: Immediate +---- +<1> Name of the StorageClass. The PersistentVolumeClaim uses this StorageClass for provisioning the associated PersistentVolumes. +<2> Location of the Azure storage account, such as `eastus`. Default is empty, meaning that a new Azure storage account will be created in the {product-title} cluster's location. +<3> SKU tier of the Azure storage account, such as `Standard_LRS`. Default is empty, meaning that a new Azure storage account will be created with the `Standard_LRS` SKU. +<4> Name of the Azure storage account. If a storage account is provided, then +`skuName` and `location` are ignored. If no storage account is provided, then +the StorageClass searches for any storage account that is associated with the +resource group for any accounts that match the defined `skuName` and `location`. diff --git a/modules/storage-persistent-storage-azure-file-pod.adoc b/modules/storage-persistent-storage-azure-file-pod.adoc new file mode 100644 index 0000000000..98c1736f49 --- /dev/null +++ b/modules/storage-persistent-storage-azure-file-pod.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * storage/persistent-storage/persistent-storage-azure-file.adoc + +[id="create-azure-file-pod_{context}"] += Mount the Azure File share in a Pod + +After the PersistentVolumeClaim has been created, it can be used inside by an application. The following example demonstrates mounting this share inside of a Pod. + +.Prerequisites + +* A PersistentVolumeClaim exists that is mapped to the underlying Azure File share. + +.Procedure + +* Create a Pod that mounts the existing PersistentVolumeClaim: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: pod-name <1> +spec: + containers: + ... + volumeMounts: + - mountPath: "/data" <2> + name: azure-file-share + volumes: + - name: azure-file-share + persistentVolumeClaim: + claimName: claim1 <4> +---- +<1> The name of the Pod. +<2> The path to mount the Azure File share inside the Pod. +<3> The name of the PersistentVolumeClaim that has been previously created. diff --git a/modules/storage-persistent-storage-azure-file.adoc b/modules/storage-persistent-storage-azure-file.adoc new file mode 100644 index 0000000000..50805fa889 --- /dev/null +++ b/modules/storage-persistent-storage-azure-file.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * storage/persistent-storage/persistent-storage-azure-file.adoc + +[id="create-azure-file-secret_{context}"] += Create the Azure File share PersistentVolumeClaim + +To create the PersistentVolumeClaim, you must first define a Secret that contains the Azure account and key. This Secret is used in the PersistentVolume definition, and will be referenced by the PersistentVolumeClaim for use in applications. + +.Prerequisites + +* An Azure File share exists. +* The credentials to access this share, specifically the storage account and +key, are available. + +.Procedure + +. Create a Secret that contains the Azure File credentials: ++ +---- +$ oc create secret generic --from-literal=azurestorageaccountname= \ <1> + --from-literal=azurestorageaccountkey= <2> +---- +<1> The Azure File storage account name. +<2> The Azure File storage account key. + +. Create a PersistentVolume that references the Secret you created: ++ +[source,yaml] +---- +apiVersion: "v1" +kind: "PersistentVolume" +metadata: + name: "pv0001" <1> +spec: + capacity: + storage: "5Gi" <2> + accessModes: + - "ReadWriteOnce" + storageClassName: azure-file-sc + azureFile: + secretName: <3> + shareName: share-1 <4> + readOnly: false +---- +<1> The name of the PersistentVolume. +<2> The size of this PersistentVolume. +<3> The name of the Secret that contains the Azure File share credentials. +<4> The name of the Azure File share. + +. Create a PersistentVolumeClaim that maps to the PersistentVolume you created: ++ +[source,yaml] +---- +apiVersion: "v1" +kind: "PersistentVolumeClaim" +metadata: + name: "claim1" <1> +spec: + accessModes: + - "ReadWriteOnce" + resources: + requests: + storage: "5Gi" <2> + storageClassName: azure-file-sc <3> + volumeName: "pv0001" <4> +---- +<1> The name of the PersistentVolumeClaim. +<2> The size of this PersistentVolumeClaim. +<3> The name of the StorageClass that is used to provision the PersistentVolume. +Specify the StorageClass used in the PersistentVolume definition. +<4> The name of the existing PersistentVolume that references the +Azure File share. diff --git a/modules/storage-persistent-storage-pv.adoc b/modules/storage-persistent-storage-pv.adoc index 965a8a0a47..5989bca6ee 100644 --- a/modules/storage-persistent-storage-pv.adoc +++ b/modules/storage-persistent-storage-pv.adoc @@ -40,6 +40,8 @@ once it is released. // - Ceph RBD // - OpenStack Cinder - AWS Elastic Block Store (EBS) +- Azure Disk +- Azure File // - GCE Persistent Disk - Azure Disk ifdef::openshift-enterprise,openshift-origin[] @@ -47,8 +49,6 @@ ifdef::openshift-enterprise,openshift-origin[] - HostPath - iSCSI - NFS -// - Azure Disk -// - Azure File - VMware vSphere // - Local endif::[] @@ -129,8 +129,8 @@ the Pods that use these volumes are deleted. |=== |Volume Plug-in |ReadWriteOnce |ReadOnlyMany |ReadWriteMany |AWS EBS | ✅ | - | - -//|Azure File | ✅ | ✅ | ✅ -//|Azure Disk | ✅ | - | - +|Azure File | ✅ | ✅ | ✅ +|Azure Disk | ✅ | - | - //|Ceph RBD | ✅ | ✅ | - //|CephFS | ✅ | ✅ | ✅ |Fibre Channel | ✅ | ✅ | - diff --git a/storage/dynamic-provisioning.adoc b/storage/dynamic-provisioning.adoc index 7ce3e13e01..9adea50306 100644 --- a/storage/dynamic-provisioning.adoc +++ b/storage/dynamic-provisioning.adoc @@ -18,6 +18,10 @@ include::modules/dynamic-provisioning-annotations.adoc[leveloffset=+2] include::modules/dynamic-provisioning-aws-definition.adoc[leveloffset=+2] +include::modules/dynamic-provisioning-azure-disk-definition.adoc[leveloffset=+2] + +include::modules/dynamic-provisioning-azure-file-definition.adoc[leveloffset=+2] + // include::modules/dynamic-provisioning-gce-definition.adoc[leveloffset=+2] // include::modules/dynamic-provisioning-gluster-definition.adoc[leveloffset=+2] @@ -26,6 +30,5 @@ include::modules/dynamic-provisioning-aws-definition.adoc[leveloffset=+2] // include::modules/dynamic-provisioning-vsphere-definition.adoc[leveloffset=+2] -// include::modules/dynamic-provisioning-azure-disk-definition.adoc[leveloffset=+2] include::modules/dynamic-provisioning-change-default-class.adoc[leveloffset=+1] diff --git a/storage/persistent-storage/persistent-storage-azure-file.adoc b/storage/persistent-storage/persistent-storage-azure-file.adoc new file mode 100644 index 0000000000..e0ea089bd0 --- /dev/null +++ b/storage/persistent-storage/persistent-storage-azure-file.adoc @@ -0,0 +1,33 @@ +[id="persistent-storage-using-azure-file"] += Persistent storage using Azure File +include::modules/common-attributes.adoc[] +:context: persistent-storage-azure-file +toc::[] + +{product-title} supports Microsoft Azure File volumes. You can +provision your {product-title} cluster with persistent storage using Azure. +Some familiarity with Kubernetes and Azure is assumed. + +The Kubernetes persistent volume framework allows administrators to provision a +cluster with persistent storage and gives users a way to request those +resources without having any knowledge of the underlying infrastructure. +Azure File volumes can be provisioned dynamically. + +PersistentVolumes are not bound to a single project or namespace; they can be +shared across the {product-title} cluster. +PersistentVolumeClaims are specific to a project or namespace and can be +requested by users for use in applications. + +[IMPORTANT] +==== +High availability of storage in the infrastructure is left to the underlying +storage provider. +==== + +.Additional references + +* link:https://azure.microsoft.com/en-us/services/storage/files/[Azure Files] + +include::modules/storage-persistent-storage-azure-file.adoc[leveloffset=+1] + +include::modules/storage-persistent-storage-azure-file-pod.adoc[leveloffset=+1]