Doc updates for ONTAP certificate-based auth

docs/kubernetes/operations/tasks/backends/ontap/drivers.rst

@@ -8,7 +8,8 @@ To create and use an ONTAP backend, you will need:
 * Choose the :ref:`ONTAP storage driver <Choosing a driver>` that you want to
   use
 * Complete ONTAP backend preparation for the driver of your choice
-* Credentials to an ONTAP SVM with :ref:`appropriate access <User permissions>`
+* Authentication credentials (username/password or certificate) to an ONTAP SVM
+  with :ref:`appropriate access <User permissions>`
 
 Trident provides 5 unique storage drivers for communicating with ONTAP
 clusters. Each driver handles the creation of volumes and access control
@@ -26,6 +27,15 @@ ontap-san           iSCSI    Filesystem RWO,ROX                ``xfs``, ``ext3``
 ontap-san-economy   iSCSI    Filesystem RWO,ROX                ``xfs``, ``ext3``, ``ext4``
 =================== ======== ========== ====================== ===============================
 
+.. note::
+
+  ONTAP backends can be authenticated by one of two means:
+    - Login credentials for a security role [username/password] **OR**
+    - Certificated-based, using the private key and the certificate that is
+      installed on the ONTAP cluster.
+  Users can update existing backends to move from one authentication mode to the other
+  with ``tridentctl update backend``.
+
 The ``ontap-san`` and ``ontap-san-economy`` drivers support the ``Filesystem``
 and ``Block`` volumeModes. Users can choose to create a raw block volume with
 no file system (or) have Trident create a volume with a file system. For the

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

@@ -1,6 +1,8 @@
-#####################
-Backend Configuration
-#####################
+.. _ontap-nas-configuration-parameters:
+
+###############################
+ONTAP NAS Backend Configuration
+###############################
 
 ========================= ================================================================================================= ================================================
 Parameter                 Description                                                                                       Default
@@ -14,8 +16,11 @@ svm                       Storage virtual machine to use
 labels                    Set of arbitrary JSON-formatted labels to apply on volumes.                                       ""
 autoExportPolicy          Enable automatic export policy creation and updating [Boolean]                                    false
 autoExportCIDRs           List of CIDRs to filter Kubernetes' node IPs against when autoExportPolicy is enabled             ["0.0.0.0/0", "::/0"]
-username                  Username to connect to the cluster/SVM
-password                  Password to connect to the cluster/SVM
+clientCertificate         Base64-encoded value of client certificate. Used for certificate-based auth.                      ""
+clientPrivateKey          Base64-encoded value of client private key. Used for certificate-based auth.                      ""
+trustedCACertificate      Base64-encoded value of trusted CA certificate. Optional. Used for certificate-based auth.        ""
+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.
 storagePrefix             Prefix used when provisioning new volumes in the SVM. Once set this **cannot be updated**         "trident"
 limitAggregateUsage       Fail provisioning if usage is above this percentage                                               "" (not enforced by default)
 limitVolumeSize           Fail provisioning if requested volume size is above this value                                    "" (not enforced by default)
@@ -24,6 +29,11 @@ qtreesPerFlexvol          Maximum qtrees per FlexVol, must be in range [50, 300]
 debugTraceFlags           Debug flags to use when troubleshooting. E.g.: {"api":false, "method":true}                       null
 ========================= ================================================================================================= ================================================
 
+To communicate with the ONTAP cluster, Trident must be provided with authentication
+parameters. This could be the username/password to a security login (OR) an
+installed certificate. This is fully documented in the
+:ref:`Authentication Guide <ontap-nas-authentication>`.
+
 .. warning::
 
   Do not use ``debugTraceFlags`` unless you are troubleshooting and require a

docs/kubernetes/operations/tasks/backends/ontap/ontap-nas/dynamic-export-policies.rst

@@ -1,3 +1,4 @@
+.. _dynamic-export-policy-ontap:
 ######################################
 Dynamic Export Policies with ONTAP NAS
 ######################################

docs/kubernetes/operations/tasks/backends/ontap/ontap-nas/examples.rst

@@ -10,10 +10,31 @@ NAS Drivers. These examples are classified into two types:
 
 2. Backends with :ref:`Virtual Storage Pools <Virtual Storage Pools>`.
 
-
 Minimal backend configuration for ontap drivers
 -----------------------------------------------
 
