Configure a Cloud Volumes Service for Google Cloud backend

10/29/2024 Contributors

Learn how to configure NetApp Cloud Volumes Service for Google Cloud as the backend for your Trident installation using the sample configurations provided.

Google Cloud driver details

Trident provides the gcp-cvs driver to communicate with the cluster. Supported access modes are: ReadWriteOnce (RWO), ReadOnlyMany (ROX), ReadWriteMany (RWX), ReadWriteOncePod (RWOP).

Driver Protocol volumeMode Access modes supported File systems supported

Driver	Protocol	volumeMode	Access modes supported	File systems supported
`gcp-cvs`	NFS	Filesystem	RWO, ROX, RWX, RWOP	`nfs`

gcp-cvs

NFS

Filesystem

RWO, ROX, RWX, RWOP

nfs

Learn about Trident support for Cloud Volumes Service for Google Cloud

Trident can create Cloud Volumes Service volumes in one of two service types:

CVS-Performance: The default Trident service type. This performance-optimized service type is best suited for production workloads that value performance. The CVS-Performance service type is a hardware option supporting volumes with a minimum 100 GiB size. You can choose one of three service levels:
- standard
- premium
- extreme
CVS: The CVS service type provides high zonal availability with limited to moderate performance levels. The CVS service type is a software option that uses storage pools to support volumes as small as 1 GiB. The storage pool can contain up to 50 volumes where all volumes share the capacity and performance of the pool. You can choose one of two service levels:
- standardsw
- zoneredundantstandardsw

What you'll need

To configure and use the Cloud Volumes Service for Google Cloud backend, you need the following:

A Google Cloud account configured with NetApp Cloud Volumes Service
Project number of your Google Cloud account
Google Cloud service account with the netappcloudvolumes.admin role
API key file for your Cloud Volumes Service account

Backend configuration options

Each backend provisions volumes in a single Google Cloud region. To create volumes in other regions, you can define additional backends.

Parameter Description Default

Parameter	Description	Default
`version`		Always 1
`storageDriverName`	Name of the storage driver	"gcp-cvs"
`backendName`	Custom name or the storage backend	Driver name + "_" + part of API key
`storageClass`	Optional parameter used to specify the CVS service type. Use `software` to select the CVS service type. Otherwise, Trident assumes CVS-Performance service type (`hardware`).
`storagePools`	CVS service type only. Optional parameter used to specify storage pools for volume creation.
`projectNumber`	Google Cloud account project number. The value is found on the Google Cloud portal home page.
`hostProjectNumber`	Required if using a shared VPC network. In this scenario, `projectNumber` is the service project, and `hostProjectNumber` is the host project.
`apiRegion`	The Google Cloud region where Trident creates Cloud Volumes Service volumes. When creating cross-region Kubernetes clusters, volumes created in an `apiRegion` can be used in workloads scheduled on nodes across multiple Google Cloud regions. Cross-region traffic incurs an additional cost.
`apiKey`	API key for the Google Cloud service account with the `netappcloudvolumes.admin` role. It includes the JSON-formatted contents of a Google Cloud service account's private key file (copied verbatim into the backend configuration file).
`proxyURL`	Proxy URL if proxy server required to connect to CVS account. The proxy server can either be an HTTP proxy or an HTTPS proxy. For an HTTPS proxy, certificate validation is skipped to allow the usage of self-signed certificates in the proxy server. Proxy servers with authentication enabled are not supported.
`nfsMountOptions`	Fine-grained control of NFS mount options.	"nfsvers=3"
`limitVolumeSize`	Fail provisioning if the requested volume size is above this value.	"" (not enforced by default)
`serviceLevel`	The CVS-Performance or CVS service level for new volumes. CVS-Performance values are `standard`, `premium`, or `extreme`. CVS values are `standardsw` or `zoneredundantstandardsw`.	CVS-Performance default is "standard". CVS default is "standardsw".
`network`	Google Cloud network used for Cloud Volumes Service volumes.	"default"
`debugTraceFlags`	Debug flags to use when troubleshooting. Example, `\{"api":false, "method":true}`. Do not use this unless you are troubleshooting and require a detailed log dump.	null
`allowedTopologies`	To enable cross-region access, your StorageClass definition for `allowedTopologies` must include all regions. For example: `- key: topology.kubernetes.io/region values: - us-east1 - europe-west1`

