FSx for ONTAP configuration options and examples

10/29/2024 Contributors

Learn about backend configuration options for Amazon FSx for ONTAP. This section provides backend configuration examples.

Backend configuration options

See the following table for the backend configuration options:

Parameter Description Example

Parameter	Description	Example
`version`		Always 1
`storageDriverName`	Name of the storage driver	`ontap-nas`, `ontap-nas-economy`, `ontap-nas-flexgroup`, `ontap-san`, `ontap-san-economy`
`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].	“10.0.0.1”, “[2001:1234:abcd::fefe]”
`dataLIF`	IP address of protocol LIF. ONTAP NAS drivers: We recommend specifying dataLIF. If not provided, Trident fetches data LIFs 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 data LIFs. Can be changed after initial setting. Refer to Update `dataLIF` after initial configuration. ONTAP SAN drivers: Do not specify for iSCSI. Trident uses ONTAP Selective LUN Map to discover the iSCI LIFs needed to establish a multi path session. A warning is generated if dataLIF is explicitly defined. 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].
`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 authentication.	""
`username`	Username to connect to the cluster or SVM. Used for credential-based authentication. For example, vsadmin.
`password`	Password to connect to the cluster or SVM. Used for credential-based authentication.
`svm`	Storage virtual machine to use	Derived if an SVM managementLIF is specified.
`storagePrefix`	Prefix used when provisioning new volumes in the SVM. Cannot be modified after creation. To update this parameter, you will need to create a new backend.	`trident`
`limitAggregateUsage`	Do not specify for Amazon FSx for NetApp ONTAP. The provided `fsxadmin` and `vsadmin` do not contain the permissions required to retrieve aggregate usage and limit it using Trident.	Do not use.
`limitVolumeSize`	Fail provisioning if requested volume size is above this value. Also restricts the maximum size of the volumes it manages for qtrees and LUNs, and the `qtreesPerFlexvol` option allows customizing the maximum number of qtrees per FlexVol.	“” (not enforced by default)
`lunsPerFlexvol`	Maximum LUNs per Flexvol, must be in range [50, 200]. SAN only.	`100`
`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
`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.	""
`nasType`	Configure NFS or SMB volumes creation. Options are `nfs`, `smb`, or null. Must set to `smb` for SMB volumes. Setting to null defaults to NFS volumes.	`nfs`
`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 or a name to allow Trident to create the SMB share. This parameter is required for Amazon FSx for ONTAP backends.	`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 ONTAP 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 `ontap` 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, `userREST` is set to `true` by default; change `useREST` to `false` to use ONTAP ZAPI calls.	`true` for ONTAP 9.15.1 or later, otherwise `false`.
`aws`	You can specify the following in the configuration file for AWS FSx for ONTAP: - `fsxFilesystemID`: Specify the ID of the AWS FSx file system. - `apiRegion`: AWS API region name. - `apikey`: AWS API key. - `secretKey`: AWS secret key.	`""` `""` `""`
`credentials`	Specify the FSx SVM credentials to store in AWS Secret Manager. - `name`: Amazon Resource Name (ARN) of the secret, which contains the credentials of SVM. - `type`: Set to `awsarn`. Refer to Create an AWS Secrets Manager secret for more information.

version

Always 1

storageDriverName

Name of the storage driver

ontap-nas, ontap-nas-economy, ontap-nas-flexgroup, ontap-san, ontap-san-economy

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].

“10.0.0.1”, “[2001:1234:abcd::fefe]”

dataLIF

IP address of protocol LIF.

ONTAP NAS drivers: We recommend specifying dataLIF. If not provided, Trident fetches data LIFs 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 data LIFs. Can be changed after initial setting. Refer to Update dataLIF after initial configuration.

ONTAP SAN drivers: Do not specify for iSCSI. Trident uses ONTAP Selective LUN Map to discover the iSCI LIFs needed to establish a multi path session. A warning is generated if dataLIF is explicitly defined.

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].

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 authentication.

username

Username to connect to the cluster or SVM. Used for credential-based authentication. For example, vsadmin.

password

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

svm

Storage virtual machine to use

Derived if an SVM managementLIF is specified.

storagePrefix

Prefix used when provisioning new volumes in the SVM.

Cannot be modified after creation. To update this parameter, you will need to create a new backend.

trident

limitAggregateUsage

Do not specify for Amazon FSx for NetApp ONTAP.

The provided fsxadmin and vsadmin do not contain the permissions required to retrieve aggregate usage and limit it using Trident.

Do not use.

limitVolumeSize

Fail provisioning if requested volume size is above this value.

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