+ontap-nas driver with certificate-based authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``clientCertificate``, ``clientPrivateKey`` and ``trustedCACertificate`` (optional,
+if using trusted CA) are populated in backend.json and take the Base64-encoded
+values of the client certificate, private key and trusted CA certificate respectively.
+
+.. code-block:: json
+
+  {
+    "version": 1,
+    "backendName": "DefaultNASBackend",
+    "storageDriverName": "ontap-nas",
+    "managementLIF": "10.0.0.1",
+    "dataLIF": "10.0.0.15",
+    "svm": "nfs_svm",
+    "clientCertificate": "ZXR0ZXJwYXB...ICMgJ3BhcGVyc2",
+    "clientPrivateKey": "vciwKIyAgZG...0cnksIGRlc2NyaX",
+    "trustedCACertificate": "zcyBbaG...b3Igb3duIGNsYXNz",
+    "storagePrefix": "myPrefix_"
+  }
+
 ontap-nas driver with auto export policy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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

@@ -1,3 +1,5 @@
+.. _ontap-nas-preparation:
+
 ###########
 Preparation
 ###########
@@ -12,12 +14,202 @@ classes that point to one or the other. For example, you could configure a
 *Gold* class that uses the ``ontap-nas`` driver and a *Bronze* class that
 uses the ``ontap-nas-economy`` one.
 
-ontap-nas, ontap-nas-economy, ontap-nas-flexgroups
---------------------------------------------------
-
 All of your Kubernetes worker nodes must have the appropriate NFS tools
 installed. See the :ref:`worker configuration guide <NFS>` for more details.
 
