Doc updates

docs/dag/kubernetes/deploying_trident.rst

@@ -35,7 +35,13 @@ Normal installation involves running the ``tridentctl install -n trident`` comma
 **Offline install mode**
 
 In many organizations, production and development environments do not have access to public repositories for pulling and posting images as these environments are completely secured and restricted. Such environments only allow pulling images from trusted private repositories.
-In such scenarios, make sure that a private registry instance is available. The trident image should be downloaded from a bastion host with internet access and pushed on to the private registry. To install Trident in offline mode, just issue the ``tridentctl install -n trident`` command with the ``--trident-image`` parameter set to the appropriate image name and location.
+
+To perform an air-gapped installation of Trident, you can use the ``--image-registry`` flag
+when invoking ``tridentctl install`` to point to a private image registry. This registry must
+contain the Trident image (obtained `here <https://hub.docker.com/r/netapp/trident/>`_) and the
+CSI sidecar images as required by your Kubernetes version. The
+:ref:`Customized Installation <Customized Installation>` section talks about the options available
+for performing a custom Trident install.
 
 **Remote install mode**
 
@@ -140,8 +146,8 @@ Deploying Trident to OpenShift
 
 OpenShift uses Kubernetes for the underlying container orchestrator. Consequently, the same recommendations will apply when using Trident with Kubernetes or OpenShift. However, there are some minor additions when using OpenShift which should be taken into consideration.
 
-Deploy Trident to infrastructure nodes
---------------------------------------
+Deploy Trident to infrastructure nodes (OpenShift 3.11)
+-------------------------------------------------------
 
 Trident is a core service to the OpenShift cluster, provisioning and managing the volumes used across all projects. Consideration should be given to deploying Trident to the infrastructure nodes in order to provide the same level of care and concern.
 

docs/dag/kubernetes/frequently_asked_questions.rst

@@ -103,7 +103,8 @@ Refer to :ref:`Supported backends <Supported backends (storage)>` for more infor
 Does Trident work with Cloud Volumes Services?
 ----------------------------------------------
 
-Yes, Trident supports the Azure NetApp Files service in Azure as well as the Cloud Volumes Service in AWS.
+Yes, Trident supports the Azure NetApp Files service in Azure as well as the Cloud Volumes Service in AWS
+and GCP.
 
 Refer to :ref:`Supported backends <Supported backends (storage)>` for more information.
 
@@ -169,6 +170,14 @@ Configure it in the backend.json file as
 `"managementLIF": <ip address>:<port>"` For example, if the IP address of your management LIF is 192.0.2.1, and the
 port is 1000, configure ``"managementLIF": "192.0.2.1:1000"``,
 
+Can IPv6 addresses be used for the Management and Data LIFs?
+------------------------------------------------------------
+
+Yes. Trident 20.01 supports defining IPv6 addresses for the ``managementLIF`` and
+``dataLIF`` parameters for ONTAP backends. You must make sure that the address
+follows IPv6 semantics and the ``managementLIF`` is defined within square brackets,
+(e.g. ``[ec0d:6504:a9c1:ae67:53d1:4bdf:ab32:e233]``). You must also ensure that
+Trident is installed using the ``--use-ipv6`` flag for it to function over IPv6.
 
 Is it possible to update the Management LIF on the backend ?
 ------------------------------------------------------------
@@ -308,13 +317,14 @@ PVC protection is automatically enabled on Kubernetes starting from version 1.10
 Refer to `Storage Object in Use Protection <https://v1-14.docs.kubernetes.io/docs/tasks/administer-cluster/storage-object-in-use-protection/>`_ for additional information.
 
 
-Can we use PVC resize functionality with NFS, Trident, and ONTAP?
------------------------------------------------------------------
+Can I grow NFS PVCs that were created by Trident?
+-------------------------------------------------
 
-PVC resize is supported with Trident. Note that `volume autogrow` is an ONTAP feature that is not applicable to
+Yes. You can expand a PVC that has been created by Trident.
+Note that `volume autogrow` is an ONTAP feature that is not applicable to
 Trident.
 
-Refer to :ref:`Resizing Volumes <Resizing an NFS volume>` for more information.
+Refer to :ref:`Expanding NFS Volumes <Expanding an NFS volume>` for more information.
 
 
 If I have a volume that was created outside Trident can I import it into Trident?