version

Always 1

storageDriverName

Name of the storage driver

"gcp-cvs"

backendName

Custom name or the storage backend

Driver name + "_" + part of API key

storageClass

Optional parameter used to specify the CVS service type.

Use software to select the CVS service type. Otherwise, Trident assumes CVS-Performance service type (hardware).

storagePools

CVS service type only. Optional parameter used to specify storage pools for volume creation.

projectNumber

Google Cloud account project number. The value is found on the Google Cloud portal home page.

hostProjectNumber

Required if using a shared VPC network. In this scenario, projectNumber is the service project, and hostProjectNumber is the host project.

apiRegion

The Google Cloud region where Trident creates Cloud Volumes Service volumes. When creating cross-region Kubernetes clusters, volumes created in an apiRegion can be used in workloads scheduled on nodes across multiple Google Cloud regions.

Cross-region traffic incurs an additional cost.

apiKey

API key for the Google Cloud service account with the netappcloudvolumes.admin role.

It includes the JSON-formatted contents of a Google Cloud service account's private key file (copied verbatim into the backend configuration file).

proxyURL

Proxy URL if proxy server required to connect to CVS account. The proxy server can either be an HTTP proxy or an HTTPS proxy.

For an HTTPS proxy, certificate validation is skipped to allow the usage of self-signed certificates in the proxy server.

Proxy servers with authentication enabled are not supported.

nfsMountOptions

Fine-grained control of NFS mount options.

"nfsvers=3"

limitVolumeSize

Fail provisioning if the requested volume size is above this value.

"" (not enforced by default)

serviceLevel

The CVS-Performance or CVS service level for new volumes.

CVS-Performance values are standard, premium, or extreme.

CVS values are standardsw or zoneredundantstandardsw.

CVS-Performance default is "standard".

CVS default is "standardsw".

network

Google Cloud network used for Cloud Volumes Service volumes.

"default"

debugTraceFlags

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

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

null

allowedTopologies

To enable cross-region access, your StorageClass definition for allowedTopologies must include all regions.

For example:
- key: topology.kubernetes.io/region values: - us-east1 - europe-west1

Volume provisioning options

You can control default volume provisioning in the defaults section of the configuration file.

Parameter Description Default

Parameter	Description	Default
`exportRule`	The export rules for new volumes. Must be a comma-separated list of any combination of IPv4 addresses or IPv4 subnets in CIDR notation.	"0.0.0.0/0"
`snapshotDir`	Access to the `.snapshot` directory	"false"
`snapshotReserve`	Percentage of volume reserved for snapshots	"" (accept CVS default of 0)
`size`	The size of new volumes. CVS-Performance minimum is 100 GiB. CVS minimum is 1 GiB.	CVS-Performance service type defaults to "100GiB". CVS service type does not set a default but requires a 1 GiB minimum.

exportRule

The export rules for new volumes. Must be a comma-separated list of any combination of IPv4 addresses or IPv4 subnets in CIDR notation.

"0.0.0.0/0"

snapshotDir

Access to the .snapshot directory

"false"

snapshotReserve

Percentage of volume reserved for snapshots

"" (accept CVS default of 0)

size

The size of new volumes.

CVS-Performance minimum is 100 GiB.

CVS minimum is 1 GiB.

CVS-Performance service type defaults to "100GiB".

CVS service type does not set a default but requires a 1 GiB minimum.

CVS-Performance service type examples

The following examples provide sample configurations for the CVS-Performance service type.

