Backend management using kubectl

docs/frequently_asked_questions.rst

@@ -35,7 +35,7 @@ for a step by step procedure.
 Can Trident be installed remotely?
 ----------------------------------
 
-Trident v18.10 and above supports :ref:`remote install capability <Trident installation modes>` from any machine that has kubectl access to the cluster. After kubectl access is verified (e.g. initiate a `kubectl get nodes` command from the remote machine to verify), follow the installation instructions.
+Trident v18.10 and above supports :ref:`remote install capability <Trident installation modes>` from any machine that has ``kubectl`` access to the cluster. After ``kubectl`` access is verified (e.g. initiate a `kubectl get nodes` command from the remote machine to verify), follow the installation instructions.
 
 Refer to :ref:`Deploying <Deploying>` for more information on how to install Trident.
 
@@ -152,6 +152,58 @@ Trident Backend Configuration and Use
 
 This section covers Trident backend definition file configurations and use.
 
+How do I create a backend?
+--------------------------
+
+Users have two unique ways of creating a backend:
+
+* Using ``kubectl``: Refer to :ref:`Backend Management with kubectl <manage_tbc_backend>`
+  to understand how this works.
+* Using ``tridentctl``: Users can alternatively choose to create and manage backends using
+  ``tridentctl``. Backends can be created using ``tridentctl create`` and updated with
+  ``tridentctl update``. Refer to :ref:`Backend operations with tridentctl <tridentctl-backend-management>`
+  for more information.
+
+Both options are **independent** of how Trident was installed and work the same
+for Operator/Helm/``tridentctl`` installations.
+
+How do I create and manage backends with ``kubectl``?
+-----------------------------------------------------
+
+Using the ``TridentBackendConfig`` (``tbc``) Custom Resource Definition (CRD). The ``TridentBackendConfig`` CR format is new, however, it understands existing backend configuration inputs that users use today for creating backends and also includes a couple of new fields, such as ``credentials`` and ``deletionPolicy``.
+
+The ``TridentBackendConfig`` CR itself does not represent a backend, creating one results either in a new Trident backend (tbe CR that Trident creates) or binding to an existing Trident backend.
+
+Take a look at :ref:`Backend Management with kubectl <manage_tbc_backend>` to get started.
+
+Can I create backends with both ``kubectl`` and ``tridentctl``?
+---------------------------------------------------------------
+
+Yes. Backends that are created using ``TridentBackendConfigs`` will be managed using ``kubectl``.
+Backends created with ``tridentctl`` will need to be managed with ``tridentctl``.
+
+Can I use ``tridentctl`` to manage ``TridentBackendConfig``-based backends?
+---------------------------------------------------------------------------
+
+You cannot use ``tridentctl`` to perform ``create``, ``modify``, and ``delete``
+operations on ``TridentBackendConfig``-based backends. However, you can perform the
+``get`` operation on successfully created ``TridentBackendConfig``-based backends.
+
+If the ``deletionPolicy`` is set to ``retain``, ``TridentBackendConfig`` objects
+can be deleted and associated backends can be managed with ``tridentctl``.
+
+Take a look at :ref:`Managing TridentBackendConfig backends using tridentctl <kubectl-to-tridentctl>`.
+
+Can I use ``TridentBackendConfig`` to manage ``tridentctl``-based backends?
+---------------------------------------------------------------------------
+
+No, you cannot use ``TridentBackendConfig`` to perform ``create``, ``get``,
+``modify``, and ``delete`` operations on ``tridentctl``-based backends.
+Users can choose to bind existing backends [created using ``tridentctl``] to a new
+``TridentBackendConfig`` CR and manage them **using** the CR and **not using** ``tridentctl``.
+
+Take a look at :ref:`Managing tridentctl backends using TridentBackendConfig <tridentctl-to-kubectl>`.
+
 Do we need to define both Management and Data LIFs in an ONTAP backend definition file?
 ---------------------------------------------------------------------------------------
 