@@ -339,11 +349,12 @@ Make sure to remove the DP mode or put the volume online before importing the vo
 Refer to: :ref:`Behavior of Drivers for Volume Import <Behavior of Drivers for Volume Import>` for additional information.
 
 
-Can we use PVC resize functionality with iSCSI, Trident, and ONTAP?
--------------------------------------------------------------------
-
-PVC resize functionality with iSCSI is not supported with Trident.
+Can I expand iSCSI PVCs that were created by Trident?
+-----------------------------------------------------
 
+Trident 19.10 support expanding iSCSI PVs using the CSI Provisioner. Refer to
+:ref:`Expanding an iSCSI volume <Expanding an iSCSI volume>` for details on how
+it works.
 
 How is resource quota translated to a NetApp cluster?
 -----------------------------------------------------
@@ -355,7 +366,7 @@ Can you create Volume Snapshots using Trident?
 ----------------------------------------------
 
 Yes. On-demand volume snapshotting and creating Persistent Volumes from Snapshots is supported
-by Trident beginning with 19.07. To create PVs from snapshots, ensure that the ``VolumeSnapshotDataSource``
+by Trident. To create PVs from snapshots, ensure that the ``VolumeSnapshotDataSource``
 feature-gate has been enabled.
 
 Refer to :ref:`On-Demand Volume Snapshots <On-Demand Volume Snapshots>`
@@ -364,13 +375,17 @@ for more information.
 What are the drivers which support Trident Volume Snapshots?
 ------------------------------------------------------------
 
-As of today, on-demand snapshot support is available for our ``ontap-nas``, ``ontap-san``, ``solidfire-san``,
+As of today, on-demand snapshot support is available for our ``ontap-nas``,
+``ontap-san``, ``ontap-san-economy``, ``solidfire-san``,
 ``aws-cvs``, ``gcp-cvs``, and ``azure-netapp-files`` backend drivers.
 
 How do we take a snapshot backup of a volume provisioned by Trident with ONTAP?
 -------------------------------------------------------------------------------
 This is available on ``ontap-nas``, ``ontap-san``, and ``ontap-nas-flexgroup`` drivers.
 
+You can also specify a `snapshotPolicy` for the ``ontap-san-economy`` driver at the FlexVol
+level.
+
 This is also available on the ``ontap-nas-economy`` drivers but on the FlexVol level granularity and not on the qtree level granularity.
 
 To enable the ability to snapshot volumes provisioned by Trident, set the backend parameter option `snapshotPolicy`
@@ -431,13 +446,14 @@ storage class per namespace by using
 `Storage Resource Quotas <https://kubernetes.io/docs/concepts/policy/resource-quotas/#storage-resource-quota>`_  which
 are per namespace. To deny a specific namespace access to specific storage, set the resource quota to 0 for that storage class.
 
-
-Does Trident provide insight into the capacity of the storage?
+Can I obtain metrics on how storage is provisioned by Trident?
 --------------------------------------------------------------
 
-This is out of scope for Trident. NetApp offers `Cloud Insights <https://cloud.netapp.com/cloud-insights>`_ for
-monitoring and analysis.
-
+Yes. Trident 20.01 introduces Prometheus endpoints that can be used to
+gather information on Trident's operation, such as the number of backends
+managed, the number of volumes provisoned, bytes consumed and so on.
+You can also use `Cloud Insights <https://cloud.netapp.com/cloud-insights>`_ for
+monitoring and analysis. Refer to :ref:`Monitoring Trident <Monitoring Trident>`.
 
 Does the user experience change when using Trident as a CSI Provisioner?
 ------------------------------------------------------------------------
@@ -447,8 +463,8 @@ and functionalities are concerned. The provisioner name used will be ``csi.tride
 This method of installing Trident is recommended to use all new features provided by current
 and future releases.
 
-How do I design a Disaster Workflow for Trident v19.10?
--------------------------------------------------------
+How do I design a Disaster Workflow for Trident?
+------------------------------------------------
 
 The :ref:`Data replication using ONTAP <Data replication using ONTAP>` section
 talks about backup and DR workflows using ONTAP.
@@ -526,8 +542,9 @@ you must have a NetApp backend storage device.
 Can I upgrade from a older version of Trident directly to a newer version (skipping a few versions)?
 ----------------------------------------------------------------------------------------------------
 
