Skip to main content

ONTAP NAS configuration options and examples

Contributors netapp-aruldeepa
PDFs

Learn to create and use ONTAP NAS drivers with your Trident installation. This section provides backend configuration examples and details for mapping backends to StorageClasses.

Backend configuration options

See the following table for the backend configuration options:

Parameter Description Default

version

Always 1

storageDriverName

Name of the storage driver

ontap-nas, ontap-nas-economy, or ontap-nas-flexgroup

backendName

Custom name or the storage backend

Driver name + "_" + dataLIF

managementLIF

IP address of a cluster or SVM management LIF

A fully-qualified domain name (FQDN) can be specified.

Can be set to use IPv6 addresses if Trident was installed using the IPv6 flag. IPv6 addresses must be defined in square brackets, such as [28e8:d9fb:a825:b7bf:69a8:d02f:9e7b:3555].

For seamless MetroCluster switchover, see the MetroCluster example.

"10.0.0.1", "[2001:1234:abcd::fefe]"

dataLIF

IP address of protocol LIF.

NetApp recommends specifying dataLIF. If not provided, Trident fetches dataLIFs from the SVM. You can specify a fully-qualified domain name (FQDN) to be used for the NFS mount operations, allowing you to create a round-robin DNS to load-balance across multiple dataLIFs.

Can be changed after initial setting. Refer to Update dataLIF after initial configuration.

Can be set to use IPv6 addresses if Trident was installed using the IPv6 flag. IPv6 addresses must be defined in square brackets, such as [28e8:d9fb:a825:b7bf:69a8:d02f:9e7b:3555].

Omit for Metrocluster. See the MetroCluster example.

Specified address or derived from SVM, if not specified (not recommended)

svm

Storage virtual machine to use

Omit for Metrocluster. See the MetroCluster example.

Derived if an SVM managementLIF is specified

autoExportPolicy

Enable automatic export policy creation and updating [Boolean].

Using the autoExportPolicy and autoExportCIDRs options, Trident can manage export policies automatically.

false

autoExportCIDRs

List of CIDRs to filter Kubernetes' node IPs against when autoExportPolicy is enabled.

Using the autoExportPolicy and autoExportCIDRs options, Trident can manage export policies automatically.

