Documentation Index

Fetch the complete documentation index at: https://kb.vastdata.com/llms.txt

Use this file to discover all available pages before exploring further.

Deploy VAST CSI Driver

  • Updated on Sep 1, 2026
  • Published on Sep 1, 2026
  • 35 minute(s) read
Prev Next

Use one of the following methods to deploy VAST CSI Driver:

VAST CSI Driver Requirements

Ensure that your environment meets the following requirements:

  • A Kubernetes cluster is up and running.

  • A VAST cluster is up and running.

  • All nodes of the Kubernetes cluster are networked with the VAST cluster and can mount VAST cluster volumes via NFS.

  • At least one node can communicate with the VAST Cluster management virtual IP.

  • A host is available with a Helm client installed, preferably in the VMS network.

Supported Versions

VAST CSI Driver 2.6.x requires:

Required Permissions

VAST CSI Driver requires root (sysadmin) privileges.

Deploy VAST CSI Driver with Helm Chart

Before you begin, ensure that your environment meets the requirements.

The following procedure uses a Helm chart to deploy the driver. A Helm chart is an installation template that can be reused to install multiple instances of the software being deployed. Each instance is referred to as a release. Helm charts are available from Helm repositories.

Steps to deploy VAST CSI Driver include:

  1. Install Custom Resource Definitions for snapshots.

    Note: This step is required if the driver's Helm chart configuration file (values.yaml) has secretName and Endpoint specified as global options (on top of values.yaml). This step is optional only when secretName and secretNamespace are specified within one or more storage classes (or under StorageClassDefaults).

  2. (Optional) Create a Kubernetes namespace for VAST CSI Driver.

    Note: This step is required if you are going to deploy VAST CSI Driver in a Kubernetes namespace other than default. Otherwise, skip to step 4.

  3. Configure the VAST cluster.

  4. Create a Kubernetes secret with VMS user credentials or API token for VAST CSI Driver.

  5. Add the Helm repository that contains the VAST CSI Driver chart.

  6. Create a Helm chart configuration file for VAST CSI Driver.

  7. Install the Helm chart for VAST CSI Driver.

  8. (Optional) Verify the deployment by launching a test application.

Install CRDs for VAST Snapshots

CRDs for VAST snapshots are a prerequisite for using VAST snapshots. The CRDs are required if your deployment includes one or more snapshot classes.

The driver's logic for creating snapshot classes varies depending on whether you specify the Kubernetes secret as a global or a storage class-specific option:

  • If the driver's Helm chart configuration file (values.yaml) has secretName and Endpoint specified as global options (on top of values.yaml), the driver follows legacy logic and creates one snapshot class named vastdata-snapshot to be used for all PVCs. This configuration requires that you install the CRDs for VAST snapshots during driver deployment.

  • When secretName and secretNamespace are specified within one or more storage classes (or under StorageClassDefaults), the driver creates snapshot classes only when they are defined explicitly. This means that in this case, you need to install the CRDs for VAST snapshots only when you have an explicit snapshotClass definition in place.

Run the following commands to install the CRDs for snapshots:

kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v7.0.1/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v7.0.1/client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v7.0.1/client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v7.0.1/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/v7.0.1/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml

Create Kubernetes Namespace for VAST CSI Driver

By default, VAST CSI Driver is deployed to the default namespace on the Kubernetes cluster.

If you want to use a different Kubernetes namespace for VAST CSI Driver, create it prior to deployment by running the following command:

kubectl create ns <namespace_name>

Configure VAST Cluster for VAST CSI Driver

Complete the following steps to make your VAST cluster ready for integration with Kubernetes:

  • (Optionally) With VAST Cluster 5.3.3 or later, if you are going to provision storage on a particular VAST tenant, create a tenant that will host the dynamic volumes.

  • Set up virtual IP pools to be used by VAST CSI Driver.

  • Configure a view policy to be used for views created by VAST CSI Driver.

  • Set up a VMS user to be used by VAST CSI Driver.

  • (Optional) Upload your CA-signed SSL certificate to the VAST cluster.

  • (Optional): Configure a QoS policy to be associated with views created by VAST CSI Driver.

Note: If you are going to use VAST CSI Driver with a VAST cluster where the Trash Folder Access feature is disabled or not used for any reason, you also need to complete additional configuration steps.

Create Tenant for Dynamic Volume Provisioning

If you run the driver with VAST Cluster 5.3.3 or later, it is recommended to set up a dedicated VAST Cluster tenant for dynamic volume provisioning to allow for control plane isolation of privileges that would prevent the service account used by the driver from acting outside the scope of dynamic provisioning.

For more information about support of multiple VAST tenants by the driver, see Support of VAST Cluster Multi-Tenancy.

To create a tenant in VAST Web UI, log in and choose Element Store -> Tenants in the main navigation menu. Click Create Tenant and follow the tenant creation guidelines in VAST Cluster Administrator's Guide.

Set Up Virtual IP Pools

VAST CSI Driver distributes the load among virtual IPs in one or more VAST virtual IP pools.

You specify a virtual IP pool in the storage class definition. The virtual IP pool specified for a storage class is used to process read and write operations requested by the application that is using that particular class.

When using VAST Cluster 4.6.0 or later, ensure that the virtual IP pool set for a storage class belongs to the same VAST Cluster tenant as the view policy specified for that class.

In the VAST CSI Driver chart configuration file, the virtual IP pool can be specified by its name (vipPool) or FQDN (vipPoolFQDN). If you are going to use the FQDN, ensure that the VAST cluster has DNS configured, and the virtual IP pool has Virtual IP Pool Domain Name defined in its settings.

To view and manage virtual IP pools in VAST Web UI, log in and choose Network Access -> Virtual IP Pools in the main navigation menu. For more information about VAST Cluster virtual IP pools, see VAST Cluster Administrator's Guide.

Configure View Policies