@@ -269,7 +321,7 @@ How does Trident deploy Qtrees on an ONTAP volume? How many Qtrees can be deploy
 The ``ontap-nas-economy`` driver will create 200 Qtrees in the same FlexVol by default (configurable between 50 and 300), and the ``ontap-san-economy`` driver will create 100 LUNs in the same FlexVol by default (configurable between 50 and 200),
 100,000 Qtrees per cluster node, and 2.4M per cluster. When you enter a new PersistentVolumeClaim that is serviced by
 the economy driver, the driver looks to see if a FlexVol already exists that can service the new Qtree. If the FlexVol
-does not exist that can service the Qtree, a new FlexVol will be created. 
+does not exist that can service the Qtree, a new FlexVol will be created.
 
 Refer to :ref:`Choosing a driver <Choosing a driver>` for more information.
 

docs/kubernetes/operations/tasks/backends/index.rst

@@ -9,8 +9,8 @@ should provision volumes from it.
 Trident will automatically offer up storage pools from backends that together
 match the requirements defined by a storage class.
 
-To get started, choose the storage system type that you will be using as a
-backend:
+Choose the storage system type that you will be using as a backend, and create the backend using one of the options
+described :ref:`here <backend-management>`.
 
 .. toctree::
    :maxdepth: 2

docs/kubernetes/operations/tasks/index.rst

@@ -9,6 +9,6 @@ Common tasks
   monitoring
   worker
   backends/index
-  backends
+  managing-backends/index
   storage-classes
   volumes/index

docs/kubernetes/operations/tasks/managing-backends/backend-operations.rst