["0.0.0.0/0", "::/0"]`

labels

Set of arbitrary JSON-formatted labels to apply on volumes

""

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. Cannot be updated after you set it

Note When using ontap-nas-economy and a storagePrefix that is 24 or more characters, the qtrees will not have the storage prefix embedded, though it will be in the volume name.

"trident"

aggregate

Aggregate for provisioning (optional; if set, must be assigned to the SVM). For the ontap-nas-flexgroup driver, this option is ignored. If not assigned, any of the available aggregates can be used to provision a FlexGroup volume.

Note When the aggregate is updated in SVM, it is updated in Trident automatically by polling SVM without having to restart the Trident Controller. When you have configured a specific aggregate in Trident to provision volumes, if the aggregate is renamed or moved out of the SVM, the backend will move to failed state in Trident while polling the SVM aggregate. You must either change the aggregate to one that is present on the SVM or remove it altogether to bring the backend back online.

""

limitAggregateUsage

Fail provisioning if usage is above this percentage.

Does not apply to Amazon FSx for ONTAP

"" (not enforced by default)

flexgroupAggregateList

List of aggregates for provisioning (optional; if set, must be assigned to the SVM). All aggregates assigned to the SVM are used to provision a FlexGroup volume. Supported for the ontap-nas-flexgroup storage driver.

Note When the aggregate list is updated in SVM, the list is updated in Trident automatically by polling SVM without having to restart the Trident Controller. When you have configured a specific aggregate list in Trident to provision volumes, if the aggregate list is renamed or moved out of SVM, the backend will move to failed state in Trident while polling the SVM aggregate. You must either change the aggregate list to one that is present on the SVM or remove it altogether to bring the backend back online.

""

limitVolumeSize

Fail provisioning if requested volume size is above this value.

Also restricts the maximum size of the volumes it manages for qtrees, and the qtreesPerFlexvol option allows customizing the maximum number of qtrees per FlexVol volume

"" (not enforced by default)

debugTraceFlags

Debug flags to use when troubleshooting. Example, {"api":false, "method":true}

Do not use debugTraceFlags unless you are troubleshooting and require a detailed log dump.

null

nasType

Configure NFS or SMB volumes creation.

Options are nfs, smb or null. Setting to null defaults to NFS volumes.

nfs

nfsMountOptions

Comma-separated list of NFS mount options.

The mount options for Kubernetes-persistent volumes are normally specified in storage classes, but if no mount options are specified in a storage class, Trident will fall back to using the mount options specified in the storage backend's configuration file.

If no mount options are specified in the storage class or the configuration file, Trident will not set any mount options on an associated persistent volume.

""

qtreesPerFlexvol

Maximum Qtrees per FlexVol, must be in range [50, 300]

"200"

smbShare

You can specify one of the following: the name of an SMB share created using the Microsoft Management Console or ONTAP CLI; a name to allow Trident to create the SMB share; or you can leave the parameter blank to prevent common share access to volumes.

This parameter is optional for on-premises ONTAP.

This parameter is required for Amazon FSx for ONTAP backends and cannot be blank.

smb-share

useREST

Boolean parameter to use ONTAP REST APIs.

useREST When set to true, Trident uses ONTAP REST APIs to communicate with the backend; when set to false, Trident uses ONTAPI (ZAPI) calls to communicate with the backend. This feature requires ONTAP 9.11.1 and later. In addition, the ONTAP login role used must have access to the ontapi application. This is satisfied by the pre-defined vsadmin and cluster-admin roles.
Beginning with the Trident 24.06 release and ONTAP 9.15.1 or later, useREST is set to true by default; change useREST to false to use ONTAPI (ZAPI) calls.

true for ONTAP 9.15.1 or later, otherwise false.

limitVolumePoolSize

Maximum requestable FlexVol size when using Qtrees in ontap-nas-economy backend.

"" (not enforced by default)

denyNewVolumePools

Restricts ontap-nas-economy backends from creating new FlexVol volumes to contain their Qtrees. Only preexisting Flexvols are used for provisioning new PVs.

Backend configuration options for provisioning volumes

You can control default provisioning using these options in the defaults section of the configuration. For an example, see the configuration examples below.

Parameter Description Default

spaceAllocation

Space-allocation for Qtrees

"true"

spaceReserve

Space reservation mode; "none" (thin) or "volume" (thick)

"none"

snapshotPolicy

Snapshot policy to use

"none"

qosPolicy

QoS policy group to assign for volumes created. Choose one of qosPolicy or adaptiveQosPolicy per storage pool/backend

""

adaptiveQosPolicy

Adaptive QoS policy group to assign for volumes created. Choose one of qosPolicy or adaptiveQosPolicy per storage pool/backend.

Not supported by ontap-nas-economy.

""

snapshotReserve

Percentage of volume reserved for snapshots

"0" if snapshotPolicy is "none", otherwise ""

splitOnClone

Split a clone from its parent upon creation

"false"

encryption

Enable NetApp Volume Encryption (NVE) on the new volume; defaults to false. NVE must be licensed and enabled on the cluster to use this option.

If NAE is enabled on the backend, any volume provisioned in Trident will be NAE enabled.

For more information, refer to: How Trident works with NVE and NAE.

"false"

tieringPolicy

Tiering policy to use "none"

unixPermissions

Mode for new volumes

"777" for NFS volumes; empty (not applicable) for SMB volumes

snapshotDir

Controls access to the .snapshot directory

"true" for NFSv4
"false" for NFSv3

exportPolicy

Export policy to use

"default"

securityStyle

Security style for new volumes.

NFS supports mixed and unix security styles.

SMB supports mixed and ntfs security styles.

NFS default is unix.

SMB default is ntfs.

nameTemplate

Template to create custom volume names.

""
Note Using QoS policy groups with Trident requires ONTAP 9.8 or later. You should use a non-shared QoS policy group and ensure the policy group is applied to each constituent individually. A shared QoS policy group enforces the ceiling for the total throughput of all workloads.

Volume provisioning examples

Here's an example with defaults defined:

---
version: 1
storageDriverName: ontap-nas
backendName: customBackendName
managementLIF: 10.0.0.1
dataLIF: 10.0.0.2
labels:
  k8scluster: dev1
  backend: dev1-nasbackend
svm: trident_svm
username: cluster-admin
password: <password>
limitAggregateUsage: 80%
limitVolumeSize: 50Gi
nfsMountOptions: nfsvers=4
debugTraceFlags:
  api: false
  method: true
defaults:
  spaceReserve: volume
  qosPolicy: premium
  exportPolicy: myk8scluster
  snapshotPolicy: default
  snapshotReserve: "10"

For ontap-nas and ontap-nas-flexgroups, Trident now uses a new calculation to ensure that the FlexVol is sized correctly with the snapshotReserve percentage and PVC. When the user requests a PVC, Trident creates the original FlexVol with more space by using the new calculation. This calculation ensures that the user receives the writable space they requested for in the PVC, and not lesser space than what they requested. Before v21.07, when the user requests a PVC (for example, 5GiB), with the snapshotReserve to 50 percent, they get only 2.5GiB of writeable space. This is because what the user requested for is the whole volume and snapshotReserve is a percentage of that. With Trident 21.07, what the user requests for is the writeable space and Trident defines the snapshotReserve number as the percentage of the whole volume. This does not apply to ontap-nas-economy. See the following example to see how this works:

The calculation is as follows:

Total volume size = (PVC requested size) / (1 - (snapshotReserve percentage) / 100)

For snapshotReserve = 50%, and PVC request = 5GiB, the total volume size is 5/.5 = 10GiB and the available size is 5GiB, which is what the user requested in the PVC request. The volume show command should show results similar to this example:

Shows the output of the volume show command.

Existing backends from previous installs will provision volumes as explained above when upgrading Trident. For volumes that you created before upgrading, you should resize their volumes for the change to be observed. For example, a 2GiB PVC with snapshotReserve=50 earlier resulted in a volume that provides 1GiB of writable space. Resizing the volume to 3GiB, for example, provides the application with 3GiB of writable space on a 6 GiB volume.

Minimal configuration examples

The following examples show basic configurations that leave most parameters to default. This is the easiest way to define a backend.

Note If you are using Amazon FSx on NetApp ONTAP with Trident, the recommendation is to specify DNS names for LIFs instead of IP addresses.
ONTAP NAS economy example 
---
version: 1
storageDriverName: ontap-nas-economy
managementLIF: 10.0.0.1
dataLIF: 10.0.0.2
svm: svm_nfs
username: vsadmin
password: password
ONTAP NAS Flexgroup example 
---
version: 1
storageDriverName: ontap-nas-flexgroup
managementLIF: 10.0.0.1
dataLIF: 10.0.0.2
svm: svm_nfs
username: vsadmin
password: password
MetroCluster example

You can configure the backend to avoid having to manually update the backend definition after switchover and switchback during SVM replication and recovery.

For seamless switchover and switchback, specify the SVM using managementLIF and omit the dataLIF and svm parameters. For example:

---
version: 1
storageDriverName: ontap-nas
managementLIF: 192.168.1.66
username: vsadmin
password: password
SMB volumes example 
---
version: 1
backendName: ExampleBackend
storageDriverName: ontap-nas
managementLIF: 10.0.0.1
nasType: smb
securityStyle: ntfs
unixPermissions: ""
dataLIF: 10.0.0.2
svm: svm_nfs
username: vsadmin
password: password
Certificate-based authentication example

This is a minimal backend configuration example. 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.

---
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_
Auto export policy example

This example shows you how you can instruct Trident to use dynamic export policies to create and manage the export policy automatically. This works the same for the ontap-nas-economy and ontap-nas-flexgroup drivers.

---
version: 1
storageDriverName: ontap-nas
managementLIF: 10.0.0.1
dataLIF: 10.0.0.2
svm: svm_nfs
labels:
  k8scluster: test-cluster-east-1a
  backend: test1-nasbackend
autoExportPolicy: true
autoExportCIDRs:
- 10.0.0.0/24
username: admin
password: password
nfsMountOptions: nfsvers=4
IPv6 addresses example

This example shows managementLIF using an IPv6 address.

---
version: 1
storageDriverName: ontap-nas
backendName: nas_ipv6_backend
managementLIF: "[5c5d:5edf:8f:7657:bef8:109b:1b41:d491]"
labels:
  k8scluster: test-cluster-east-1a
  backend: test1-ontap-ipv6
svm: nas_ipv6_svm
username: vsadmin
password: password
Amazon FSx for ONTAP using SMB volumes example

The smbShare parameter is required for FSx for ONTAP using SMB volumes.

---
version: 1
backendName: SMBBackend
storageDriverName: ontap-nas
managementLIF: example.mgmt.fqdn.aws.com
nasType: smb
dataLIF: 10.0.0.15
svm: nfs_svm
smbShare: smb-share
clientCertificate: ZXR0ZXJwYXB...ICMgJ3BhcGVyc2
clientPrivateKey: vciwKIyAgZG...0cnksIGRlc2NyaX
trustedCACertificate: zcyBbaG...b3Igb3duIGNsYXNz
storagePrefix: myPrefix_
Backend configuration example with nameTemplate 
---
version: 1
storageDriverName: ontap-nas
backendName: ontap-nas-backend
managementLIF: <ip address>
svm: svm0
username: <admin>
password: <password>
defaults:
  nameTemplate: "{{.volume.Name}}_{{.labels.cluster}}_{{.volume.Namespace}}_{{.vo\
    lume.RequestName}}"
labels:
  cluster: ClusterA
  PVC: "{{.volume.Namespace}}_{{.volume.RequestName}}"

Examples of backends with virtual pools

In the sample backend definition files shown below, specific defaults are set for all storage pools, such as spaceReserve at none, spaceAllocation at false, and encryption at false. The virtual pools are defined in the storage section.

Trident sets provisioning labels in the "Comments" field. Comments are set on FlexVol for ontap-nas or FlexGroup for ontap-nas-flexgroup. Trident copies all labels present on a virtual pool to the storage volume at provisioning. For convenience, storage administrators can define labels per virtual pool and group volumes by label.

In these examples, some of the storage pools set their own spaceReserve, spaceAllocation, and encryption values, and some pools override the default values.

ONTAP NAS example 
---
version: 1
storageDriverName: ontap-nas
managementLIF: 10.0.0.1
svm: svm_nfs
username: admin
password: <password>
nfsMountOptions: nfsvers=4
defaults:
  spaceReserve: none
  encryption: "false"
  qosPolicy: standard
labels:
  store: nas_store
  k8scluster: prod-cluster-1
region: us_east_1
storage:
  - labels:
      app: msoffice
      cost: "100"
    zone: us_east_1a
    defaults:
      spaceReserve: volume
      encryption: "true"
      unixPermissions: "0755"
      adaptiveQosPolicy: adaptive-premium
  - labels:
      app: slack
      cost: "75"
    zone: us_east_1b
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0755"
  - labels:
      department: legal
      creditpoints: "5000"
    zone: us_east_1b
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0755"
  - labels:
      app: wordpress
      cost: "50"
    zone: us_east_1c
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0775"
  - labels:
      app: mysqldb
      cost: "25"
    zone: us_east_1d
    defaults:
      spaceReserve: volume
      encryption: "false"
      unixPermissions: "0775"
ONTAP NAS FlexGroup example 
---
version: 1
storageDriverName: ontap-nas-flexgroup
managementLIF: 10.0.0.1
svm: svm_nfs
username: vsadmin
password: <password>
defaults:
  spaceReserve: none
  encryption: "false"
labels:
  store: flexgroup_store
  k8scluster: prod-cluster-1
region: us_east_1
storage:
  - labels:
      protection: gold
      creditpoints: "50000"
    zone: us_east_1a
    defaults:
      spaceReserve: volume
      encryption: "true"
      unixPermissions: "0755"
  - labels:
      protection: gold
      creditpoints: "30000"
    zone: us_east_1b
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0755"
  - labels:
      protection: silver
      creditpoints: "20000"
    zone: us_east_1c
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0775"
  - labels:
      protection: bronze
      creditpoints: "10000"
    zone: us_east_1d
    defaults:
      spaceReserve: volume
      encryption: "false"
      unixPermissions: "0775"
ONTAP NAS economy example 
---
version: 1
storageDriverName: ontap-nas-economy
managementLIF: 10.0.0.1
svm: svm_nfs
username: vsadmin
password: <password>
defaults:
  spaceReserve: none
  encryption: "false"
labels:
  store: nas_economy_store
region: us_east_1
storage:
  - labels:
      department: finance
      creditpoints: "6000"
    zone: us_east_1a
    defaults:
      spaceReserve: volume
      encryption: "true"
      unixPermissions: "0755"
  - labels:
      protection: bronze
      creditpoints: "5000"
    zone: us_east_1b
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0755"
  - labels:
      department: engineering
      creditpoints: "3000"
    zone: us_east_1c
    defaults:
      spaceReserve: none
      encryption: "true"
      unixPermissions: "0775"
  - labels:
      department: humanresource
      creditpoints: "2000"
    zone: us_east_1d
    defaults:
      spaceReserve: volume
      encryption: "false"
      unixPermissions: "0775"

Map backends to StorageClasses

The following StorageClass definitions refer to Examples of backends with virtual pools. Using the parameters.selector field, each StorageClass calls out which virtual pools can be used to host a volume. The volume will have the aspects defined in the chosen virtual pool.

  • The protection-gold StorageClass will map to the first and second virtual pool in the ontap-nas-flexgroup backend. These are the only pools offering gold level protection.

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: protection-gold
provisioner: csi.trident.netapp.io
parameters:
  selector: "protection=gold"
  fsType: "ext4"

  • The protection-not-gold StorageClass will map to the third and fourth virtual pool in the ontap-nas-flexgroup backend. These are the only pools offering protection level other than gold.

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: protection-not-gold
provisioner: csi.trident.netapp.io
parameters:
  selector: "protection!=gold"
  fsType: "ext4"

  • The app-mysqldb StorageClass will map to the fourth virtual pool in the ontap-nas backend. This is the only pool offering storage pool configuration for mysqldb type app.

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: app-mysqldb
provisioner: csi.trident.netapp.io
parameters:
  selector: "app=mysqldb"
  fsType: "ext4"

  • TThe protection-silver-creditpoints-20k StorageClass will map to the third virtual pool in the ontap-nas-flexgroup backend. This is the only pool offering silver-level protection and 20000 creditpoints.

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: protection-silver-creditpoints-20k
provisioner: csi.trident.netapp.io
parameters:
  selector: "protection=silver; creditpoints=20000"
  fsType: "ext4"

  • The creditpoints-5k StorageClass will map to the third virtual pool in the ontap-nas backend and the second virtual pool in the ontap-nas-economy backend. These are the only pool offerings with 5000 creditpoints.

    apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: creditpoints-5k
provisioner: csi.trident.netapp.io
parameters:
  selector: "creditpoints=5000"
  fsType: "ext4"

Trident will decide which virtual pool is selected and ensures the storage requirement is met.

Update dataLIF after initial configuration

You can change the dataLIF after initial configuration by running the following command to provide the new backend JSON file with updated dataLIF.

tridentctl update backend <backend-name> -f <path-to-backend-json-file-with-updated-dataLIF>
Note If PVCs are attached to one or multiple pods, you must bring down all corresponding pods and then bring them back up in order to for the new dataLIF to take effect.