VAST CSI Driver can automatically create a VAST Cluster view for each storage claim being provisioned. These views are controlled using VAST Cluster view policies.

You specify a view policy to be assigned to the automatically created views in the storage class definition. The view policy specified for a storage class is used when processing read and write operations requested by the application that is using that particular storage class.

When using VAST Cluster 4.6.0 or later, ensure that the view policy set for a storage class belongs to the same VAST Cluster tenant as the virtual IP pool specified for that class.

To view and manage existing view policies in VAST Web UI, log in and choose Element Store -> View Policies. For more information about VAST Cluster view policies, see VAST Cluster Administrator's Guide.

Set Up VMS User

Set up a VMS user for VAST CSI Driver to communicate with the VAST Management Service (VMS) via VAST REST API.

You'll need to supply the VMS user credentials or API token in a Kubernetes secret that is specified when creating the VAST CSI Driver's Helm chart configuration file.

To set up a VMS user for VAST CSI Driver:

  1. Create a new role (in VAST Web UI: Administrators -> Roles -> Create Role) that grants the Create, View, Edit and Delete permissions in the Logical realm.

    Note: Do not use the csi role provided with the cluster.

  2. Create a new VMS manager user for VAST CSI Driver (in VAST Web UI: Administrators -> Managers -> Create Manager) and assign the newly created role to this user.

    Note: Alternatively, assign the newly created role to the admin user provided with the cluster.

    With VAST Cluster 5.3.3 or later, if you are going to provision storage on a particular VAST tenant, set the User type to Tenant Admin and select the desired tenant from the dropdown list. This is the tenant you'll need to specify in the driver's Kubernetes secret.

  3. If you want to have the user authenticated with a VMS API token instead of a password, generate the token as follows:

    • If the user is a Cluster Admin, run the apitoken create command of VAST CLI.

    • If the user is a Tenant Admin, with VAST Cluster 5.3.3 or later:

      1. Install vastpy and vastpy-cli tools with the following command (which installs both tools):

        pip install vastpy

      2. Run the following command to generate the VMS API token:

        vastpy-cli --user <username of tenant admin user>  \
           --password '<password of tenant admin user>' \
           --tenant-name <tenant name>  \
           post apitokens owner=<username of tenant admin user> name=<token name>

        For example:

        vastpy-cli   --user admina  \
 --password 'P@ssw0rd'   \
 --tenant-name ten-a   \
 post apitokens owner=admina name=new‑token9898

Upload CA-Signed SSL Certificate to VAST Cluster

If you want to use a Certificate Authority-signed SSL certificate to secure the connection to the VAST cluster, follow the SSL certificate upload procedure in the VAST Cluster Administrator's Guide to upload your SSL certificate to the VAST cluster.

For more information about configuring SSL encryption for VAST CSI Driver, see Configure SSL Encryption for VAST CSI Driver.

Configure QoS Policy

You can optionally set up a Quality of Service (QoS) policy to be associated with the views that VAST CSI Driver creates. A QoS policy is specified per Kubernetes storage class configured for the VAST driver.

Note: This capability requires VAST Cluster 4.6 or later.

To view and manage QoS policies via VAST Web UI, log in and choose Element Store -> QoS Policies. For more information about VAST Cluster QoS policies, see VAST Cluster Administrator's Guide.

Extra Configuration Steps for Legacy CSI Local-Mount Deletions

If you are going to use VAST CSI Driver with a VAST cluster where the Trash Folder Access feature is disabled or not used for any reason, you need to specify a deletion view policy and a deletion virtual IP pool. The deletion view policy and pool are used solely for deletions and must enable VAST CSI Driver to effectively handle deletions across all storage classes defined.

The deletion view policy and pool can be the same as those used for the volume views, or they can be different.

Ensure that the deletion view policy and pool meet the following requirements:

  • For all versions of VAST Cluster:

    The deletion view policy has the same security flavor as the view policy set for the storage class.

  • For VAST Cluster 4.6.0 up to 4.7.0-SP3:

    The deletion view policy and pool belong to the same VAST Cluster tenant as the view policy and pool specified for the storage class.

  • For VAST Cluster earlier than 4.7.0-SP6:

    The deletion view policy does not have the Root Squash setting enabled.

Create Kubernetes Secret for VAST CSI Driver

Create a Kubernetes secret to keep VMS user credentials or API token that VAST CSI Driver uses to communicate with the VAST cluster. You need to supply the name of the secret when creating the driver's Helm chart configuration file.

The Kubernetes secret can also specify the VAST cluster on which you want to provision volumes for a particular storage class or snapshot class.

Choose one of the following:

Create Kubernetes Secret to Provision Storage on Multiple VAST Clusters

Use this procedure to create one or more Kubernetes secrets that can be specified individually per storage class or snapshot class. Each of these Kubernetes secrets specifies the VAST cluster to connect to and the VMS user credentials or an API token, enabling you to provision volumes on multiple VAST clusters or using multiple VMS users on the same VAST cluster.

Tip: This type of secret can be used not only when there are multiple VAST clusters, but also anytime when the secretName and secretNamespace parameters in the Helm chart configuration file (values.yaml) are specified within a storage class or under StorageClassDefaults.

