Storage Drivers Definitions

The first step to installing a Storage Driver is to create a Storage Driver Definition. This definition describes how the Storage Driver will be installed and operate on Substrate nodes. For example a driver for a NFS-based volume may look like the following:

version: v1
name: nfs.csi.k8s.io
description: NFS CSI Driver
image:
  uri: docker://registry.k8s.io/sig-storage/nfsplugin:v4.2.0
args:
  - --nodeid=${CSI_NODE_ID}
  - --endpoint=${CSI_ENDPOINT}
  - -v=10
envs:
  ENV_VAR: value
  SECRET_ENV_VAR: secret://organization/nfs-csi-secret-env
mounts:
  - source: /dev
    destination: /dev
  - source: /lib/modules
    destination: /lib/modules
files:
  - path: /path/to/storage.config
    secret: secret://organization/nfs-driver-storage-secrets-map
    content: |
      [credentials]
      # provide secrets to access your remote filesystem
      access_secret = ${ACCESS_SECRET}
      access_username = ${ACCESS_USERNAME}

We will step through the fields of this YAML definition in detail. First, it is necessary to provide the definition version, a name, and a description. The name is obtained by referring to the CSI driver documentation.

The name cannot be changed later, so you might want to double check that it is correct when first created.

# Always v1 for now
version: v1
# The name is mandatory and will be used by storage volume as reference
name: nfs.csi.k8s.io
# A nice, human-readable description
description: NFS CSI Driver

Image

You can supply a URI to tell to Substrate which container to use for the Storage Driver.

image:
  uri: docker://registry.k8s.io/sig-storage/nfsplugin:v4.2.0

It’s possible to specify registry credentials by using secret to provide a secret scheme reference containing registry credentials:

image:
  uri: docker://registry.k8s.io/sig-storage/nfsplugin:v4.2.0
  secret: secret://organization/csi-registry-creds

Arguments

You can provide appropriate arguments for the CSI driver container execution. For example:

args:
  - --nodeid=${CSI_NODE_ID}
  - --endpoint=${CSI_ENDPOINT}
  - -v=10

Most CSI drivers require the arguments --nodeid and --endpoint. You can consult the CSI Driver source code and/or documentation to determine additional command line arguments. The Storage Service will always substitute the variables $CSI_NODE_ID and $CSI_ENDPOINT with the correct values, so it is unnecessary to provide them. (In other words they should appear in the YAML file as literal strings instead of being replaced by values.)

Environments

You can specify environment variables for the CSI Driver. For example:

envs:
  ENV_VAR: value
  SECRET_ENV_VAR: secret://organization/nfs-csi-secret-env

In the example above, a secret value is provided by using a secret scheme reference.

Mounts

A CSI Driver may require access to specific host directories for the containerized software to function properly. Those can be defined by using mounts section. (Note that these mounts are necessary for the drivers to operate and don’t have anything to do with the actual volumes that will be shared to Fuzzball workflows.)

mounts:
  - source: /dev
    destination: /dev
  - source: /lib/modules
    destination: /lib/modules

In this example, we want to mount the host directories /dev and /lib/modules in the driver container. Additionally each source/destination pair can take mount options. If no mount options are specified the default is options: ["bind", "private"]. Here are supported mount options:

bind: regular bind mount
rbind: recursive bind mount
ro: readonly bind mount
slave: bind mount with slave mount propagation
rslave: bind mount with recursive slave mount propagation
private: bind mount with private mount propagation
rprivate: bind mount with recursive private mount propagation
shared: bind mount with shared mount propagation
rshared: bind mount with recursive share mount propagation

You can refer to the Linux kernel documentation on file systems to see the effect of each mount option.

Files

Some CSI drivers require specific configuration files within the container. This syntax allows you to inject files into the driver container:

files:
  - path: /path/to/storage.config
    secret: secret://organization/nfs-driver-storage-secrets-map
    content: |
      [credentials]
      # provide secrets to access your remote filesystem
      access_secret = ${ACCESS_SECRET}
      access_username = ${ACCESS_USERNAME}

Here a file /path/to/storage.config is injected in the container with the provided content. In this example a secret is specified and is referring to a secret map type. This secret type allows you to define multiple key/value pair that can be used as substitution keys (e.g. ${A_KEY} ) within the file content.