Make iSCSI options more obvious

The default iSCSI PV example should use just the basic options and the
other options should be explained (and demonstrated) in the subchapters.

It helps users to pick only the options they need instead of using all of
them from the example.

modules/storage-persistent-storage-iscsi-provisioning.adoc

@@ -9,9 +9,6 @@ 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
 ====
 
@@ -28,14 +25,8 @@ spec:
     - 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
 ----
 ====

modules/storage-persistent-storage-iscsi-volume-security.adoc

@@ -10,3 +10,36 @@ that same namespace. Any attempt to access a persistent volume claim across a
 namespace causes the pod to fail.
 
 Each iSCSI LUN must be accessible by all nodes in the cluster.
+
+== Challenge Handshake Authentication Protocol (CHAP) configuration
+
+Optionally, OpenShift can use CHAP to authenticate itself to iSCSI targets:
+
+====
+[source, yaml]
+----
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: iscsi_pv
+spec:
+  capacity:
+    storage: 1Gi
+  accessModes:
+    - ReadWriteOnce
+  iscsi:
+    targetPortal: 10.0.0.1:3260
+    iqn: iqn.2016-04.test.com:storage.target00
+    lun: 0
+    fsType: ext4
+    chapAuthDiscovery: true <1>
+    chapAuthSession: true <2>
+    secretRef:
+      name: chap-secret <3>
+
+----
+<1> Enable CHAP authentication of iSCSI discovery.
+<2> Enable CHAP authentication of iSCSI session.
+<3> Specify name of Secrets object with user name + password. This Secrets
+object must be available in all namespaces that can use the referenced volume.
+====

storage/persistent-storage/persistent-storage-iscsi.adoc

@@ -28,6 +28,14 @@ security policy to include TCP traffic between nodes on the iSCSI ports.
 By default, they are ports `860` and `3260`.
 ====
 
+[IMPORTANT]
+====
+OpenShift assumes that all nodes in the cluster have already configured iSCSI
+initator, i.e. have installed `iscsi-initiator-utils` package and configured
+their initiator name in `/etc/iscsi/initiatorname.iscsi`. See Storage
+Administration Guide linked above.
+====
+
 include::modules/storage-persistent-storage-iscsi-provisioning.adoc[leveloffset=+1]
 
 include::modules/storage-persistent-storage-iscsi-enforcing-disk-quota.adoc[leveloffset=+1]