-We support upgrading directly from a version up to one year back. For example, if you are currently on v18.04, v18.07,
-or v19.01, we will support directly upgrading to v19.04. We suggest testing upgrading in a lab prior to production deployment.
+NetApp supports upgrading Trident from one major release to the next immediate major
+release. You can upgrade Trident from version 18.xx to 19.xx, 19.xx to 20.xx and
+so on. We suggest testing upgrading in a lab prior to production deployment.
 Information on upgrading Trident can be obtained :ref:`here <Upgrading Trident>`.
 
 
@@ -541,7 +558,9 @@ Upgrading Trident to the latest release.
 Is it possible to downgrade Trident to a previous release?
 ----------------------------------------------------------
 
-**Downgrading Trident is not recommended** for the :ref:`following reasons <Downgrading Trident>`.
+There are a number of factors to be evaluated if you would like to downgrade.
+Take a look at this section on :ref:`downgrading Trident <Downgrading Trident>`.
+
 
 If the Trident pod is destroyed, will we lose the data?
 -------------------------------------------------------

docs/dag/kubernetes/integrating_trident.rst

@@ -202,7 +202,8 @@ Please refer to :ref:`Trident StorageClass Objects <Trident StorageClass objects
 
 Storage Class Design for Virtual Storage Pools
 ----------------------------------------------
-Virtual Storage Pools are available for Cloud Volumes Service for AWS, ANF, Element and E-Series backends.
+Virtual Storage Pools are available for all Trident backends. You can define Virtual Storage Pools
+for any backend, using any driver that Trident provides.
 
 Virtual Storage Pools allow an administrator to create a level of abstraction over backends which can be referenced through Storage Classes, for greater flexibility and efficient placement of volumes on backends. Different backends can be defined with the same class of service. Moreover, multiple Storage Pools can be created on the same backend but with different characteristics. When a Storage Class is configured with a selector with the specific labels , Trident chooses a backend which matches all the selector labels to place the volume. If the Storage Class selector labels matches multiple Storage Pools, Trident will choose one of them to provision the volume from.
 
@@ -211,7 +212,17 @@ Please refer to :ref:`Virtual Storage Pools <Virtual Storage Pools>` for more in
 Virtual Storage Pool Design
 ===========================
 
-While creating a backend , you can generally specify a set of parameters. It was impossible for the administrator to create another backend with the same storage credentials and with a different set of parameters. With the introduction of Virtual Storage Pools , this issue has been alleviated. Virtual Storage Pools is a level abstraction introduced between the backend and the Kubernetes Storage Class so that the administrator can define parameters along with labels which can be referenced through Kubernetes Storage Classes as a selector, in a backend-agnostic way. Currently Virtual Storage Pool is supported for Cloud Volumes Service for AWS , E-Series and SolidFire.
+While creating a backend , you can generally specify a set of parameters. It was impossible for the administrator to create another backend with the same storage credentials and with a different set of parameters. With the introduction of Virtual Storage Pools , this issue has been alleviated. Virtual Storage Pools is a level abstraction introduced between the backend and the Kubernetes Storage Class so that the administrator can define parameters along with labels which can be referenced through Kubernetes Storage Classes as a selector, in a backend-agnostic way.
+Virtual Storage Pools can be defined for all supported NetApp backends with Trident. That list
+includes E-Series, SolidFire/HCI, ONTAP, Cloud Volumes Service on AWS and GCP, as well as Azure
+NetApp Files.
+
+.. note::
+
+   When defining Virtual Storage Pools, it is recommended to not attempt to rearrange
+   the order of existing virtual pools in a backend definition. It is also advisable
+   to not edit/modify attributes for an existing virtual pool and define a new virtual
+   pool instead.
 
 Design Virtual Storage Pools for emulating different Service Levels/QoS
 -----------------------------------------------------------------------
@@ -303,12 +314,13 @@ Trident supports resizing NFS and iSCSI PVs, beginning with the ``18.10`` and ``
 releases respectively. This enables users to resize their volumes directly through
 the Kubernetes layer. Volume expansion is possible for all major NetApp storage platforms,
 including ONTAP, Element/HCI and Cloud Volumes Service backends.
-Take a look at the :ref:`Resizing an NFS volume` and
-:ref:`Resizing an iSCSI volume` for examples and conditions that must be met.
+Take a look at the :ref:`Expanding an NFS volume` and
+:ref:`Expanding an iSCSI volume` for examples and conditions that must be met.
 To allow possible expansion later, set `allowVolumeExpansion` to `true` in your StorageClass associated with the volume. Whenever the Persistent Volume needs to be resized, edit the ``spec.resources.requests.storage`` annotation in the Persistent Volume Claim to the required volume size. Trident will automatically take care of resizing the volume on the storage cluster.
+
 .. note::
+
    1. Resizing iSCSI PVs requires Kubernetes 1.16 and Trident 19.10 or later.
-
    2. Kubernetes, prior to version 1.12, does not support PV resize as the admission controller may reject PVC size updates. The Trident team has changed Kubernetes to allow such changes starting with Kubernetes 1.12. While we recommend using Kubernetes 1.12, it is still possible to resize NFS PVs for earlier versions of Kubernetes that support resize. This is done by disabling the PersistentVolumeClaimResize admission plugin when the Kubernetes API server is started.
 
 

docs/dag/kubernetes/security_recommendations.rst

@@ -7,12 +7,37 @@ Security Recommendations
 Run Trident in its own namespace
 ---------------------------------
 
-It is important to prevent applications, application admins, users, and management applications from accessing Trident object definitions or the pods to ensure reliable storage and block potential malicious activity. To separate out the other applications and users from Trident, always install Trident in its own Kubernetes namespace. In our :ref:`Installing Trident docs <Install Trident>` we call this namespace `trident`. Putting Trident in its own namespace assures that only the Kubernetes administrative personnel have access to the Trident pod and the artifacts (such as backend and CHAP secrets if applicable) stored in Trident's etcd datastore. Allow only administrators access to the trident namespace and thus access to `tridentctl` application.
+It is important to prevent applications, application admins, users, and
+management applications from accessing Trident object definitions or the
+pods to ensure reliable storage and block potential malicious activity.
+To separate out the other applications and users from Trident, always
+install Trident in its own Kubernetes namespace. In our
+:ref:`Installing Trident docs <Install Trident>` we call this namespace
+`trident`. Putting Trident in its own namespace assures that only the
+Kubernetes administrative personnel have access to the Trident pod and
+the artifacts (such as backend and CHAP secrets if applicable) stored
+in the namespaced CRD objects. Allow only administrators access to the
+Trident namespace and thus access to `tridentctl` application.
 
 CHAP authentication
 -------------------
 
-NetApp recommends deploying bi-directional CHAP to ensure authentication between a host and the HCI/SolidFire backend. Trident uses a secret object that includes two CHAP passwords per tenant. Kubernetes manages the mapping of Kubernetes tenant to SF tenant. Upon volume creation time, Trident makes an API call to the HCI/SolidFire system to retrieve the secrets if the secret for that tenant doesn’t already exist. Trident then passes the secrets on to Kubernetes. The kubelet located on each node accesses the secrets via the Kubernetes API and uses them to run/enable CHAP between each node accessing the volume and the HCI/SolidFire system where the volumes are located.
+.. note::
 
-Since Trident v18.10, the ``solidfire-san`` driver defaults to use CHAP if the Kubernetes version is >= 1.7 and a Trident access group doesn't exist. Setting `AccessGroup` or `UseCHAP` in the backend configuration file overrides this behavior. CHAP is guaranteed by setting ``UseCHAP`` to ``true`` in the backend.json file.
+   Trident will only use CHAP when installed as a CSI Provisioner. 
 
+NetApp recommends deploying bi-directional CHAP to ensure authentication
+between a host and the HCI/SolidFire backend. Trident uses a secret
+object that includes two CHAP passwords per tenant. When Trident is installed
+as a CSI Provisioner, it manages the CHAP secrets and stores them in a
+``tridentvolume`` CR object for the respective PV. When a PV is created,
+CSI Trident uses the CHAP secrets to initiate an iSCSI session and communicate with
+the HCI/SolidFire system over CHAP.
+
+In the non-CSI frontend, the attachment of volumes as devices on the worker
+nodes is handled by Kubernetes. Upon volume creation time, Trident makes an API call to
+the HCI/SolidFire system to retrieve the secrets if the secret for that tenant
+doesn’t already exist. Trident then passes the secrets on to Kubernetes. The kubelet
+located on each node accesses the secrets via the Kubernetes API and uses them to
+run/enable CHAP between each node accessing the volume and the HCI/SolidFire system
+where the volumes are located.