+.. _ontap-nas-authentication:
+
+Authentication
+--------------
+
+Trident offers two modes of authenticating an ONTAP backend.
+
+-  **Credential-based**: The username and password to an ONTAP user with the
+   required :ref:`permissions <ontap-nas-user-permissions>`. It is recommended
+   to use a pre-defined security login role, such as ``admin`` or ``vsadmin`` to
+   ensure maximum compatibility with ONTAP versions.
+-  **Certificate-based**: Trident can also communicate with an ONTAP cluster using
+   a certificate installed on the backend. Here, the backend definition must
+   contain Base64-encoded values of the client certificate, key, and the trusted
+   CA certificate if used (recommended).
+
+Users can also choose to update existing backends, opting to move from
+credential-based to certificate-based, and vice-versa. If **both credentials and
+certificates are provided**, Trident will default to using certificates while
+issuing a warning to remove the credentials from the backend definition.
+
+Credential-based Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Trident requires the credentials to an SVM-scoped/Cluster-scoped admin to
+communicate with the ONTAP backend. It is recommended to make use of standard,
+pre-defined roles such as ``admin`` or ``vsadmin``. This ensures forward
+compatibility with future ONTAP releases that may expose feature APIs to be used
+by future Trident releases. A custom security login role can be created and used
+with Trident, but is **not recommended**.
+
+A sample backend definition will look like this:
+
+.. code-block:: json
+
+  {
+    "version": 1,
+    "backendName": "ExampleBackend",
+    "storageDriverName": "ontap-nas",
+    "managementLIF": "10.0.0.1",
+    "dataLIF": "10.0.0.2",
+    "svm": "svm_nfs",
+    "username": "vsadmin",
+    "password": "secret",
+  }
+
+Keep in mind that the backend definition is the only place the credentials are
+stored in plaintext. Once the backend is created, **usernames/passwords are encoded
+with Base64 and stored as Kubernetes secrets**. The creation/updation of a backend
+is the only step that requires knowledge of the credentials. As such, it is an
+admin-only operation, to be performed by the Kubernetes/Storage administrator.
+
+Certificated-based Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Trident ``21.01`` introduces a new feature: authenticating ONTAP backends using
+certificates. New and existing backends can use a certificate and communicate with
+the ONTAP backend. Three parameters are required in the backend definition.
+
+- ``clientCertificate``: Base64-encoded value of client certificate.
+- ``clientPrivateKey``: Base64-encoded value of associated private key.
+- ``trustedCACertificate``: Base64-encoded value of trusted CA certificate. If
+  using a trusted CA, this parameter must be provided. This can be ignored if
+  no trusted CA is used.
+
+A typical workflow involves the following steps:
+
+1. A client certificate and key are generated. When generating, **CN (Common Name) is
+   set to the ONTAP user to authenticate as**.
+
+  .. code-block:: bash
+
+    #Generate certificate used to authenticate the client
+    openssl req -x509 -nodes -days 1095 -newkey rsa:2048 -keyout k8senv.key -out k8senv.pem -subj "/C=US/ST=NC/L=RTP/O=NetApp/CN=admin"
+
+2. Add trusted CA certificate to the ONTAP cluster. This may be already handled by
+   the storage administrator. Ignore if no trusted CA is used.
+
+  .. code-block:: bash
+
+    #Install trusted CA cert in ONTAP cluster.
+    security certificate install -type server -cert-name <trusted-ca-cert-name> -vserver <vserver-name>
+    ssl modify -vserver <vserver-name> -server-enabled true -client-enabled true -common-name <common-name> -serial <SN-from-trusted-CA-cert> -ca <cert-authority>
+
+3. Install the client certificate and key (from step 1) on the ONTAP cluster.
+
+  .. code-block:: bash
+
+    #Install certificate generated from step 1 on ONTAP cluster
+    security certificate install -type client-ca -cert-name <certificate-name> -vserver <vserver-name>
+    security ssl modify -vserver <vserver-name> -client-enabled true
+
+4. Confirm the ONTAP security login role supports ``cert`` authentication method.
+
+   .. code-block:: bash
+
+     #Add cert authentication method to ONTAP security login role
+     security login create -user-or-group-name admin -application ontapi -authentication-method cert
+     security login create -user-or-group-name admin -application http -authentication-method cert
+
+5. Test authentication using certificate generated.
+
+   .. code-block:: bash
+
+     #Test access to ONTAP cluster using certificate. Replace <ONTAP Management LIF> and <vserver name> with Management LIF IP and SVM name.
+     curl -X POST -Lk https://<ONTAP-Management-LIF>/servlets/netapp.servlets.admin.XMLrequest_filer --key k8senv.key --cert ~/k8senv.pem -d '<?xml version="1.0" encoding="UTF-8"?><netapp xmlns="http://www.netapp.com/filer/admin" version="1.21" vfiler="<vserver-name>"><vserver-get></vserver-get></netapp>'
+
+6. Encode certificate, key and trusted CA certificate with Base64.
+
+   .. code-block:: bash
+
+     #Encode with Base64 and write each key to a file.
+     base64 -w 0 k8senv.pem >> cert_base64
+     base64 -w 0 k8senv.key >> key_base64
+     base64 -w 0 trustedca.pem >> trustedca_base64
+
+7. Create backend using the values obtained from step 6.
+
+   .. code-block:: bash
+
+     #Trident backend using cert-based auth
+     $ cat cert-backend.json
+     {
+     "version": 1,
+     "storageDriverName": "ontap-nas",
+     "backendName": "NasBackend",
+     "managementLIF": "1.2.3.4",
+     "dataLIF": "1.2.3.8",
+     "svm": "vserver_test",
+     "clientCertificate": "Faaaakkkkeeee...Vaaalllluuuueeee",
+     "clientPrivateKey": "LS0tFaKE...0VaLuES0tLS0K",
+     "trustedCACertificate": "QNFinfO...SiqOyN",
+     "storagePrefix": "myPrefix_"
+     }
+
+     #Create backend
+     $ tridentctl create backend -f cert-backend.json -n trident
+     +------------+----------------+--------------------------------------+--------+---------+
+     |    NAME    | STORAGE DRIVER |                 UUID                 | STATE  | VOLUMES |
+     +------------+----------------+--------------------------------------+--------+---------+
+     | NasBackend | ontap-nas      | 98e19b74-aec7-4a3d-8dcf-128e5033b214 | online |       0 |
+     +------------+----------------+--------------------------------------+--------+---------+
+
+Updating Authentication Methods/Rotating Credentials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can update an existing backend to make use of a different authentication
+method or to rotate their credentials. This works both ways: backends that make
+use of username/password can be updated to use certificates; backends that
+utilize certificates can be updated to username/password based. To do this,
+an updated backend.json file containing the required parameters must be used to
+execute ``tridentctl backend update``.
+
+.. note::
+
+  When rotating passwords, the storage administrator must first update the
+  password for the user on ONTAP. This is followed by a backend update. When
+  rotating certificates, multiple certificates can be added to the user. The
+  backend is then updated to use the new certificate, following which the old
+  certificate can be deleted from the ONTAP cluster.
+
+.. code-block:: bash
+
+  #Update backend.json to include chosen auth method
+  $ cat cert-backend-updated.json
+  {
+  "version": 1,
+  "storageDriverName": "ontap-nas",
+  "backendName": "NasBackend",
+  "managementLIF": "1.2.3.4",
+  "dataLIF": "1.2.3.8",
+  "svm": "vserver_test",
+  "username": "vsadmin",
+  "password": "secret",
+  "storagePrefix": "myPrefix_"
+  }
+
+  #Update backend with tridentctl
+  $ tridentctl update backend NasBackend -f cert-backend-updated.json -n trident
+  +------------+----------------+--------------------------------------+--------+---------+
+  |    NAME    | STORAGE DRIVER |                 UUID                 | STATE  | VOLUMES |
+  +------------+----------------+--------------------------------------+--------+---------+
+  | NasBackend | ontap-nas      | 98e19b74-aec7-4a3d-8dcf-128e5033b214 | online |       9 |
+  +------------+----------------+--------------------------------------+--------+---------+
+
+Updating a backend does not disrupt access to volumes that have already been
+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.
+
+Export-policy Management
+------------------------
+
 Trident uses NFS `export policies`_ to control access to the volumes that it
 provisions.
 