Example 1: Minimal configuration

This is the minimum backend configuration using default CVS-Performance service type with the default "standard" service level.

---
version: 1
storageDriverName: gcp-cvs
projectNumber: '012345678901'
apiRegion: us-west2
apiKey:
  type: service_account
  project_id: my-gcp-project
  private_key_id: "<id_value>"
  private_key: |
    -----BEGIN PRIVATE KEY-----
    <key_value>
    -----END PRIVATE KEY-----
  client_email: cloudvolumes-admin-sa@my-gcp-project.iam.gserviceaccount.com
  client_id: '123456789012345678901'
  auth_uri: https://accounts.google.com/o/oauth2/auth
  token_uri: https://oauth2.googleapis.com/token
  auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
  client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/cloudvolumes-admin-sa%40my-gcp-project.iam.gserviceaccount.com

Example 2: Service level configuration

This sample illustrates backend configuration options, including service level, and volume defaults.

---
version: 1
storageDriverName: gcp-cvs
projectNumber: '012345678901'
apiRegion: us-west2
apiKey:
  type: service_account
  project_id: my-gcp-project
  private_key_id: "<id_value>"
  private_key: |
    -----BEGIN PRIVATE KEY-----
    <key_value>
    -----END PRIVATE KEY-----
  client_email: cloudvolumes-admin-sa@my-gcp-project.iam.gserviceaccount.com
  client_id: '123456789012345678901'
  auth_uri: https://accounts.google.com/o/oauth2/auth
  token_uri: https://oauth2.googleapis.com/token
  auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
  client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/cloudvolumes-admin-sa%40my-gcp-project.iam.gserviceaccount.com
proxyURL: http://proxy-server-hostname/
nfsMountOptions: vers=3,proto=tcp,timeo=600
limitVolumeSize: 10Ti
serviceLevel: premium
defaults:
  snapshotDir: 'true'
  snapshotReserve: '5'
  exportRule: 10.0.0.0/24,10.0.1.0/24,10.0.2.100
  size: 5Ti

Example 3: Virtual pool configuration

This sample uses storage to configure virtual pools and the StorageClasses that refer back to them. Refer to Storage class definitions to see how the storage classes were defined.

Here, specific defaults are set for all virtual pools, which set the snapshotReserve at 5% and the exportRule to 0.0.0.0/0. The virtual pools are defined in the storage section. Each individual virtual pool defines its own serviceLevel, and some pools overwrite the default values. Virtual pool labels were used to differentiate the pools based on performance and protection.

---
version: 1
storageDriverName: gcp-cvs
projectNumber: '012345678901'
apiRegion: us-west2
apiKey:
  type: service_account
  project_id: my-gcp-project
  private_key_id: "<id_value>"
  private_key: |
    -----BEGIN PRIVATE KEY-----
    <key_value>
    -----END PRIVATE KEY-----
  client_email: cloudvolumes-admin-sa@my-gcp-project.iam.gserviceaccount.com
  client_id: '123456789012345678901'
  auth_uri: https://accounts.google.com/o/oauth2/auth
  token_uri: https://oauth2.googleapis.com/token
  auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
  client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/cloudvolumes-admin-sa%40my-gcp-project.iam.gserviceaccount.com
nfsMountOptions: vers=3,proto=tcp,timeo=600
defaults:
  snapshotReserve: '5'
  exportRule: 0.0.0.0/0
labels:
  cloud: gcp
region: us-west2
storage:
- labels:
    performance: extreme
    protection: extra
  serviceLevel: extreme
  defaults:
    snapshotDir: 'true'
    snapshotReserve: '10'
    exportRule: 10.0.0.0/24
- labels:
    performance: extreme
    protection: standard
  serviceLevel: extreme
- labels:
    performance: premium
    protection: extra
  serviceLevel: premium
  defaults:
    snapshotDir: 'true'
    snapshotReserve: '10'