“” (not enforced by default)

lunsPerFlexvol

Maximum LUNs per Flexvol, must be in range [50, 200].

SAN only.

100

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

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.

nasType

Configure NFS or SMB volumes creation.

Options are nfs, smb, or null.

Must set to smb for SMB volumes. Setting to null defaults to NFS volumes.

nfs

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 or a name to allow Trident to create the SMB share.

This parameter is required for Amazon FSx for ONTAP backends.

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 ONTAP 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 ontap 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, userREST is set to true by default; change useREST to false to use ONTAP ZAPI calls.

true for ONTAP 9.15.1 or later, otherwise false.

aws

You can specify the following in the configuration file for AWS FSx for ONTAP:
- fsxFilesystemID: Specify the ID of the AWS FSx file system.
- apiRegion: AWS API region name.
- apikey: AWS API key.
- secretKey: AWS secret key.

""
""
""

credentials

Specify the FSx SVM credentials to store in AWS Secret Manager.
- name: Amazon Resource Name (ARN) of the secret, which contains the credentials of SVM.
- type: Set to awsarn.
Refer to Create an AWS Secrets Manager secret for more information.

Update `dataLIF` after initial configuration

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

tridentctl update backend <backend-name> -f <path-to-backend-json-file-with-updated-dataLIF>

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 data LIF to take effect.

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

Parameter	Description	Default
`spaceAllocation`	Space-allocation for LUNs	`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 or backend. Using QoS policy groups with Trident requires ONTAP 9.8 or later. You should use a non-shared QoS policy group and ensuring the policy group is applied to each constituent individually. A shared QoS policy group enforces the ceiling for the total throughput of all workloads.	“”
`adaptiveQosPolicy`	Adaptive QoS policy group to assign for volumes created. Choose one of qosPolicy or adaptiveQosPolicy per storage pool or backend. Not supported by ontap-nas-economy.	“”
`snapshotReserve`	Percentage of volume reserved for snapshots “0”	If `snapshotPolicy` is `none`, `else` “”
`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`
`luksEncryption`	Enable LUKS encryption. Refer to Use Linux Unified Key Setup (LUKS). SAN only.	""
`tieringPolicy`	Tiering policy to use `none`	`snapshot-only` for pre-ONTAP 9.5 SVM-DR configuration
`unixPermissions`	Mode for new volumes. Leave empty for SMB volumes.	“"
`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`.

spaceAllocation

Space-allocation for LUNs

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 or backend.

Using QoS policy groups with Trident requires ONTAP 9.8 or later.

You should use a non-shared QoS policy group and ensuring the policy group is applied to each constituent individually. A shared QoS policy group enforces the ceiling for the total throughput of all workloads.

“”

adaptiveQosPolicy

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

Not supported by ontap-nas-economy.

“”

snapshotReserve

Percentage of volume reserved for snapshots “0”

If snapshotPolicy is none, else “”

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

luksEncryption

Enable LUKS encryption. Refer to Use Linux Unified Key Setup (LUKS).

SAN only.

tieringPolicy

Tiering policy to use none

snapshot-only for pre-ONTAP 9.5 SVM-DR configuration

unixPermissions

Mode for new volumes.

Leave empty for SMB volumes.

“"

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.

Example configurations

Configuration of storage class for SMB volumes

Using nasType, node-stage-secret-name, and node-stage-secret-namespace, you can specify an SMB volume and provide the required Active Directory credentials. SMB volumes are supported using the ontap-nas driver only.

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nas-smb-sc
provisioner: csi.trident.netapp.io
parameters:
  backendType: "ontap-nas"
  trident.netapp.io/nasType: "smb"
  csi.storage.k8s.io/node-stage-secret-name: "smbcreds"
  csi.storage.k8s.io/node-stage-secret-namespace: "default"

Configuration for AWS FSx for ONTAP with secret manager

apiVersion: trident.netapp.io/v1
kind: TridentBackendConfig
metadata:
  name: backend-tbc-ontap-nas
spec:
  version: 1
  storageDriverName: ontap-nas
  backendName: tbc-ontap-nas
  svm: svm-name
  aws:
    fsxFilesystemID: fs-xxxxxxxxxx
  managementLIF:
  credentials:
    name: "arn:aws:secretsmanager:us-west-2:xxxxxxxx:secret:secret-name"
    type: awsarn

FSx for ONTAP configuration options and examples

Creating your file...

Backend configuration options

Update dataLIF after initial configuration

Backend configuration options for provisioning volumes

Example configurations

Update `dataLIF` after initial configuration