diff --git a/_topic_map.yml b/_topic_map.yml index 80bbac4fca..839f6f0b29 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -874,6 +874,8 @@ Topics: File: persistent-storage-csi-cloning - Name: AWS Elastic Block Store CSI Driver Operator File: persistent-storage-csi-ebs + - Name: GCP PD CSI Driver Operator + File: persistent-storage-csi-gcp-pd - Name: OpenStack Manila CSI Driver Operator File: persistent-storage-csi-manila - Name: Red Hat Virtualization (oVirt) CSI Driver Operator diff --git a/modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc b/modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc new file mode 100644 index 0000000000..588852fdb8 --- /dev/null +++ b/modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc @@ -0,0 +1,113 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc + +[id="persistent-storage-csi-gcp-pd-encrypted-pv_{context}"] += Creating a custom-encrypted persistent volume + +When you create a `PersistentVolumeClaim` object, {product-title} provisions a new persistent volume (PV) and creates a `PersistentVolume` object. You can add a custom encryption key in Google Cloud Platform (GCP) to protect a PV in your cluster by encrypting the newly created PV. + +For encryption, the newly attached PV that you create uses customer-managed encryption keys (CMEK) on a cluster by using a new or existing Google Cloud Key Management Service (KMS) key. + +.Prerequisites +* You are logged in to a running {product-title} cluster. +* You have created a Cloud KMS key ring and key version. + +For more information about CMEK and Cloud KMS resources, see link:https://cloud.google.com/kubernetes-engine/docs/how-to/using-cmek[Using customer-managed encryption keys (CMEK)]. + +.Procedure +To create a custom-encrypted PV, complete the following steps: + +. Create a storage class with the Cloud KMS key. The following example enables dynamic provisioning of encrypted volumes: ++ +[source,yaml] +-- +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: csi-gce-pd-cmek +provisioner: pd.csi.storage.gke.io +volumeBindingMode: "WaitForFirstConsumer" +allowVolumeExpansion: true +parameters: + type: pd-standard + disk-encryption-kms-key: projects//locations//keyRings//cryptoKeys/ <1> +-- +<1> This field must be the resource identifier for the key that will be used to encrypt new disks. Values are case-sensitive. For more information about providing key ID values, see link:https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id[Retrieving a resource's ID] and link:https://cloud.google.com/kms/docs/getting-resource-ids[Getting a Cloud KMS resource ID]. ++ +[NOTE] +==== +You cannot add the `disk-encryption-kms-key` parameter to an existing storage class. However, you can delete the storage class and recreate it with the same name and a different set of parameters. If you do this, the provisioner of the existing class must be `pd.csi.storage.gke.io`. +==== + +. Deploy the storage class on your {product-title} cluster using the `oc` command: ++ +[source,terminal] +-- +$ oc describe storageclass csi-gce-pd-cmek +-- ++ +.Example output +[source,terminal] +-- +Name: csi-gce-pd-cmek +IsDefaultClass: No +Annotations: None +Provisioner: pd.csi.storage.gke.io +Parameters: disk-encryption-kms-key=projects/key-project-id/locations/location/keyRings/ring-name/cryptoKeys/key-name,type=pd-standard +AllowVolumeExpansion: unset +MountOptions: none +ReclaimPolicy: Delete +VolumeBindingMode: WaitForFirstConsumer +Events: none +-- + +. Create a file named `pvc.yaml` that matches the name of your storage class object that you created in the previous step: ++ +[source,yaml] +-- +kind: PersistentVolumeClaim +apiVersion: v1 +metadata: + name: podpvc +spec: + accessModes: + - ReadWriteOnce + storageClassName: csi-gce-pd-cmek + resources: + requests: + storage: 6Gi +-- ++ +[NOTE] +==== +If you marked the new storage class as default, you can omit the `storageClassName` field. +==== + +. Apply the PVC on your cluster: ++ +[source,terminal] +-- +$ oc apply -f pvc.yaml +-- + +. Get the status of your PVC and verify that it is created and bound to a newly provisioned PV: ++ +[source,terminal] +-- +$ oc get pvc +-- ++ +[source,terminal] +.Example output +-- +NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE +podpvc Bound pvc-e36abf50-84f3-11e8-8538-42010a800002 10Gi RWO csi-gce-pd-cmek 9s +-- ++ +[NOTE] +==== +If your storage class has the `volumeBindingMode` field set to `WaitForFirstConsumer`, you must create a pod to use the PVC before you can verify it. +==== + +Your CMEK-protected PV is now ready to use with your {product-title} cluster. diff --git a/modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc b/modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc new file mode 100644 index 0000000000..3f7b3ce3bb --- /dev/null +++ b/modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc + +[id="persistent-storage-csi-gcp-pd-storage-class-ref_{context}"] += GCP PD CSI driver storage class parameters + +The Google Cloud Platform (GCP) persistent disk (PD) Container Storage Interface (CSI) driver uses the CSI `external-provisioner` sidecar as a controller. This is a separate helper container that is deployed with the CSI driver. The sidecar manages persistent volumes (PVs) by triggering the `CreateVolume` operation. + +The GCP PD CSI driver uses the `csi.storage.k8s.io/fstype` parameter key to support dynamic provisioning. The following table describes all the GCP PD CSI storage class parameters that are supported by {product-title}. + +.CreateVolume Parameters +[cols="2,3,2,4",options="header"] +|=== +|Parameter |Values |Default |Description + +|`type` | `pd-ssd` or `pd-standard` | `pd-standard` | Allows you to choose between standard PVs or solid-state-drive PVs. +|`replication-type`| `none` or `regional-pd` | `none` | Allows you to choose between zonal or regional PVs. +|`disk-encryption-kms-key` | Fully qualified resource identifier for the key to use to encrypt new disks. | Empty string | Uses customer-managed encryption keys (CMEK) to encrypt new disks. +|=== diff --git a/storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc b/storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc new file mode 100644 index 0000000000..137d7a6b32 --- /dev/null +++ b/storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc @@ -0,0 +1,36 @@ +[id="persistent-storage-csi-gcp-pd"] += GCP PD CSI Driver Operator +include::modules/common-attributes.adoc[] +:context: persistent-storage-csi-gcp-pd + +toc::[] + +== Overview + +{product-title} can provision persistent volumes (PVs) using the Container Storage Interface (CSI) driver for Google Cloud Platform (GCP) persistent disk (PD) storage. + +:FeatureName: GCP PD CSI Driver Operator +include::modules/technology-preview.adoc[leveloffset=+1] + +Familiarity with xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[persistent storage] and xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[configuring CSI volumes] is recommended when working with a Container Storage Interface (CSI) Operator and driver. + +To create CSI-provisioned persistent volumes (PVs) that mount to GCP PD storage assets, {product-title} installs the GCP PD CSI Driver Operator and the GCP PD CSI driver by default in the `openshift-cluster-csi-drivers` namespace. + +* *GCP PD CSI Driver Operator*: By default, the Operator provides a storage class that you can use to create PVCs. You also have the option to create the GCP PD storage class as described in xref:../../storage/persistent_storage/persistent-storage-gce.adoc#persistent-storage-using-gce[Persistent storage using GCE Persistent Disk]. + +* *GCP PD driver*: The driver enables you to create and mount GCP PD PVs. + +[IMPORTANT] +==== +{product-title} defaults to using an in-tree, or non-CSI, driver to provision GCP PD storage. This in-tree driver will be removed in a subsequent update of {product-title}. Volumes provisioned using the existing in-tree driver are planned for migration to the CSI driver at that time. +==== + +include::modules/persistent-storage-csi-about.adoc[leveloffset=+1] + +include::modules/persistent-storage-csi-gcp-pd-storage-class-ref.adoc[leveloffset=+1] + +include::modules/persistent-storage-csi-gcp-pd-encrypted-pv.adoc[leveloffset=+1] + +.Additional resources +* xref:../../storage/persistent_storage/persistent-storage-gce.adoc#persistent-storage-using-gce[Persistent storage using GCE Persistent Disk] +* xref:../../storage/container_storage_interface/persistent-storage-csi.adoc#persistent-storage-csi[Configuring CSI volumes]