@@ -0,0 +1,208 @@
+###########################
+Handling backend operations
+###########################
+
+Users have two unique options for managing backends:
+
+* Using ``kubectl``: Using the ``TridentBackendConfig`` CRD,
+  backends can be created directly using the Kubernetes CLI.
+  :ref:`This section <kubectl-backend-management>` explains how operations are
+  handled. In addition, :ref:`Manage Trident backends by using kubectl <manage_tbc_backend>`
+  talks about the ``TridentBackendConfig`` CRD and explains how it works.
+* Using ``tridentctl``: Trident provides a dedicated command-line tool (``tridentctl``)
+  that can be used to manage backends. :ref:`This section <tridentctl-backend-management>`
+  explains the various operations that can be performed.
+
+Creating a backend configuration
+--------------------------------
+
+We have an entire :ref:`backend configuration <Backend configuration>` guide to
+help you with this.
+
+.. _kubectl-backend-management:
+
+Backend operations with ``kubectl``
+-----------------------------------
+
+Creating a backend
+==================
+
+Run the following command:
+
+.. code-block:: bash
+
+  $ kubectl create -f <tbc-backend-file.yaml> -n trident
+
+If you did not specify the ``backendName`` field  in the ``spec``, it defaults
+to the ``.metadata.name`` of the ``TridentBackendConfig`` CR.
+
+If the backend creation fails, you can run one of the following commands to view the logs:
+
+.. code-block:: bash
+
+  $ kubectl get tbc <tbc-name> -o yaml -n trident
+
+Alternatively, you can use the ``kubectl -n trident describe tbc <tbc-name>`` command to get details of the event logs.
+
+Deleting a backend
+==================
+
+By deleting a ``TridentBackendConfig``, users instruct Trident to delete/retain
+backends (based on the ``deletionPolicy``) as well as deleting the ``TridentBackendConfig``.
+To delete a backend, ensure that ``deletionPolicy`` is set to ``delete``.
+To delete just the ``TridentBackendConfig``, ensure that ``deletionPolicy`` is set
+to ``retain``. This will ensure the backend is still present and manageable through
+``tridentctl``.
+
+Run the following command:
+
+.. code-block:: bash
+
+  $ kubectl delete tbc <tbc-name> -n trident
+
+Trident does not delete the Kubernetes Secrets that were in use by the
+``TridentBackendConfig``. The Kubernetes user is responsible for cleaning up secrets.
+Care must be taken when deleting secrets; only delete secrets if they are **not in
+use** by Trident backends.
+
+Viewing the existing backends
+=============================
+
+To view the backends that have been created through ``kubectl``:
+
+.. code-block:: bash
+
+  $ kubectl get tbc -n trident
+
+You can also run ``tridentctl get backend -n trident`` or ``tridentctl get backend -o yaml -n trident``
+to obtain a list all backends that exist. This list will also include backends that
+were created with ``tridentctl``.
+
+Updating a backend
+==================
+
+There can be multiple reasons to update a backend:
+
+1. Credentials to the storage system have changed.
+2. Parameters (such as the name of the ONTAP SVM being used) need to be updated.
+
+In the case of (1), the Kubernetes Secret that is used in the ``TridentBackendConfig``
+object must be updated. Trident will automatically update the backend with the
+latest credentials provided.
+
+.. code-block:: bash
+
+  # Credentials need to be updated?
+  $ kubectl apply -f <updated-secret-file.yaml> -n trident
+
+In the case of (2), ``TridentBackendConfig`` objects can be updated directly
+through Kubernetes.
+
+.. code-block:: bash
+
+  # TridentBackendConfig needs to be updated?
+  $ kubectl apply -f <updated-backend-file.yaml>
+
+Alternatively, make changes to the existing ``TridentBackendConfig`` CR by running:
+
+.. code-block:: bash
+
+  # TridentBackendConfigs can be edited using kubectl
+  $ kubectl edit tbc <tbc-name> -n trident
+
+If a backend update fails, the backend continues to remain in its last known configuration.
+You can view the logs to determine the cause by running ``kubectl get tbc <tbc-name> -o yaml -n trident``
+or ``kubectl describe tbc <tbc-name> -n trident``.
+
+After you identify and correct the problem with the configuration file, you can re-run the update command.
+
+.. _tridentctl-backend-management:
+
+Backend operations with ``tridentctl``
+--------------------------------------
+
+Use the information below to manage backends with ``tridentctl``.
+
+Creating a backend
+==================
+
+Once you have a :ref:`backend configuration <Backend configuration>` file, run:
+
+.. code-block:: bash
+
+  $ tridentctl create backend -f <backend-file> -n trident
+
+If backend creation fails, something was wrong with the backend configuration.
+You can view the logs to determine the cause by running:
+
+.. code-block:: bash
+
+  $ tridentctl logs -n trident
+
+Once you identify and correct the problem with the configuration file you can
+simply run the create command again.
+
+Deleting a backend
+==================
+
+.. note::
+
+  If Trident has provisioned volumes and snapshots from this backend that still exist,
+  deleting the backend will prevent new volumes from being provisioned by it.
+  The backend will continue to exist in a "Deleting" state and Trident
+  will continue to manage those volumes and snapshots until they are deleted.
+
+To delete a backend from Trident, run:
+
+.. code-block:: bash
+
+  # Retrieve the backend name
+  $ tridentctl get backend -n trident
+
+  $ tridentctl delete backend <backend-name> -n trident
+
+Viewing the existing backends
+=============================
+
+To view the backends that Trident knows about, run:
+
+.. code-block:: bash
+
+  # Summary
+  $ tridentctl get backend -n trident
+
+  # Full details
+  $ tridentctl get backend -o json -n trident
+
+Updating a backend
+==================
+
+Once you have a new :ref:`backend configuration <Backend configuration>` file, run:
+
+.. code-block:: bash
+
+  $ tridentctl update backend <backend-name> -f <backend-file> -n trident
+
+If backend update fails, something was wrong with the backend configuration or
+you attempted an invalid update.
+You can view the logs to determine the cause by running:
+
+.. code-block:: bash
+
+  $ tridentctl logs -n trident
+
+Once you identify and correct the problem with the configuration file you can
+simply run the update command again.
+
+Identifying the storage classes that will use a backend
+-------------------------------------------------------
+
+This is an example of the kind of questions you can answer with the JSON that
+``tridentctl`` outputs for Trident backend objects. This uses the ``jq``
+utility, which you may need to install first.
+
+.. code-block:: bash
+
+  $ tridentctl get backend -o json | jq '[.items[] | {backend: .name, storageClasses: [.storage[].storageClasses]|unique}]'
+
+This also applies for backends that were created using ``TridentBackendConfig``.