- labels:
    performance: premium
    protection: standard
  serviceLevel: premium
- labels:
    performance: standard
  serviceLevel: standard

Storage class definitions

The following StorageClass definitions apply to the virtual pool configuration example. Using parameters.selector, you can specify for each StorageClass the virtual pool used to host a volume. The volume will have the aspects defined in the chosen pool.

Storage class example

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cvs-extreme-extra-protection
provisioner: csi.trident.netapp.io
parameters:
  selector: "performance=extreme; protection=extra"
allowVolumeExpansion: true
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cvs-extreme-standard-protection
provisioner: csi.trident.netapp.io
parameters:
  selector: "performance=premium; protection=standard"
allowVolumeExpansion: true
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cvs-premium-extra-protection
provisioner: csi.trident.netapp.io
parameters:
  selector: "performance=premium; protection=extra"
allowVolumeExpansion: true
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cvs-premium
provisioner: csi.trident.netapp.io
parameters:
  selector: "performance=premium; protection=standard"
allowVolumeExpansion: true
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cvs-standard
provisioner: csi.trident.netapp.io
parameters:
  selector: "performance=standard"
allowVolumeExpansion: true
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cvs-extra-protection
provisioner: csi.trident.netapp.io
parameters:
  selector: "protection=extra"
allowVolumeExpansion: true

The first StorageClass (cvs-extreme-extra-protection) maps to the first virtual pool. This is the only pool offering extreme performance with a snapshot reserve of 10%.
The last StorageClass (cvs-extra-protection) calls out any storage pool which provides a snapshot reserve of 10%. Trident decides which virtual pool is selected and ensures that the snapshot reserve requirement is met.

CVS service type examples

The following examples provide sample configurations for the CVS service type.

Example 1: Minimum configuration

This is the minimum backend configuration using storageClass to specify the CVS service type and default standardsw service level.

---
version: 1
storageDriverName: gcp-cvs
projectNumber: '012345678901'
storageClass: software
apiRegion: us-east4
apiKey:
  type: service_account
  project_id: my-gcp-project
  private_key_id: "<id_value>"
  private_key: |
    -----BEGIN PRIVATE KEY-----
    <key_value>
    -----END PRIVATE KEY-----
  client_email: cloudvolumes-admin-sa@my-gcp-project.iam.gserviceaccount.com
  client_id: '123456789012345678901'
  auth_uri: https://accounts.google.com/o/oauth2/auth
  token_uri: https://oauth2.googleapis.com/token
  auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
  client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/cloudvolumes-admin-sa%40my-gcp-project.iam.gserviceaccount.com
serviceLevel: standardsw

Example 2: Storage pool configuration

This sample backend configuration uses storagePools to configure a storage pool.

---
version: 1
storageDriverName: gcp-cvs
backendName: gcp-std-so-with-pool
projectNumber: '531265380079'
apiRegion: europe-west1
apiKey:
  type: service_account
  project_id: cloud-native-data
  private_key_id: "<id_value>"
  private_key: |-
    -----BEGIN PRIVATE KEY-----
    <key_value>
    -----END PRIVATE KEY-----
  client_email: cloudvolumes-admin-sa@cloud-native-data.iam.gserviceaccount.com
  client_id: '107071413297115343396'
  auth_uri: https://accounts.google.com/o/oauth2/auth
  token_uri: https://oauth2.googleapis.com/token
  auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
  client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/cloudvolumes-admin-sa%40cloud-native-data.iam.gserviceaccount.com
storageClass: software
zone: europe-west1-b
network: default
storagePools:
- 1bc7f380-3314-6005-45e9-c7dc8c2d7509
serviceLevel: Standardsw

What's next?

After you create the backend configuration file, run the following command:

tridentctl create backend -f <backend-file>

If the backend creation fails, something is wrong with the backend configuration. You can view the logs to determine the cause by running the following command:

tridentctl logs

After you identify and correct the problem with the configuration file, you can run the create command again.