From 14839b47076a68745ddac342d20c3b0c62ebab31 Mon Sep 17 00:00:00 2001 From: Christian Huffman Date: Fri, 22 Feb 2019 16:20:11 -0500 Subject: [PATCH] OSDOCS-293: Included iSCSI persistent storage configuration. --- ...istent-storage-iscsi-custom-initiator.adoc | 36 ++++++++++++++++ ...nt-storage-iscsi-enforcing-disk-quota.adoc | 13 ++++++ ...ge-persistent-storage-iscsi-multipath.adoc | 37 +++++++++++++++++ ...persistent-storage-iscsi-provisioning.adoc | 41 +++++++++++++++++++ ...sistent-storage-iscsi-volume-security.adoc | 12 ++++++ storage/persistent-storage-iscsi.adoc | 32 +++++++++++++++ 6 files changed, 171 insertions(+) create mode 100644 modules/storage-persistent-storage-iscsi-custom-initiator.adoc create mode 100644 modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc create mode 100644 modules/storage-persistent-storage-iscsi-multipath.adoc create mode 100644 modules/storage-persistent-storage-iscsi-provisioning.adoc create mode 100644 modules/storage-persistent-storage-iscsi-volume-security.adoc create mode 100644 storage/persistent-storage-iscsi.adoc diff --git a/modules/storage-persistent-storage-iscsi-custom-initiator.adoc b/modules/storage-persistent-storage-iscsi-custom-initiator.adoc new file mode 100644 index 0000000000..8dbbaeed8a --- /dev/null +++ b/modules/storage-persistent-storage-iscsi-custom-initiator.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * storage/persistent-storage-iscsi.adoc + +[[iscsi-custom-iqn]] += iSCSI Custom Initiator IQN +Configure the custom initiator iSCSI Qualified Name (IQN) if the iSCSI +targets are restricted to certain IQNs, but the nodes that the iSCSI PVs +are attached to are not guaranteed to have these IQNs. + +To specify a custom initiator IQN, use `initiatorName` field. + +==== +[source, yaml] +---- +apiVersion: v1 +kind: PersistentVolume +metadata: + name: iscsi_pv +spec: + capacity: + storage: 1Gi + accessModes: + - ReadWriteOnce + iscsi: + targetPortal: 10.0.0.1:3260 + portals: ['10.0.2.16:3260', '10.0.2.17:3260', '10.0.2.18:3260'] + iqn: iqn.2016-04.test.com:storage.target00 + lun: 0 + initiatorName: iqn.2016-04.test.com:custom.iqn <1> + fsType: ext4 + readOnly: false +---- +<1> Specify the name of the inquisitor. +==== + diff --git a/modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc b/modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc new file mode 100644 index 0000000000..3573911c10 --- /dev/null +++ b/modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * storage/persistent-storage-iscsi.adoc + +[[enforcing-disk-quotas-iscsi]] += Enforcing Disk Quotas +Use LUN partitions to enforce disk quotas and size constraints. Each LUN +is one persistent volume. Kubernetes enforces unique names for persistent +volumes. + +Enforcing quotas in this way allows the end user to request persistent +storage by a specific amount (e.g, 10Gi) and be matched with a +corresponding volume of equal or greater capacity. diff --git a/modules/storage-persistent-storage-iscsi-multipath.adoc b/modules/storage-persistent-storage-iscsi-multipath.adoc new file mode 100644 index 0000000000..99e554b999 --- /dev/null +++ b/modules/storage-persistent-storage-iscsi-multipath.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * storage/persistent-storage-iscsi.adoc + +[[iscsi-multipath]] += iSCSI Multipathing +For iSCSI-based storage, you can configure multiple paths by using the +same IQN for more than one target portal IP address. Multipathing ensures +access to the persistent volume when one or more of the components in a +path fail. + +To specify multi-paths in the pod specification use the `portals` field. +For example: + +==== +[source, yaml] +---- +apiVersion: v1 +kind: PersistentVolume +metadata: + name: iscsi_pv +spec: + capacity: + storage: 1Gi + accessModes: + - ReadWriteOnce + iscsi: + targetPortal: 10.0.0.1:3260 + portals: ['10.0.2.16:3260', '10.0.2.17:3260', '10.0.2.18:3260'] <1> + iqn: iqn.2016-04.test.com:storage.target00 + lun: 0 + fsType: ext4 + readOnly: false +---- +<1> Add additional target portals using the `portals` field. +==== + diff --git a/modules/storage-persistent-storage-iscsi-provisioning.adoc b/modules/storage-persistent-storage-iscsi-provisioning.adoc new file mode 100644 index 0000000000..07ec18cffd --- /dev/null +++ b/modules/storage-persistent-storage-iscsi-provisioning.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies +// +// * storage/persistent-storage-iscsi.adoc + +[[persistent-storage-iscsi-provisioning]] += Provisioning +Verify that the storage exists in the underlying infrastructure before +mounting it as a volume in {product-title}. All that is required for the +iSCSI is the iSCSI target portal, a valid iSCSI Qualified Name (IQN), +a valid LUN number, the filesystem type, and the `PersistentVolume` API. + +Optionally, you can provide multipath portals and the Challenge Handshake +Authentication Protocol (CHAP) configuration. + +.Persistent Volume Object Definition +==== + +[source,yaml] +---- +apiVersion: v1 +kind: PersistentVolume +metadata: + name: iscsi-pv +spec: + capacity: + storage: 1Gi + accessModes: + - ReadWriteOnce + iscsi: + targetPortal: 10.16.154.81:3260 + portals: ['10.16.154.82:3260', '10.16.154.83:3260'] + iqn: iqn.2014-12.example.server:storage.target00 + lun: 0 + fsType: 'ext4' + readOnly: false + chapAuthDiscovery: true + chapAuthSession: true + secretRef: + name: chap-secret +---- +==== diff --git a/modules/storage-persistent-storage-iscsi-volume-security.adoc b/modules/storage-persistent-storage-iscsi-volume-security.adoc new file mode 100644 index 0000000000..f573495bed --- /dev/null +++ b/modules/storage-persistent-storage-iscsi-volume-security.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * storage/persistent-storage-iscsi.adoc + +[[volume-security-iscsi]] += iSCSI Volume Security +Users request storage with a `PersistentVolumeClaim`. This claim only +lives in the user's namespace and can only be referenced by a pod within +that same namespace. Any attempt to access a persistent volume across a +namespace causes the pod to fail. + +Each iSCSI LUN must be accessible by all nodes in the cluster. diff --git a/storage/persistent-storage-iscsi.adoc b/storage/persistent-storage-iscsi.adoc new file mode 100644 index 0000000000..85ab0fdaad --- /dev/null +++ b/storage/persistent-storage-iscsi.adoc @@ -0,0 +1,32 @@ +[id='persistent-storage-using-iscsi'] += Persistent Storage Using iSCSI +include::modules/common-attributes.adoc[] +:context: persistent-storage-iscsi + +toc::[] + +You can provision your {product-title} cluster with +persistent storage using +https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Storage_Administration_Guide/ch-iscsi.html[iSCSI]. +Some familiarity with Kubernetes and iSCSI 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. + +[IMPORTANT] +==== +High-availability of storage in the infrastructure is left to the underlying +storage provider. +==== + +include::modules/storage-persistent-storage-iscsi-provisioning.adoc[leveloffset=+1] + +include::modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc[leveloffset=+1] + +include::modules/storage-persistent-storage-iscsi-volume-security.adoc[leveloffset=+1] + +include::modules/storage-persistent-storage-iscsi-multipath.adoc[leveloffset=+1] + +include::modules/storage-persistent-storage-iscsi-custom-initiator.adoc[leveloffset=+1]