@@ -42,6 +234,8 @@ on the worker nodes it runs on. As and when nodes are removed or added to the
 Kubernetes cluster, Trident can be set up to permit access to the nodes, thus
 providing a more robust way of managing access to the PVs it creates. Trident
 will create one export policy per backend. **This feature requires CSI Trident**.
+To learn more about this feature, continue to
+:ref:`Dynamic Export Policy Management <dynamic-export-policy-ontap>`.
 
 With (2), Trident does not create or otherwise manage export policies themselves.
 The export policy must exist before the storage backend is added to Trident,

docs/kubernetes/operations/tasks/backends/ontap/ontap-nas/user-permissions.rst

@@ -1,3 +1,5 @@
+.. _ontap-nas-user-permissions:
+
 ################
 User permissions
 ################

docs/kubernetes/operations/tasks/backends/ontap/ontap-san/bidir-ontap-chap.rst

@@ -1,3 +1,5 @@
+.. _ontap-bidir-chap:
+
 #################################
 Using CHAP with ONTAP SAN drivers
 #################################

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

@@ -1,6 +1,8 @@
-#####################
-Backend Configuration
-#####################
+.. _ontap-san-configuration-parameters:
+
+###############################
+ONTAP SAN Backend Configuration
+###############################
 
 ========================= ================================================================================================= ================================================
 Parameter                 Description                                                                                       Default
@@ -16,6 +18,11 @@ labels                    Set of arbitrary JSON-formatted labels to apply on vol
 chapTargetInitiatorSecret CHAP target initiator secret. Required if ``useCHAP=true``                                        ""
 chapUsername              Inbound username. Required if ``useCHAP=true``                                                    ""
 chapTargetUsername        Target username. Required if ``useCHAP=true``                                                     ""
+clientCertificate         Base64-encoded value of client certificate. Used for certificate-based auth.                      ""
+clientPrivateKey          Base64-encoded value of client private key. Used for certificate-based auth.                      ""
+trustedCACertificate      Base64-encoded value of trusted CA certificate. Optional. Used for certificate-based auth.        ""
+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"
 username                  Username to connect to the cluster/SVM
@@ -27,6 +34,11 @@ lunsPerFlexvol            Maximum LUNs per Flexvol, must be in range [50, 200]
 debugTraceFlags           Debug flags to use when troubleshooting. E.g.: {"api":false, "method":true}                       null
 ========================= ================================================================================================= ================================================
 
+To communicate with the ONTAP cluster, Trident must be provided with authentication
+parameters. This could be the username/password to a security login (OR) an
+installed certificate. This is fully documented in the
+:ref:`Authentication Guide <ontap-san-authentication>`.
+
 .. warning::
 
   Do not use ``debugTraceFlags`` unless you are troubleshooting and require a
@@ -43,6 +55,19 @@ 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.
+
+.. warning::
+
+   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.
+
 A fully-qualified domain name (FQDN) can be specified for the ``managementLIF``
 option.