Doc updates: handling igroups with ONTAP SAN drivers

docs/frequently_asked_questions.rst

@@ -77,12 +77,14 @@ Refer to :ref:`Customized Installation <Customized Installation>` for instructio
 Can we share the same ONTAP backend SVM for two separate Trident instances for two separate Kubernetes clusters?
 ----------------------------------------------------------------------------------------------------------------
 
-Although it is not advised, you can use the same backend SVM for 2 Trident instances. Specify a unique Trident volume name for
-each Trident instance during installation and/or specify a unique StoragePrefix parameter in the setup/backend.json file. This is to ensure the same FlexVol isn't used for both instances.
-
-Refer to: :ref:`Customized Installation <Customized Installation>` for information on specifying a unique Trident volume name.
-Refer to: :ref:`Global Configuration <Global Configuration>` for information on creating a unique StoragePrefix.
-
+Although it is not advised, you can use the same backend SVM for multiple Trident instances.
+Specifying a unique ``StoragePrefix`` parameter in the backend.json file will help
+track the volumes created in each Kubernetes environment.
+
+If using the ONTAP SAN drivers (``ontap-san`` and/or ``ontap-san-economy``), it is
+important to ensure **unique** igroups are used. The simplest way to do this is
+to have Trident create igroups for you. Take a look at :ref:`igroup Management <igroup-management>`
+to learn how that works.
 
 Is it possible to install Trident under ContainerLinux (formerly CoreOS)?
 -------------------------------------------------------------------------

docs/kubernetes/operations/tasks/backends/ontap/ontap-san/configuration.rst

@@ -24,7 +24,7 @@ trustedCACertificate      Base64-encoded value of trusted CA certificate. Option
 username                  Username to connect to the cluster/SVM. Used for credential-based auth.
 password                  Password to connect to the cluster/SVM. Used for credential-based auth.
 svm                       Storage virtual machine to use                                                                    Derived if an SVM managementLIF is specified
-igroupName                Name of the igroup for SAN volumes to use                                                         "trident"
+igroupName                Name of the igroup for SAN volumes to use                                                         "trident-<backend-UUID>"
 username                  Username to connect to the cluster/SVM
 password                  Password to connect to the cluster/SVM
 storagePrefix             Prefix used when provisioning new volumes in the SVM. Once set this **cannot be updated**         "trident"
@@ -55,20 +55,22 @@ specified address.
    cannot be modified after creation. To update these parameters you will need
    to create a new backend.
 
-The ``igroupName`` is set to an igroup that is already created on the ONTAP cluster.
-CSI Trident will automatically populate the igroup with node IQNs as volumes are
-created and attached. Similarly, node removals from the Kubernetes cluster will
-result in deleting the IQNs from the igroup. NetApp recommends using an igroup
-per Kubernetes cluster, if the SVM is to be shared between environments. This is
+The ``igroupName`` can be set to an igroup that is already created on the ONTAP cluster.
+If unspecified, Trident automatically creates an igroup named ``trident-<backend-UUID>``.
+If providing a pre-defined ``igroupName``, NetApp recommends using an igroup per
+Kubernetes cluster, if the SVM is to be shared between environments. This is
 necessary for Trident to maintain IQN additions/deletions automatically.
 
-.. warning::
+Backends can also have igroups updated after creation:
+
+* ``igroupName`` can be updated to point to a new igroup that is created and managed
+  on the SVM outside of Trident.
+* ``igroupName`` can be omitted. In this case, Trident will create and manage a
+  ``trident-<backend-UUID>`` igroup automatically.
 
-   While ``igroupName`` can be updated for a backend, it is important to remember
-   that the new igroup will only be used for all volumes created henceforth.
-   Existing volumes will continue to use the old igroup. Updating ``igroupName``
-   is **not recommended** unless the old igroup will still remain untouched on the
-   storage cluster.
+In both cases, volume attachments will continue to be accessible.
+Future volume attachments will use the updated igroup. This update does not disrupt
+access to volumes present on the backend.
 
 A fully-qualified domain name (FQDN) can be specified for the ``managementLIF``
 option.

docs/kubernetes/operations/tasks/backends/ontap/ontap-san/preparing.rst

@@ -207,12 +207,28 @@ created, nor impact volume connections made after. A successful backend update
 indicates that Trident can communicate with the ONTAP backend and handle future
 volume operations.
 
+.. _igroup-management:
+
 igroup Management
 -----------------
 
 Trident uses `igroups`_ to control access to the volumes (LUNs) that it
-provisions. It expects to find an igroup called ``trident`` unless a different
-igroup name is specified in the configuration.
+provisions. Trident administrators have two options when it comes to specifying
+igroups for backends:
+
+* Trident can automatically create and manage an igroup per backend. If
+  ``igroupName`` is not included in the backend definition, Trident creates an
+  igroup named ``trident-<backend-UUID>`` on the SVM. This will ensure each
+  backend has a dedicated igroup and handle the automated addition/deletion of
+  Kubernetes node IQNs.
+* Alternatively, pre-created igroups can also be provided in a backend definition.
+  This can be done using the ``igroupName`` config parameter. Trident will
+  add/delete Kubernetes node IQNs to the pre-existing igroup.
+
+For backends that have ``igroupName`` defined, the ``igroupName`` can be deleted
+with a ``tridentctl backend update`` to have Trident auto-handle igroups. This
+will not disrupt access to volumes that are already attached to workloads. Future
+connections will be handled using the igroup Trident created.
 
 .. _igroups: https://library.netapp.com/ecmdocs/ECMP1196995/html/GUID-CF01DCCD-2C24-4519-A23B-7FEF55A0D9A3.html
 
@@ -231,19 +247,18 @@ igroup name is specified in the configuration.
    and removal of IQNs. Reusing IQNs across hosts can lead to undesirable scenarios
    where hosts get mistaken for one another and access to LUNs is denied.
 
-While Trident associates new LUNs with the configured igroup, it does not
-create or otherwise manage igroups themselves. The igroup must exist before the
-storage backend is added to Trident.
-
-If Trident is configured to function as a CSI Provisioner, Trident manages the
-addition of IQNs from worker nodes when mounting PVCs. As and when PVCs are
-attached to pods running on a given node, Trident adds the node's IQN to the
-igroup configured in your backend definition.
+If Trident is configured to function as a CSI Provisioner, Kubernetes node IQNs
+are automatically added to/removed from the igroup. When nodes are added to a
+Kubernetes cluster, ``trident-csi`` DaemonSet deploys a pod (``trident-csi-xxxxx``)
+on the newly added nodes and registers the new nodes it can attach volumes to.
+Node IQNs are also added to the backend's igroup. A similar set of steps handle
+the removal of IQNs when node(s) are cordoned, drained, and deleted from Kubernetes.
 
 If Trident does not run as a CSI Provisioner, the igroup must be manually updated
-to contain the iSCSI IQNs from every worker node in the Kubernetes cluster. The
-igroup needs to be updated when new nodes are added to the cluster, and
-they should be removed when nodes are removed as well.
+to contain the iSCSI IQNs from every worker node in the Kubernetes cluster. IQNs
+of nodes that join the Kubernetes cluster will need to be added to the igroup.
+Similarly, IQNs of nodes that are removed from the Kubernetes cluster must be
+removed from the igroup.
 
 Authenticating Connections with Bidirectional CHAP
 --------------------------------------------------