Do either of the following:

  - [Create](#create-secret-with-vms-api-token-recommended) a secret with a VMS API token (recommended), or

  - [Create](#create-secret-with-vms-user-credentials) a secret with VMS user credentials

Using VMS API tokens is recommended over supplying VMS user credentials.

Create Secret with VMS API Token (Recommended)

Note: VMS API tokens are supported with VAST Cluster 5.3 or later.

To create a Kubernetes secret with the VMS user's API token:

  1. Create a YAML file with the following content:

    apiVersion: v1
kind: Secret
metadata:
  name: <secret name>
type: Opaque
data:
  endpoint: <VAST cluster hostname>
  tenant: <VAST tenant name>
  token: <VMS user's token>
  sslCert: <path to SSL certificate>

    Where:

    • (Required) name is the name of the Kubernetes secret.

    • (Required) endpoint sets the hostname FQDN or IP address of the VMS URL of the VAST cluster where you want to provision block volumes.

    • (Optional) tenant lets you connect to a particular VAST cluster tenant. Supplying a tenant requires that the VMS user has a user type of Tenant Admin for the specified tenant (in VAST Web UI: Administrators -> Managers -> open manager details -> User type: Tenant Admin).

      Note: The tenant parameter is supported starting with VAST CSI Driver 2.6.3.

    • (Required) token is the VMS API token of the VMS user to connect to the VAST cluster. The token must be Base64-encoded.

    • (Optional) sslCert is only required if you are using SSL encryption with a self-signed SSL certificate. It specifies the path to the SSL certificate.

  2. Apply the YAML file:

    kubectl apply -f <path to the YAML file>

    Note: If you are creating the secret in a namespace that is different from the namespace used to install the driver's Helm chart, specify the secret's namespace on the command: -n <secret's namespace>.

Alternatively, you can create a secret with the following command:

kubectl create secret generic <secret name> \
    --from-literal=endpoint='vms.example.com' \
    --from-literal=tenant='<VAST tenant name>' \
    --from-literal=token='<VMS user token>' \
    --from-file=ssl_cert='<path to SSL certificate>' \
    -n <secret's namespace>

For example:

kubectl create secret generic vast-mgmt \
    --from-literal=endpoint='vms.example.com' \
    --from-literal=tenant='Operations' \
    --from-literal=token='xxxxxxxxxххххххххххххххххххххххххххххххх' \
    --from-file=ssl_cert='VastCerts/RootCA.crt' \
    -n secret_namespace

Create Secret with VMS User Credentials

To create a Kubernetes secret with VMS user credentials:

  1. Create a YAML file with the following content:

    apiVersion: v1
kind: Secret
metadata:
  name: <secret name>
type: Opaque
data:
  endpoint: <VAST cluster hostname>
  tenant: <VAST tenant name>
  username: <VMS user's username>
  password: <VMS user's password>
  sslCert: <path to SSL certificate>
  mtlsClientCert: <path to client certificate for mTLS>
  mtlsClientPrivkey: <path to private key for mTLS>

    Where:

    • (Required) name is the name of the Kubernetes secret.

    • (Required) endpoint sets the hostname FQDN or IP address of the VMS URL of the VAST cluster where you want to provision block volumes.

    • (Optional) tenant lets you connect to a particular VAST cluster tenant. Supplying a tenant requires that the VMS user has a user type of Tenant Admin for the specified tenant (in VAST Web UI: Administrators -> Managers -> open manager details -> User type: Tenant Admin).

      Note: The tenant parameter is supported starting with VAST CSI Driver 2.6.3.

    • (Required) username is the username of the VMS user to connect to the VAST cluster. The username must be Base64-encoded.

    • (Required) password is the password for the VMS user connecting to the VAST cluster. The password must be Base64-encoded.

    • (Optional) sslCert is only required if you are using SSL encryption with a self-signed SSL certificate. It specifies the path to the SSL certificate.

    • (Optional) mtlsClientCert and mtlsClientPrivkey are only required if you want to use mTLS authentication. They specify the client certificate and the private key, respectively. Both certificate and key must be provided in PEM format.

  2. Apply the YAML file:

    kubectl apply -f <path to the YAML file>

    Note: If you are creating the secret in a namespace that is different from the namespace used to install the driver's Helm chart, specify the secret's namespace on the command: -n <secret's namespace>.

Alternatively, you can create a secret with the following command:

kubectl create secret generic <secret name> \
    --from-literal=endpoint='vms.example.com' \
    --from-literal=tenant='<VAST tenant name>' \
    --from-literal=username='<VMS user's username>' \
    --from-literal=password='<VMS user's password>' \
    --from-file=ssl_cert='<path to SSL certificate>' \
    --from-file=mtls_client_cert=<path to client certificate for mTLS> \
    --from-file=mtls_client_privkey=<path to private key for mTLS> \
    -n <secret's namespace>

For example:

kubectl create secret generic vast-mgmt \
    --from-literal=endpoint='vms.example.com' \
    --from-literal=tenant='Operations' \
    --from-literal=username='user1' \
    --from-literal=password='xxxxxxxxx' \
    --from-file=ssl_cert='VastCerts/RootCA.crt' \
    --from-file=mtls_client_cert=client.pem \
    --from-file=mtls_client_privkey=client-key.pem \
    -n secret_namespace

Create Kubernetes Secret to Provision Storage on Single VAST Cluster

Use this procedure to create a single Kubernetes secret that contains VMS user credentials to connect to a single VAST cluster. The Kubernetes secret will be used for all storage classes and snapshot classes defined in the VAST CSI Driver Helm chart configuration file. The VAST cluster to connect is specified on the endpoint parameter in the configuration file.

To create a Kubernetes secret that will be used to provision storage on a single VAST cluster:

  1. Create a YAML file with the following content. Note that the VMS user's username and password must be Base64-encoded.

    apiVersion: v1
kind: Secret
metadata:
  name: <secret name>
type: Opaque
data:
  username: <VMS user's username>
  password: <VMS user's password>
  tenant: <VAST tenant name>

  2. Apply the YAML file:

    kubectl apply -f <path to the YAML file>

Alternatively, you can create a secret with the following command:

kubectl create secret generic <secret name> \
    --from-literal=username='<VMS user's username>' \
    --from-literal=password='<VMS user's password>' \
    --from-literal=tenant='<VAST tenant name>'

Note: If you are creating the secret in a Kubernetes namespace that is different from the namespace used to install the VAST CSI Driver Helm chart, specify the secret's namespace on the command: -n <secret's namespace>.

Add Helm Repository for VAST CSI Driver

Add the Helm repository that contains the VAST CSI Driver Helm chart to the list of available repositories:

  1. Add the Helm repository for VAST CSI Driver:

    helm repo add <repo> https://vast-data.github.io/vast-csi

    Specify any suitable name for repo. This name will be used to refer to the VAST CSI Driver repository when running Helm commands. For example: vastcsi

  2. Verify that the repository has been added:

    helm repo list

    The output is similar to the following:

    NAME    URL 
vastcsi https://vast-data.github.io/vast-csi

Create Helm Chart Configuration File for VAST CSI Driver

In Helm-based deployments, VAST CSI Driver's Helm chart configuration file lets you override default installation settings provided in the chart with parameters that are specific to your environment.

The configuration file is a YAML file typically named values.yaml, although you can use any arbitrary name for it.

Create Configuration File

Create a YAML file as follows (see also the example below):

Note: For a detailed reference for parameters and values, see here.

secretName: "<secret>"
endpoint: "<endpoint>"
verifySsl: true|false
sslCertsSecretName: "<SSL secret>"
deletionVipPool: "<deletion virtual IP pool>"
deletionViewPolicy: "<deletion view policy>"

StorageClassDefaults:
  <option 1>
  <option 2>
  ...
  <option n>

storageClasses:
  <storage class name 1>:
    <option 1>
    <option 2>
    ...
    <option n>
  <storage class name 2>:
    <option 1>
    <option 2>
    ...
    <option n>
 ...
  <storage class name n>:
    <option 1>
    <option 2>
    ...
    <option n>

In the YAML file:

  1. Set global or storage class-specific session options:

    • Global session options are specified in the beginning of the configuration file. They apply to all storage classes:

      • secretName: "<secret>": Specify the Kubernetes secret to be used by VAST CSI Driver. For more information, see Create Kubernetes Secret for VAST CSI Driver.

        The secretName global session option is required unless the secret name is provided, together with secretNamespace, under StorageClassDefaults or under a specific storage class. If you supply the secret name under a specific storage class, you must specify the endpoint within the secret.

      • endpoint: "<endpoint>" (required): Enter the VAST Cluster management hostname.

      • verifySsl: true|false (optional): Specify true to enable SSL encryption for the connection to the VAST cluster. If set to false or not specified, SSL encryption is disabled.

        Tip: When enabling SSL encryption, either upload a CA-signed SSL certificate to the VAST cluster, or supply a self-signed SSL certificate to the driver. The latter can be done either via the sslCertsSecretName option, or using --set-file sslCert on the Helm chart installation command.

      • sslCertsSecretName: "<SSL secret>" (optional): Specify the Kubernetes secret that contains the self-signed SSL certificate to be used to secure communications between VAST CSI Driver and the VAST cluster. For more information, see Configure SSL Encryption for VAST CSI Driver.

    • Storage class-specific session options are specified under a certain storage class (in step 3). They apply to that particular storage class only, taking precedence over global session options.

  2. If you are going to use a VAST cluster that has its Trash Folder Access feature disabled or not used, set options to handle deletions. When running against a VAST Cluster version prior to 4.7.0-SP6, these options are required.

    • deletionVipPool: "<deletion virtual IP pool>": Specify the name of the VAST Cluster's virtual IP pool to be used when deleting volumes. It can match a virtual IP pool specified in the vipPool property of a storage class, or you can specify a different virtual IP pool. For more guidance, see Extra Configuration Steps for Legacy CSI Local-Mount Deletions.

    • deletionViewPolicy: "<deletion virtual IP pool>": Specify the name of the VAST Cluster view policy to be used when deleting volumes. It can match a view policy specified in the viewPolicy property of a storage class, or you can specify a different view policy. For more guidance, see Extra Configuration Steps for Legacy CSI Local-Mount Deletions.

  3. Set storage class options:

    • <storage class name> (required): Provide a name to identify the storage class. For more information about Kubernetes storage classes, see Create Storage Classes.

      Note: Define at least one storage class.

    • <option 1>...<option n>: Specify parameters to be used when provisioning storage for PVCs with this storage class. For information on each option, see Storage Class Option Reference.

      The required options are as follows:

      storageClasses:
  <storage class name>:
    vipPoolFQDN: "<pool FQDN>" | vipPool: "<pool name>"
    storagePath: "<path>"
    viewPolicy: "<policy name>"

      If you want to configure storage class-specific session options, add the following parameters:

      • secretName (required if no global session options are set): The name of the Kubernetes secret that contains information about the VAST cluster on which to provision volumes for this particular storage class, the corresponding VMS user credentials or API token and, optionally, the SSL certificate. For more information, see Provisioning Volumes on Multiple VAST Clusters.

      • secretNamespace (optional): If the storage class Kubernetes secret (specified on secretName) was created in a namespace that is different from that used to install the VAST CSI Driver's Helm chart, add this parameter to specify the namespace of the Kubernetes secret.

  4. (Optional) Configure registration of VAST CSI Driver with kubelet:

    • kubeletPath: "<your kubelet root directory>" (optional): Add this option if you are going to run VAST CSI Driver on a Kubernetes cluster where the kubelet root directory is not /var/lib/kubelet.

The following snippet shows a sample configuration file for VAST CSI Driver:

secretName: "vast-mgmt"
endpoint: "vms.example.com"
deletionVipPool: "vippool-1"
deletionViewPolicy: "default"
verifySsl: true

StorageClassDefaults:
  volumeNameFormat: "csi:{namespace}:{name}:{id}"
  ephemeralVolumeNameFormat: "eph:{namespace}:{name}:{id}"
  vipPool: "main"

storageClasses:
  vastdata-filesystem:
    vipPool: "vippool-1"
    storagePath: "/k8s"
    viewPolicy: "default"
    mountOptions:
      - proto=tcp
      - port=2049
      - vers=3
  vastdata-filesystem2:
    secretName: "session-options-for-fs2"
    secretNamespace: "nm"
    vipPool: "vippool-2"
    storagePath: "/fs2/path"
    viewPolicy: "policy-for-fs2"
      mountOptions:
        - proto=rdma
        - port=20049
  my-custom-storage-class:
    secretName: "custom-tenant"
    secretNamespace: "tenant2"
    storagePath: "/data" 
    vipPool: "vip-tenant2"

Verify Configuration File

Verify the newly created chart configuration file:

helm template <release name> <repo>/<chart> -f <filename>.yaml -n <namespace>

Where:

  • <release name> identifies the release being deployed.

  • <repo> is the name of the VAST CSI Driver Helm repository.

  • <chart> is the name of the VAST CSI Driver Helm chart (vastcsi).

  • <filename>.yaml is the VAST driver chart configuration file.

  • <namespace> determines the Kubernetes namespace to which the release is deployed. If this parameter is not specified, the default namespace is used. Otherwise, create a custom namespace prior to installing the VAST driver chart.

For example:

helm template csi-driver vastcsi/vastcsi -f values.yaml

The output is similar to the following:

---
# Source: vastcsi/templates/serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: csi-vast-controller-sa
  namespace: "default"
  labels:
    helm.sh/chart: vastcsi-0.1.0
    app.kubernetes.io/name: vastcsi
    app.kubernetes.io/instance: csi-driver
    app.kubernetes.io/version: "2.6.6"
    app.kubernetes.io/managed-by: Helm
---
# Source: vastcsi/templates/serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
<...>

Install VAST CSI Driver Helm Chart

Installing a Helm chart results in deployment of a VAST driver's release in your Kubernetes environment. A release is identified with its release name, which you supply during the install.

To install the VAST CSI Driver Helm chart:

  1. Refresh Helm repository information:

    helm repo update

  2. Run the following command to initiate the install:

    helm install <release name> <repo>/<chart> -f <filename>.yaml -n <namespace> [--set-file sslCert=VastCerts/RootCA.crt]

    Where:

    • <release name> identifies the release being deployed.

    • <repo> is the name of the VAST CSI Driver Helm repository.

    • <chart> is the name of the Helm chart to be installed (vastcsi).

    • <filename>.yaml is the Helm chart configuration file for VAST CSI Driver.

    • <namespace> (optional) determines the Kubernetes namespace to which the release is deployed. If this parameter is not specified, the default namespace is used. Otherwise, create a custom namespace prior to installing the Helm chart.

    • --set-file sslCert=VastCerts/RootCA.crt (optional) specifies the path to a self-signed SSL certificate to secure the connection to the VAST cluster.

    For example:

    helm install csi-driver vastcsi/vastcsi -f values.yaml

    The output is similar to the following:

    NAME: csi-driver
LAST DEPLOYED: Thu Dec  5 05:24:36 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Thank you for installing vastcsi.

Your release is named csi-driver.
The release is installed in namespace default

To learn more about the release, try:

  $ helm status -n default csi-driver
  $ helm get all -n default csi-driver

<...>

  3. Verify that the Helm chart has been installed as follows:

    • Check the release status with the following command:

      helm status -n <namespace> <release name>

      For example:

      helm status -n default csi-driver

    • Ensure that the release appears in the list of releases:

      helm list -n <namespace>

      For example:

      helm list -n default

      The output is similar to the following:

      NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
csi-driver      default         1               2024-12-04 04:25:33.783236165 +0000 UTC deployed        vastcsi-0.1.0   2.4.0

Verify VAST CSI Driver Deployment

To verify your VAST CSI Driver deployment, test it by launching an application using a Persistent Volume Claim (PVC).

In the following example, VAST CSI Driver will create a PVC by provisioning a volume of 1Gi from VAST using the vastdata-filesystem storage class. It will create a set of 5 pods running an application consisting of Docker containers with mounts to that volume. The application is a shell program that appends a date to a text file.

To verify the deployment with a test application:

  1. Create a Kubernetes YAML configuration file for a PVC as follows:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: vast-pvc-1
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 1Gi
  storageClassName: vastdata-filesystem

  2. Apply the PVC configuration file:

    kubectl apply -f <filename>.yaml

  3. Verify that the PVC has been created with the following commands:

    kubectl get pvc

kubectl get pv

  4. Create a Kubernetes YAML configuration file for the test application:

    kind: StatefulSet
apiVersion: apps/v1
metadata:
  name: test-app-1
spec:
  serviceName: "test-service-1"
  replicas: 5
  selector:
    matchLabels:
      app: test-app-1
  template:
    metadata:
      labels:
        app: test-app-1
        role: test-app-2
    spec:
      containers:
        - name: my-frontend
          image: busybox
          volumeMounts:
          - mountPath: "/shared"
            name: my-shared-volume
          command: [ '/bin/sh', '-c', 'while true; do date -Iseconds >> /shared/$HOSTNAME; sleep 1; done' ]
      volumes:
        - name: my-shared-volume
          persistentVolumeClaim:
            claimName: vast-pvc-1

  5. Apply the test application configuration file:

    kubectl apply -f <filename>.yaml

  6. Monitor the VAST Cluster path specified in the definition of the vastdata-filesystem storage class. You will see a PVC per container, in this example 5. In each, a date will be appended to a text file.

Deploy VAST CSI Driver VAST CSI Operator for Kubernetes

VAST CSI Operator for Kubernetes helps deploy, configure and upgrade VAST CSI drivers in Kubernetes environments.

To deploy VAST CSI Driver using VAST CSI Operator for Kubernetes:

Note: Before you start, ensure that the VAST cluster on which you are going to provision storage is configured for CSI use.

1.  Follow [VAST CSI Operator installation guidelines](https://operatorhub.io/operator/vast-csi-operator) to install VAST CSI Operator.

The VAST CSI Operator will be installed into the `my-vast-csi-operator` namespace. Follow [these guidelines](#specify-namespace) to handle namespaces.

2.  Use VAST CSI Operator to deploy the VAST CSI Driver [custom resources](#custom-resource-definitions-in-vast-csi-operator): `VastCSIDriver`, `VastCluster` and `VastStorage`.

Each of the three resources is required.

3.  [Use](#use-vaststoragegenerated-storage-class-in-pvcs) the storage class generated by the `VastStorage` custom resource instance in your PVCs to provision storage.

Note: VAST CSI Operator does not provide a CRD for VAST snapshots. If you are going to use VAST snapshots with VAST CSI Driver, install the snapshot CRDs manually.

Specify Namespace

By default, VAST CSI Operator for Kubernetes is installed into the my-vast-csi-operator namespace and can be run from that namespace only. To ensure that VAST CSI Driver runs in the same namespace as the VAST CSI Operat, do either of the following:

  • Remove my-vast-csi-operator from the targetNamespaces specification in the manifest produced during the installation, or

  • Install VAST CSI Driver to the my-vast-csi-operator namespace.

Custom Resource Definitions in VAST CSI Operator

VAST CSI Operator introduces the following Custom Resource Definitions (CRD):

  • VastCSIDriver is a common specification for the VAST CSI Controller and VAST CSI Node, for example:

    apiVersion: storage.vastdata.com/v1
kind: VastCSIDriver
metadata:
  name: csi.vastdata.com
  namespace: vast-csi
spec:
  driverType: "nfs"
  image:
    csiVastPlugin:
      repository: docker.io/vastdataorg/csi:v2.6.3

    Ensure that the specification includes the correct driver type for VAST CSI Driver: driverType: "nfs" (default).

    Note: The driverType parameter is available starting with VAST CSI 2.6.3.

  • VastCluster specifies the VAST endpoint and credentials to connect to the VAST cluster where volumes will be provisioned. These settings are stored in a VAST CSI Driver's Kubernetes secret.

    The specification can include either a VMS API token, or a username and a password.

    For example:

    • With a VMS API token:

      apiVersion: storage.vastdata.com/v1
kind: VastCluster
metadata:
  name: cluster
  namespace: vast-csi
spec:
  endpoint: 198.151.100.12
  token: "<token>"

    • With a username and password:

      apiVersion: storage.vastdata.com/v1
kind: VastCluster
metadata:
  name: cluster
  namespace: vast-csi
spec:
  endpoint: 198.151.100.12
  username: admin
  password: "<password>"

    You can create multiple VastCluster instances to access different VAST clusters, or to access the same VAST cluster using different credentials.

  • VastStorage defines VAST storage options to be used when provisioning volumes on the VAST cluster. This resource generates a storage class (and optionally a snapshot class) that you can use in your PVCs.

    For example:

    apiVersion: storage.vastdata.com/v1
kind: VastStorage
metadata:
  name: vastdata-filesystem
  namespace: vast-csi
spec:
  driverType: "nfs"
  provisioner: "csi.vastdata.com"
  secretName: vastcluster
  secretNamespace: vast-csi
  storagePath: "/k8s"
  viewPolicy: "default"
  vipPool: "vippool-1"
  allowVolumeExpansion: true
  createSnapshotClass: false

Use VastStorage-generated Storage Class in PVCs

In your PVC, specify the name of the storage class generated based on the VastStorage CRD as the storageClassName, for example:

For example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: vastdata-filesystem

Deploy VAST CSI Driver on OpenShift with VAST CSI Operator

VAST CSI Operator is an OpenShift operator that helps deploy, configure and upgrade VAST CSI drivers in Red Hat OpenShift environments.

To deploy VAST CSI Driver using VAST CSI Operator:

Note: Before you start, ensure that the VAST cluster on which you are going to provision storage is configured for CSI use.

1.  Follow [OpenShift Operator guidelines](https://catalog.redhat.com/software/container-stacks/detail/5f74e44ee13f2c4bdca41b30#deploy%20&%20use) to install VAST CSI Operator.

2.  Use VAST CSI Operator to deploy the VAST CSI Driver [custom resources](#custom-resource-definitions-in-vast-csi-operator): `VastCSIDriver`, `VastCluster` and `VastStorage`.

Each of the three resources is required.

3.  [Use](#use-vaststoragegenerated-storage-class-in-pvcs) the storage class generated by the `VastStorage` custom resource instance in your PVCs to provision storage.

4.  [Assign](#assign-sccs-to-vast-csi-driver) OpenShift Security Context Constraints (SCCs) to VAST CSI Driver.

Note: VAST CSI Operator does not provide a CRD for VAST snapshots. If you are going to use VAST snapshots with VAST CSI Driver, install the snapshot CRDs manually.

Custom Resource Definitions in VAST CSI Operator

VAST CSI Operator introduces the following Custom Resource Definitions (CRD):

  • VastCSIDriver is a common specification for the VAST CSI Controller and VAST CSI Node, for example:

    apiVersion: storage.vastdata.com/v1
kind: VastCSIDriver
metadata:
  name: csi.vastdata.com
  namespace: vast-csi
spec:
  driverType: "nfs"
  image:
    csiVastPlugin:
      repository: docker.io/vastdataorg/csi:v2.6.4

    Ensure that the specification includes the correct driver type for VAST CSI Driver: driverType: "nfs" (default).

    Note: The driverType parameter is available starting with VAST CSI 2.6.3.

  • VastCluster specifies the VAST endpoint and credentials to connect to the VAST cluster where volumes will be provisioned. These settings are stored in a VAST CSI Driver's Kubernetes secret.

    The specification can include either a VMS authentication token, or a username and a password.

    For example:

    • With a VMS authentication token:

      apiVersion: storage.vastdata.com/v1
kind: VastCluster
metadata:
  name: cluster
  namespace: vast-csi
spec:
  endpoint: 198.151.100.12
  token: "<token>"

    • With a username and password:

      apiVersion: storage.vastdata.com/v1
kind: VastCluster
metadata:
  name: cluster
  namespace: vast-csi
spec:
  endpoint: 198.151.100.12
  username: admin
  password: "<password>"

    You can create multiple VastCluster instances to access different VAST clusters, or to access the same VAST cluster using different credentials.

  • VastStorage defines VAST storage options to be used when provisioning volumes on the VAST cluster. This resource generates a storage class (and optionally a snapshot class) that you can use in your PVCs.

    For example:

    apiVersion: storage.vastdata.com/v1
kind: VastStorage
metadata:
  name: vastdata-filesystem
  namespace: vast-csi
spec:
  driverType: "nfs"
  provisioner: "csi.vastdata.com"
  secretName: vastcluster
  secretNamespace: vast-csi
  storagePath: "/k8s"
  viewPolicy: "default"
  vipPool: "vippool-1"
  allowVolumeExpansion: true
  createSnapshotClass: false

Use VastStorage-generated Storage Class in PVCs

In your PVC, specify the name of the storage class generated based on the VastStorage CRD as the storageClassName, for example:

For example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  storageClassName: vastdata-filesystem

Assign SCCs to VAST CSI Driver

Assign OpenShift Security Context Constraints (SCC) to VAST CSI Driver service accounts so that VAST CSI Driver is able to create mount points on the host machine:

oc adm policy add-scc-to-user privileged -z <release name>-vast-controller-sa -n <namespace name>
oc adm policy add-scc-to-user privileged -z <release name>-vast-node-sa -n <namespace name>

Where:

  • <release name> identifies the VAST CSI Driver release being deployed.

  • <namespace name> is the namespace to which VAST CSI Driver will be deployed.

For example:

oc adm policy add-scc-to-user privileged -z csi-vast-controller-sa -n vastcsi
oc adm policy add-scc-to-user privileged -z csi-vast-node-sa -n vastcsi

Configure SSL Encryption for VAST CSI Driver

You can secure the connection between VAST CSI Driver and the VAST cluster with SSL encryption as follows:

  1. Enable SSL encryption.

  2. Do one of the following to install an SSL certificate:

    • If you want to use a Certified Authority-signed SSL certificate, upload it to the VAST cluster. Follow the SSL certificate upload procedure provided in the VAST Cluster Administrator's Guide.

    • If you want to use a self-signed SSL certificate, supply it to VAST CSI Driver.

Enable SSL Encryption

By default, SSL encryption is disabled.

To enable SSL encryption:

  1. Add the verifySsl=true option to the VAST CSI Driver's Helm chart configuration file, for example:

    secretName: "vast-mgmt"
endpoint: "my.endpoint"
verifySsl: true
<...>

  2. Install or upgrade the VAST CSI Driver Helm chart.

Upload CA-Signed SSL Certificate to VAST Cluster

Follow the guidelines provided in the VAST Cluster Administrator's Guide to upload a CA-signed SSL certificate to the VAST cluster.

Supply Self-Signed SSL Certificate to VAST CSI Driver

You can either point to a file that contains a self-signed SSL certificate file, or specify an existing Kubernetes secret that contains the certificate. These two methods are mutually exclusive.

Do either of the following:

  • Install or upgrade the VAST CSI Driver Helm chart with the --set-file sslCert=<path to certificate file> option specified, for example:

    helm install csi-driver vast/vastcsi -f values.yaml --set-file sslCert=<path to certificate file>

OR

  • Create a Kubernetes secret with the SSL certificate and specify the secret using the sslCertsSecretName option in the VAST CSI Driver Helm chart configuration file:

    1. Create a Kubernetes secret that contains the SSL certificate, for example:

      kubectl create secret generic vast-ca --from-file=ca-bundle.crt=<path to certificate file>

    2. Specify the newly created secret on the sslCertsSecretName option in the VAST CSI Driver chart configuration file, for example:

      secretName: "vast-mgmt"
endpoint: "my.endpoint"
verifySsl: true
sslCertsSecretName: "vast-ca"
<...>

    3. Install or upgrade the VAST CSI Driver Helm chart (without specifying --set-file sslCert).

Replace Self-Signed SSL Certificate for VAST CSI Driver

Choose either of the following, depending on how you supplied the old self-signed SSL certificate:

  • If you supplied the old SSL certificate using the --set-file sslCert option on the Helm chart install or upgrade command:

    • Upgrade the Helm chart with --set-file sslCert pointing to the new SSL certificate file. For example:

      helm upgrade csi-driver vast/vastcsi -f values.yaml --set-file sslCert=<path to new certificate>

OR

  • If the old SSL certificate was supplied via sslCertsSecretName in the VAST CSI Driver chart configuration file:

    1. Create a new Kubernetes secret with the new SSL certificate:

      kubectl create secret generic vast-ca-new --from-file=ca-bundle.crt=<path to new certificate file>

    2. Ensure that the new SSL certificate is specified on the sslCertsSecretName option in the VAST CSI Driver chart configuration file:

      secretName: "vast-mgmt"
endpoint: "my.endpoint"
verifySsl: true
sslCertsSecretName: "vast-ca-new"
<...>

    3. Upgrade the Helm chart, for example:

      helm upgrade csi-driver vast/vastcsi -f values.yaml

Remove Self-Signed SSL Certificate from VAST CSI Driver

Choose either of the following, depending on how you supplied the self-signed SSL certificate:

  • If you used --set-file sslCert to supply the SSL certificate:

    • Upgrade the Helm chart without the --set-file sslCert option specified. For example:

      helm upgrade csi-driver vast/vastcsi -f values.yaml

OR

  • If the old SSL certificate was supplied via sslCertsSecretName:

    1. Remove the sslCertsSecretName option from the VAST CSI Driver chart configuration file.

    2. Upgrade the Helm chart (without specifying --set-file sslCert), for example:

      helm upgrade csi-driver vast/vastcsi -f values.yaml

Configure mTLS Authentication for VAST CSI Driver

Starting with version 2.6.6, VAST CSI Driver supports mTLS authentication on client NFS connections to the VAST NFS server. In multi-tenant environments, mTLS authentication allows for certificate-based access control and isolation of workloads per storage class.

Note: mTLS authentication for NFS requires VAST Cluster 5.5.0 or later.

The requirements are as follows:

  • VAST Cluster 5.5.0 or later

  • VASTNFS 4.5.8 or later

  • Client kernel 6.17 or later

    Note: VAST CSI Driver leverages cert_serial and privkey_serial mount options that are available since Linux kernel 6.17. Note that ktls-utils 1.3.0 and 1.4.0 have a known regression related to these mount options.

To use mTLS authentication with the driver:

  • Configure the VAST cluster to enable mTLS authentication for NFS, as described in the VAST Cluster's Administrator's Guide:

    • Supply the cluster-wide or tenant-specific certificate and identify the certificate field that will be used for tenant association.

    • When using a cluster-wide certificate: set the mTLS identifier for the tenant.

    • (Optional) Configure the view policy (the one used by the CSI storage class) to enforce mTLS on NFS connections.

  • Add the client certificate and the private key to the Kubernetes secret that is used to supply the user's username and password. The secret must contain the certificate signed by the CA that is set on the cluster or tenant.

    For example, if creating the secret from the command line, add these options:

      --from-file=mtls_client_cert=<certificate> \
  --from-file=mtls_client_privkey=<private key> \

    The certificate and the key must be in PEM format.

  • Configure the storage class to use mTLS by adding the xprtsec=mtls mount option:

    mountOptions:
    - "xprtsec=mtls"

  • If the storage class has vip_pool_fqdn_random_prefix set to true (which is by default) and the TLS server certificate contains a wildcarded string for the DNS name, the string must match all related virtual IP pools, for example: *.<vippool-dns-domain>.<dns-suffix>. If the TLS server certificate contains a wildcarded SAN across all virtual IP pools (for example, *.<dns-suffix>), set vip_pool_fqdn_random_prefix to false in the storage class.

Secure VAST CSI Driver in Kubernetes Multi-Tenant Environment

When using VAST CSI Driver in a Kubernetes multi-tenant environment, follow these guidelines to prevent security issues where one client can see the IP address of NFS servers and try to exploit or access other mount points in a direct or indirect attack.

  • Do not run your container as privileged.

    This will block root from within a container from mounting, as shown in the following example where root within a container has searched the mount point, created a directory and attempted to mount, but failed:

    [root@es-master-0 elasticsearch]# mkdir /mnttest
[root@es-master-0 elasticsearch]# mount|grep elastic
10.101.12.16:/elastic/pvc-44b42a13-8dc1-47ff-8c9c-2092311bde1f on /usr/share/elasticsearch/data type nfs (rw,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,hard,proto=rdma,port=20049,timeo=600,retrans=2,sec=sys,mountaddr=10.101.12.16,mountvers=3,mountproto=tcp,local_lock=none,addr=10.101.12.16)           
[root@es-master-0 elasticsearch]# mount -t nfs 10.101.12.16:/elastic /mnttestmount: permission denied

    Note: For information about running a contained as privileged, see this document.

  • Isolate your pods and establish a proper flow of NFS calls from the container to the NFS server.

    By default, pods are not isolated; they accept traffic from any source and can send traffic to any destination.

    Pods become isolated by having a network policy that selects them. Once there is a network policy in a namespace selecting a particular pod, Kubernetes will reject any inbound or outbound connections that are not allowed by any network policy. Other pods in the namespace that are not selected by any network policy will continue to accept all traffic.

    POSIX system calls from within a container are traveling out of the container to the NFS client on the host, and it is from the host that NFS packets are sent to the NFS server. So with proper network isolation, the container cannot communicated directly with the NFS server, even though it knows its IP from the mount information.

    Note: For information about Kubernetes network policies, see this document.

Run Multiple Instances of VAST CSI Driver

You can run multiple VAST CSI Driver instances on the same Kubernetes cluster.

To do so, deploy each instance under its own name specified on the csiDriverName parameter in the driver instance's Helm chart configuration file. Each driver instance needs to be deployed in its own namespace. After deployment, you can supply the driver instance name when specifying the provisioner for a storage class (or a snapshot class), as well as when supplying the driver name in your pod definition.

Note: The default instance name for VAST CSI Driver is csi.vastdata.com.

For example, to deploy two driver instances named csi1.vastdata.com and csi2.vastdata.com:

  1. Create a Helm chart configuration file for each of the instances and specify the instance name in it, for example:

    • For instance 1, create csi1-values.yaml with:

      csiDriverName: csi1.vastdata.com

    • For instance 2, create csi2-values.yaml with:

      csiDriverName: csi2.vastdata.com

  2. Install the Helm chart for driver instance 1 into the namespace designated for this instance, for example:

    helm install csi-driver vastcsi/vastcsi -f csi1-values.yaml -n csi1

  3. Install the Helm chart for driver instance 1 into into a namespace that is different from that used for instance 1, for example:

    helm install csi-driver vastcsi/vastcsi -f csi2-values.yaml -n csi2

If the Helm chart configuration file contains a Kubernetes secret and its namespace specified as global parameters at the top of the file, a default snapshot class named vastdata-snapshot is automatically created during driver installation (unless you define a snapshot class explicitly in the snapshotClasses section of the file). In this case, since snapshot class names must be unique globally, an attempt to deploy the second driver instance may fail because the default snapshot class already exists. To avoid the failure, edit the Helm chart configuration file of the second driver instance being deployed as follows:

  • Add the snapshotClasses section and define a snapshot class explicitly, or

  • Remove the global secret and specify the secret(s) under each storage class (and each snapshot class, if defined).

Related articles