Persistent Storage Using iSCSI

Overview

You can provision your OKD cluster with persistent storage using 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.

High-availability of storage in the infrastructure is left to the underlying storage provider.

Provisioning

Verify that the storage exists in the underlying infrastructure before mounting it as a volume in OKD. 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, multipath portals and Challenge Handshake Authentication Protocol (CHAP) configuration can be provided.

Example 1. Persistent Volume Object Definition

  1. apiVersion: v1
  2. kind: PersistentVolume
  3. metadata:
  4.   name: iscsi-pv
  5. spec:
  6.   capacity:
  7.     storage: 1Gi
  8.   accessModes:
  9.     - ReadWriteOnce
  10.   iscsi:
  11.      targetPortal: 10.16.154.81:3260
  12.      portals: ['10.16.154.82:3260', '10.16.154.83:3260']
  13.      iqn: iqn.2014-12.example.server:storage.target00
  14.      lun: 0
  15.      fsType: 'ext4'
  16.      readOnly: false
  17.      chapAuthDiscovery: true
  18.      chapAuthSession: true
  19.      secretRef:
  20.        name: chap-secret

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.

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.

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 pod specification use the portals field. For example:

  1. apiVersion: v1
  2. kind: PersistentVolume
  3. metadata:
  4.   name: iscsi-pv
  5. spec:
  6.   capacity:
  7.     storage: 1Gi
  8.   accessModes:
  9.     - ReadWriteOnce
  10.   iscsi:
  11.     targetPortal: 10.0.0.1:3260
  12.     portals: ['10.0.2.16:3260', '10.0.2.17:3260', '10.0.2.18:3260'] (1)
  13.     iqn: iqn.2016-04.test.com:storage.target00
  14.     lun: 0
  15.     fsType: ext4
  16.     readOnly: false
1Add additional target portals using the portals field.

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 custom initiator IQN, use initiatorName field.

  1. apiVersion: v1
  2. kind: PersistentVolume
  3. metadata:
  4.   name: iscsi-pv
  5. spec:
  6.   capacity:
  7.     storage: 1Gi
  8.   accessModes:
  9.     - ReadWriteOnce
  10.   iscsi:
  11.     targetPortal: 10.0.0.1:3260
  12.     portals: ['10.0.2.16:3260', '10.0.2.17:3260', '10.0.2.18:3260']
  13.     iqn: iqn.2016-04.test.com:storage.target00
  14.     lun: 0
  15.     initiatorName: iqn.2016-04.test.com:custom.iqn (1)
  16.     fsType: ext4
  17.     readOnly: false
1To add an additional custom initiator IQN, use initiatorName field.