Skip to main content

Create backends with kubectl

Contributors juliantap netapp-aruldeepa netapp-dbagwell netapp-mwallis
PDFs

A backend defines the relationship between Trident and a storage system. It tells Trident how to communicate with that storage system and how Trident should provision volumes from it. After Trident is installed, the next step is to create a backend. The TridentBackendConfig Custom Resource Definition (CRD) enables you to create and manage Trident backends directly through the Kubernetes interface. You can do this by using kubectl or the equivalent CLI tool for your Kubernetes distribution.

TridentBackendConfig

TridentBackendConfig (tbc, tbconfig, tbackendconfig) is a frontend, namespaced CRD that enables you to manage Trident backends using kubectl. Kubernetes and storage admins can now create and manage backends directly through the Kubernetes CLI without requiring a dedicated command-line utility (tridentctl).

Upon the creation of a TridentBackendConfig object, the following happens:

  • A backend is created automatically by Trident based on the configuration you provide. This is represented internally as a TridentBackend (tbe, tridentbackend) CR.

  • The TridentBackendConfig is uniquely bound to a TridentBackend that was created by Trident.

Each TridentBackendConfig maintains a one-to-one mapping with a TridentBackend. The former is the interface provided to the user to design and configure backends; the latter is how Trident represents the actual backend object.

Warning TridentBackend CRs are created automatically by Trident. You should not modify them. If you want to make updates to backends, do this by modifying the TridentBackendConfig object.

See the following example for the format of the TridentBackendConfig CR:

apiVersion: trident.netapp.io/v1
kind: TridentBackendConfig
metadata:
  name: backend-tbc-ontap-san
spec:
  version: 1
  backendName: ontap-san-backend
  storageDriverName: ontap-san
  managementLIF: 10.0.0.1
  dataLIF: 10.0.0.2
  svm: trident_svm
  credentials:
    name: backend-tbc-ontap-san-secret

You can also take a look at the examples in the trident-installer directory for sample configurations for the desired storage platform/service.

The spec takes backend-specific configuration parameters. In this example, the backend uses the ontap-san storage driver and uses the configuration parameters that are tabulated here. For the list of configuration options for your desired storage driver, refer to the backend configuration information for your storage driver.

The spec section also includes credentials and deletionPolicy fields, which are newly introduced in the TridentBackendConfig CR:

  • credentials: This parameter is a required field and contains the credentials used to authenticate with the storage system/service. This is set to a user-created Kubernetes Secret. The credentials cannot be passed in plain text and will result in an error.

  • deletionPolicy: This field defines what should happen when the TridentBackendConfig is deleted. It can take one of two possible values:

    • delete: This results in the deletion of both TridentBackendConfig CR and the associated backend. This is the default value.

    • retain: When a TridentBackendConfig CR is deleted, the backend definition will still be present and can be managed with tridentctl. Setting the deletion policy to retain lets users downgrade to an earlier release (pre-21.04) and retain the created backends. The value for this field can be updated after a TridentBackendConfig is created.

Note The name of a backend is set using spec.backendName. If unspecified, the name of the backend is set to the name of the TridentBackendConfig object (metadata.name). It is recommended to explicitly set backend names using spec.backendName.
Tip Backends that were created with tridentctl do not have an associated TridentBackendConfig object. You can choose to manage such backends with kubectl by creating a TridentBackendConfig CR. Care must be taken to specify identical config parameters (such as spec.backendName, spec.storagePrefix, spec.storageDriverName, and so on). Trident will automatically bind the newly-created TridentBackendConfig with the pre-existing backend.

Steps overview

To create a new backend by using kubectl, you should do the following:

  1. Create a Kubernetes Secret. The secret contains the credentials Trident needs to communicate with the storage cluster/service.

  2. Create a TridentBackendConfig object. This contains specifics about the storage cluster/service and references the secret created in the previous step.

After you create a backend, you can observe its status by using kubectl get tbc <tbc-name> -n <trident-namespace> and gather additional details.

Step 1: Create a Kubernetes Secret

Create a Secret that contains the access credentials for the backend. This is unique to each storage service/platform. Here's an example:

kubectl -n trident create -f backend-tbc-ontap-san-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: backend-tbc-ontap-san-secret
type: Opaque
stringData:
  username: cluster-admin
  password: t@Ax@7q(>

This table summarizes the fields that must be included in the Secret for each storage platform:

Storage platform Secret Fields description Secret Fields description

Azure NetApp Files

clientID

The client ID from an app registration

Cloud Volumes Service for GCP

private_key_id

ID of the private key. Part of API key for GCP Service Account with CVS admin role

Cloud Volumes Service for GCP

private_key

Private key. Part of API key for GCP Service Account with CVS admin role

Element (NetApp HCI/SolidFire)

Endpoint

MVIP for the SolidFire cluster with tenant credentials

ONTAP

username

Username to connect to the cluster/SVM. Used for credential-based authentication

ONTAP

password

Password to connect to the cluster/SVM. Used for credential-based authentication

ONTAP

clientPrivateKey

Base64-encoded value of client private key. Used for certificate-based authentication

ONTAP

chapUsername

Inbound username. Required if useCHAP=true. For ontap-san and ontap-san-economy

ONTAP

chapInitiatorSecret

CHAP initiator secret. Required if useCHAP=true. For ontap-san and ontap-san-economy

ONTAP

chapTargetUsername

Target username. Required if useCHAP=true. For ontap-san and ontap-san-economy

ONTAP

chapTargetInitiatorSecret

CHAP target initiator secret. Required if useCHAP=true. For ontap-san and ontap-san-economy

The Secret created in this step will be referenced in the spec.credentials field of the TridentBackendConfig object that is created in the next step.

Step 2: Create the TridentBackendConfig CR

You are now ready to create your TridentBackendConfig CR. In this example, a backend that uses the ontap-san driver is created by using the TridentBackendConfig object shown below:

kubectl -n trident create -f backend-tbc-ontap-san.yaml
apiVersion: trident.netapp.io/v1
kind: TridentBackendConfig
metadata:
  name: backend-tbc-ontap-san
spec:
  version: 1
  backendName: ontap-san-backend
  storageDriverName: ontap-san
  managementLIF: 10.0.0.1
  dataLIF: 10.0.0.2
  svm: trident_svm
  credentials:
    name: backend-tbc-ontap-san-secret

Step 3: Verify the status of the TridentBackendConfig CR

Now that you created the TridentBackendConfig CR, you can verify the status. See the following example:

kubectl -n trident get tbc backend-tbc-ontap-san
NAME                    BACKEND NAME          BACKEND UUID                           PHASE   STATUS
backend-tbc-ontap-san   ontap-san-backend     8d24fce7-6f60-4d4a-8ef6-bab2699e6ab8   Bound   Success

A backend was successfully created and bound to the TridentBackendConfig CR.

Phase can take one of the following values:

  • Bound: The TridentBackendConfig CR is associated with a backend, and that backend contains configRef set to the TridentBackendConfig CR's uid.

  • Unbound: Represented using "". The TridentBackendConfig object is not bound to a backend. All newly created TridentBackendConfig CRs are in this phase by default. After the phase changes, it cannot revert to Unbound again.

  • Deleting: The TridentBackendConfig CR's deletionPolicy was set to delete. When the TridentBackendConfig CR is deleted, it transitions to the Deleting state.

    • If no persistent volume claims (PVCs) exist on the backend, deleting the TridentBackendConfig will result in Trident deleting the backend as well as the TridentBackendConfig CR.

    • If one or more PVCs are present on the backend, it goes to a deleting state. The TridentBackendConfig CR subsequently also enters deleting phase. The backend and TridentBackendConfig are deleted only after all PVCs are deleted.

  • Lost: The backend associated with the TridentBackendConfig CR was accidentally or deliberately deleted and the TridentBackendConfig CR still has a reference to the deleted backend. The TridentBackendConfig CR can still be deleted irrespective of the deletionPolicy value.

  • Unknown: Trident is unable to determine the state or existence of the backend associated with the TridentBackendConfig CR. For example, if the API server is not responding or if the tridentbackends.trident.netapp.io CRD is missing. This might require intervention.

At this stage, a backend is successfully created! There are several operations that can additionally be handled, such as backend updates and backend deletions.

(Optional) Step 4: Get more details

You can run the following command to get more information about your backend:

kubectl -n trident get tbc backend-tbc-ontap-san -o wide
NAME                    BACKEND NAME        BACKEND UUID                           PHASE   STATUS    STORAGE DRIVER   DELETION POLICY
backend-tbc-ontap-san   ontap-san-backend   8d24fce7-6f60-4d4a-8ef6-bab2699e6ab8   Bound   Success   ontap-san        delete

In addition, you can also obtain a YAML/JSON dump of TridentBackendConfig.

kubectl -n trident get tbc backend-tbc-ontap-san -o yaml
apiVersion: trident.netapp.io/v1
kind: TridentBackendConfig
metadata:
  creationTimestamp: "2021-04-21T20:45:11Z"
  finalizers:
  - trident.netapp.io
  generation: 1
  name: backend-tbc-ontap-san
  namespace: trident
  resourceVersion: "947143"
  uid: 35b9d777-109f-43d5-8077-c74a4559d09c
spec:
  backendName: ontap-san-backend
  credentials:
    name: backend-tbc-ontap-san-secret
  managementLIF: 10.0.0.1
  dataLIF: 10.0.0.2
  storageDriverName: ontap-san
  svm: trident_svm
  version: 1
status:
  backendInfo:
    backendName: ontap-san-backend
    backendUUID: 8d24fce7-6f60-4d4a-8ef6-bab2699e6ab8
  deletionPolicy: delete
  lastOperationStatus: Success
  message: Backend 'ontap-san-backend' created
  phase: Bound

backendInfo contains the backendName and the backendUUID of the backend that got created in response to the TridentBackendConfig CR. The lastOperationStatus field represents the status of the last operation of the TridentBackendConfig CR, which can be user-triggered (for example, user changed something in spec) or triggered by Trident (for example, during Trident restarts). It can either be Success or Failed. phase represents the status of the relation between the TridentBackendConfig CR and the backend. In the example above, phase has the value Bound, which means that the TridentBackendConfig CR is associated with the backend.

You can run the kubectl -n trident describe tbc <tbc-cr-name> command to get details of the event logs.

Warning You cannot update or delete a backend which contains an associated TridentBackendConfig object using tridentctl. To understand the steps involved in switching between tridentctl and TridentBackendConfig, see here.