Press CTRL+K to open search

Provision Object Storage with VAST COSI Driver

  • Updated on Sep 24, 2026
  • Published on Sep 24, 2026
  • 15 minute(s) read
Prev Next

VAST COSI Driver Workflow

VAST COSI Driver lets you use the Kubernetes API to create and manage S3 buckets, and also to manage access to the buckets. After a bucket is provisioned, end users can perform object operations on the bucket.

Note: COSI buckets can be provisioned on the default VAST cluster tenant only.

To provision a bucket with VAST COSI Driver:

  1. In the VAST COSI Driver Helm chart configuration file, specify a BucketClass that provides parameters and attributes to be used when provisioning buckets through VAST COSI Driver. You can use a predefined bucket class provided with VAST COSI Driver, or you can define one or more custom bucket classes.

  2. Create and apply a Kubernetes YAML configuration file with the following definitions:

    • A BucketClaim, which is a request to create a bucket of the bucket class specified for the driver.

    • A BucketAccessClass, which provides various options and settings for bucket access requests made through the driver.

    • A BucketAccess request, which contains credentials that can be used to access the bucket.

Define Bucket Class

A bucket class (BucketClass) acts as a container for various parameters and attributes that VAST COSI Driver uses when creating buckets.

You define a bucket class in the VAST COSI Driver Helm chart configuration file.

A minimal bucket class would specify a virtual IP pool, a storage path, and a view policy, for example:

bucketClasses:
  vastdata-bucket:
    vipPool: cosi_vippool
    storagePath: /buckets
    viewPolicy: my_s3_policy
<...>

The bucket class name must be within 27 characters.

For options that can be specified for a bucket class, see Bucket Class Option Reference.

Bucket Class Option Reference

You specify bucket class options in the Helm chart configuration file created for VAST COSI Driver during initial deployment.

Tip: In addition to the VAST COSI Driver options listed above, VAST COSI Driver can pass through parameters that are accepted by the VAST REST API's /api/v1/views/ endpoint of your VAST cluster. For the endpoint parameter reference, see VAST REST API documentation.

bucketOwner

Sets an existing user account as the bucket owner. The bucket owner can be a VMS local user of your choice, or it can be a user account on a non-VAST provider, such as Active Directory, LDAP or NIS.
The bucketOwner option must be specified together with bucketOwnerContext that indicates the provider type.

Syntax in Helm chart configuration file:

bucketOwner: <user_name>

Syntax in Kubernetes YAML:

bucket_owner: <user_name>

bucketOwnerContext

This option is specified together with bucketOwner to indicate the type of the authentication provider from which to retrieve the bucket owner user account.

Syntax in Helm chart configuration file:

bucketOwnerContext: <context>

Syntax in Kubernetes YAML:

bucket_owner_context: <context>

Valid values for <context> include AD (Active Directory), LDAP, NIS, and local.

deletionPolicy

Determines the action to be taken when the bucket object is deleted:

  • Delete (default). Delete the underlying bucket and associated VMS user.

  • Retain. Do not delete the underlying bucket and associated VMS user.

Syntax in Helm chart configuration file:

deletionPolicy: "Delete|Retain"

Syntax in Kubernetes YAML:

deletion_policy: "Delete|Retain"

maxSize

Creates a VAST directory quota on the VAST cluster bucket path, imposing a hard limit on the cluster's logical capacity that can be consumed by the bucket.

Syntax in Helm chart configuration file:

maxSize=<size>

Syntax in Kubernetes YAML:

max_size=<size>

Use Kubernetes units to specify the required size.

Example:

maxSize=30Gi

s3_versioning

When set to true, the bucket is provisioned as a versioned S3 bucket. Default is false.

Syntax in Helm chart configuration file:

s3_versioning: "true"|"false"

Syntax in Kubernetes YAML:

s3_versioning: "true"|"false"

scheme

Determines whether to use HTTP (default) or HTTPS when creating the bucket endpoint. If TLS is configured on the VAST cluster, set it to https.

Syntax:

scheme: "http"|"https"

secretName and secretNamespace

These options lets you supply information for communicating with the VAST cluster:

  • secretName specifies the name of the Kubernetes secret that contains information about the VAST cluster on which to provision buckets for this particular bucket class, the corresponding VMS user credentials or API token and, optionally, the SSL certificate. For more information, see Provision Buckets on Multiple VAST Cluster Tenants.

  • secretNamespace specifies the namespace where the Kubernetes secret was created. If not specified, the parameter defaults to the namespace where the driver is installed.

Syntax in Helm chart configuration file:

secretName: "<secret name>"
secretNamespace: "<secret's namespace>"

Syntax in Kubernetes YAML:

vastdata.com/secret-name: "<secret name>"
vastdata.com/secret-namespace: "<secret's namespace>"

If the secret and its namespace are defined as global options in the Helm chart configuration file, they are automatically propagated to each bucket class. In this case, you do not need to explicitly include the secrets with their corresponding namespaces in the bucket class definitions.

storagePath (root_export)

A storage path within the VAST cluster to be used when provisioning storage for COSI buckets. VAST COSI Driver will automatically create a view for each bucket being provisioned.

Caution: You can specify '/' as the <path>.

This option is required when defining a bucket class in the Helm chart configuration file.

Syntax in Helm chart configuration file:

storagePath: "<path>"

Syntax in Kubernetes YAML:

root_export: "<path>"

lifecycleRules

One or more VAST lifecycle rules that enforce deletion of certain objects when their expiration conditions are met.

Syntax in Helm chart configuration file:

lifecycleRules:
  - name: <rule 1 name>
    <option 1>: <value>
    <option 2>: <value>
    ...
  - name: <rule 2 name>
    <option 1>: <value>
    <option 2>: <value>
    ...

Syntax in Kubernetes YAML:

  lifecycle_rules: |
    [
      {"name": "<rule 1 name>", "<option 1>": <value>, "option 2": <value>},
      {"name": "<rule 2 name>", "<option 1>": <value>, "option 2": <value>},
    ]

Where:

  • name is a unique name for the lifecycle rule. If not specified, the name is generated using the format: cosi-{bucket}-{i}.
  • Expiration options define the conditions for object expiry (and deletion):

    Note At least one of expiration options must be specified.

    • expiration_days - The number of days to pass after object creation.
    • abort_mpu_days_after_initiation - The number of days to pass after an incomplete multipart upload was initiated.
    • expired_obj_delete_marker - If set to true, deletes versioned objects where the only version is a delete marker. Do not include in the same rule as expiration_days.
    • newer_noncurrent_versions - The number of days after which to permanently delete non-current versions of versioned objects. The number of days is timed from when the versioned object is deleted or overwritten.
  • Object selection options determine the objects to which the lifecycle rule applies:
    • prefix - Objects that share the specified key prefix.
    • max_size - Objects smaller than the specified size.
    • min_size- Objects bigger than the specified size.
  • Other options:
    • object_age_attr - Defines which time to use for expiration: mtime (default), atime, ctime.

viewPolicy

The name of the view policy to be assigned to views created by VAST COSI Driver.

A view policy defines access settings for storage exposed through a view. For more information, see Configure VAST Cluster for VAST COSI Driver.

All view policies used with VAST COSI Driver must have the same security flavor.

A view policy set for a bucket class must belong to the same VAST cluster tenant as the virtual IP pool(s) specified for that bucket class.

This option is required when defining a bucket class in the Helm chart configuration file.

Syntax in Helm chart configuration file:

viewPolicy: "<policy name>"

Syntax in Kubernetes YAML:

view_policy: "<policy name>"

vipPool

The name of the virtual IP pool to be used when provisioning storage for COSI buckets.

A virtual IP pool that you specify for a bucket class must belong to the same VAST cluster tenant as the view policy used for this bucket class.

Either vipPool or vipPoolFQDN option is required when defining a bucket class in the Helm chart configuration file. These options are mutually exclusive. When vipPool is used, VAST COSI Driver makes an additional call to the VMS to obtain the IP.

This option is required when defining a bucket class in the Helm chart configuration file.

Syntax in Helm chart configuration file:

vipPool: "<virtual IP pool name>"

Syntax in Kubernetes YAML:

vip_pool: "<virtual IP pool name>"

vipPoolFQDN

The domain name of the virtual IP pool to be used by VAST COSI Driver.

Either vipPoolFQDN or vipPool option is required when defining a bucket class in the Helm chart configuration file. These options are mutually exclusive. With vipPoolFQDN, the IP is obtained through DNS, without the need for an extra call to the VMS.

Syntax in Helm chart configuration file:

vipPoolFQDN: "virtual IP pool's domain name"

Syntax in Kubernetes YAML:

vip_pool_fqdn: "virtual IP pool's domain name"

Define Bucket Claim

A bucket claim (BucketClaim) creates a bucket.

A minimal example of a bucket claim would include the name, bucket class, and protocol specification, for example:

kind: BucketClaim
apiVersion: objectstorage.k8s.io/v1alpha1
metadata:
  name: sample-bucket
spec:
  bucketClassName: vastdata-bucket
  protocols:
  - s3

Note: When provisioning the bucket, the driver generates the bucket name by appending the bucket claim UID (36 characters) to the name specified in a bucket claim. Since bucket names cannot exceed 63 characters, ensure that the name does not exceed 27 characters.

A bucket claim definition can also include various metadata annotations used to fine-tune VAST COSI Driver behavior for a particular bucket. For example:

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketClaim
metadata:
 name: my-bc
  annotations:
    cosi.vastdata.com/maxSize: "5Gi"
spec:
  bucketClassName: vastdata-class-b
  protocols: [s3]

Bucket Claim Annotation Reference

Specify metadata annotations in the format:

metadata:
 ...
  annotations:
    cosi.vastdata.com/<annotation1>: "<value>"
    cosi.vastdata.com/<annotation2>: "<value>"
    ...

maxSize

Sets a quota for the bucket. The bucket quota cannot exceed the quota set by the applicable bucket class.

Syntax:

maxSize=<size>

Use Kubernetes units to specify the required size.

Example:

maxSize=30Gi

Define Bucket Access Class

A bucket access class (BucketAccessClass) is a set of common properties that VAST COSI Driver uses to set up bucket access.

A minimal bucket access class would include the driver name and authentication type, as shown below:

kind: BucketAccessClass
apiVersion: objectstorage.k8s.io/v1alpha1
metadata:
  name: sample-bac
driverName: csi.vastdata.com
authenticationType: KEY

Define Bucket Access

Bucket access (BucketAccess) represents a combination of parameters necessary to get access to a particular bucket.

A minimal bucket access block would include the name of the bucket claim, the name of the bucket access class, and the name (and namespace) of the Kubernetes secret that contains the S3 access keys required for accessing the bucket, for example:

kind: BucketAccess
apiVersion: objectstorage.k8s.io/v1alpha1
metadata:
  name: sample-access
spec:
  bucketClaimName: sample-bucket
  bucketAccessClassName: sample-bac
  credentialsSecretName: sample-access-secret
  credentialsSecretNamespace: sample-access-secret-namespace

After you apply the configuration file with the bucket access definition, verify that the Kubernetes secret exists and can be attached to a Kubernetes pod:

kubectl get secret
<...>
NAME                               TYPE                 DATA   AGE
sample-access-secret               Opaque               1      11s

Bucket Access Annotation Reference

Specify metadata annotations in the format:

metadata:
 ...
  annotations:
    cosi.vastdata.com/<annotation1>: "<value>"
    cosi.vastdata.com/<annotation2>: "<value>"
    ...

flatten-credentials

Enables export of VAST cluster connection parameters from the Kubernetes secret to environment variables.

Syntax:

flatten-credentials: "true"

Provision Buckets on Multiple VAST Cluster Tenants

VAST COSI Driver can provision buckets on multiple VAST cluster tenants. You can specify the tenant and related VMS credentials per bucket class.

  • To provision buckets on a non-default tenant:

    Note: This feature requires VAST Cluster 5.3.3 or later.

    1. Create a Kubernetes secret with the username and password of a VMS user that is a Tenant Admin for the desired tenant. Specify the tenant name on the tenant parameter in the secret.
      The tenant specified in the secret must be the same as the tenant associated with the view policy assigned to the bucket.

    2. In the bucket class definition, use the secretName and secretNamespace parameters to point to the secret created in step 1.

  • To provision buckets on the cluster's default tenant:

    1. Create a Kubernetes secret with the API token of a VMS user that is a Cluster Admin. Omit the tenant parameter.

    2. In the bucket class definition, use the secretName and secretNamespace parameters to point to the secret created in step 1.

Set Quotas

VAST COSI Driver lets you set a VAST cluster directory quota on the bucket being provisioned.

VAST directory quotas are created per VAST cluster path to limit the cluster storage capacity that can be consumed by that path. The quota applies to all objects, files or directories that exist on the path, regardless of the access protocol.

VAST COSI Driver lets you impose a hard limit on the bucket's path size based on the logical capacity. Other quota limit options provided by the VAST cluster are not supported.

Quotas can be specified in the bucket class and/or in the bucket claim. The quota specified in the bucket class is overridden by the quota specified in the bucket claim for that particular bucket.

  • To set a quota that will apply for each bucket provisioned using a certain bucket class, use the maxSize=<size> parameter in the bucket class definition. For example:

    ...
kind: BucketClass
metadata:
  name: vastdata-class
...
parameters:
  ...
  max_size: 30Gi

    Note: Modifying or removing quotas for provisioned buckets is not supported.

  • To set a quota for a particular bucket, add a quota annotation to the bucket claim. For example:

    ....
kind: BucketClaim
metadata:
  name: quota-override
  annotations:
    cosi.vastdata.com/maxSize: "5Gi"
...

    Note: A bucket claim quota cannot be larger than the quota set for the applicable bucket class.

Configure Lifecycle Rules

With VAST COSI Driver, you can configure multiple VAST lifecycle rules for a bucket being provisioned.

VAST lifecycle rules define the expiration date and time for bucket objects. When an object expires, it is automatically deleted. A rule can apply to all objects in the bucket or to objects with certain object key prefixes only.

To set lifecycle rules, use the lifecycleRules parameter in the bucket class definition.

For example, the following lifecycle rules delete all /logs objects that are older than 30 days, and also all /tmp objects that are older than 7 days. For /tmp objects, multipart uploads are set to be aborted after one day from their start:

vastdata-bucketclass:
  <...>
  lifecycleRules:
    - name: expire-logs
      expiration_days: 30
      prefix: logs/
    - name: expire-tmp
      expiration_days: 7
      prefix: tmp/
      abort_mpu_days_after_initiation: 1

Note: For complete usage, see Bucket Class Option Reference

Lifecycle rules are by default enabled upon creation.

The lifecycle rule configuration can be applied to the bucket on bucket creation only. VAST COSI Driver does not support modifying lifecycle rules for an existing bucket.

Provision Buckets with S3 Versioning

VAST COSI Driver supports provisioning of s3 versioned buckets.
By default, the buckets are created with S3 versioning disabled. To enable S3 versioning, add s3_versioning: "true" to the bucket class definition.

Set Up DNS-Based Virtual IP Resolution

When provisioning buckets on the VAST cluster, VAST CSI Driver assigns a virtual IP to each bucket being provisioned. The virtual IP is taken from one or more virtual IP pools defined on the VAST cluster.

You can control how VAST CSI Driver obtains the IP to use, per bucket class:

  • By using DNS to resolve a virtual IP pool's FQDN into an IP. This method improves performance during provisioning.

    Specify the FQDN of the virtual IP pool on the vipPoolFQDN option in the VAST COSI Driver Helm chart configuration file.

    Ensure that the VAST cluster has DNS configured, and the virtual IP pool has Virtual IP Pool Domain Name defined in its settings.

  • By making an additional call to VMS to retrieve an IP.

    Specify the name of the virtual IP pool on the vipPool parameter in the VAST CSI Driver Helm chart configuration file.

Either vipPool or vipPoolFQDN option is required when defining a bucket class in the Helm chart configuration file. These options are mutually exclusive.

Use Externally Managed Bucket Access Keys

You can configure the driver to use externally managed S3 access and secret keys for the VMS local user that the driver creates for each bucket being provisioned. (By default, VMS-generated keys would be used.)

Note: This feature requires VAST Cluster 5.4.0 or later.

To use externally managed keys:

  1. Create a Kubernetes secret that will store the S3 access and secret keys you want to use:

    kind: Secret
metadata:
  name: <name of the secret that holds the keys>
  namespace: <namespace of the secret that holds the keys>
type: Opaque
data:
  accessKeyID: "<access key>"
  accessSecretKey: "<secret key>"

    In the secret:

    • accessKeyID is up to 20 uppercase alphanumeric characters.
    • accessSecretkeyis up to 40 characters, can include alphanumeric characters, a forward slash and a plus sign (+).

  2. Reference the secret that holds the keys in the bucket access class:

    kind: BucketAccessClass
metadata:
  name: <bucket access class name>
driverName: csi.vastdata.com
authenticationType: KEY
parameters:
  credentialsSecretName: <name of the secret that holds the keys>
  credentialsSecretNamespace: <namespace of the secret that holds the keys>

The following requirements and limitations apply:

  • One user can have up to 2 sets of access keys per tenant.
  • The bucket owner must be a VMS local user.

To rotate externally managed access keys:

  1. Update the secret with the new keys.
  2. Delete and recreate all BucketAccess objects under the bucket owner.
  3. Restart the applications.

Set Bucket Owner

You can configure the bucket class to use an existing user account as the bucket owner. The bucket owner can be a VMS local user of your choice, or it can be a user account on a non-VAST provider. The following providers are supported: Active Directory, LDAP, NIS.

If a bucket owner is not set, the driver automatically creates a VMS local user for each bucket being provisioned and deletes the user when the bucket is deleted.

Note: The driver does not delete the bucket owner account when the bucket is deleted.

Before setting a bucket owner, ensure that these prerequisites are met:

  • The bucket owner user account must exist in the authentication provider (regardless on whether it is a VAST provider or an external provider).
  • The authentication provider must be configured in the VMS so that the VMS is able to query the bucket owner user account.

To set the bucket owner, specify the bucketOwner and bucketOwnerContext parameters in the bucket class definition. For example:

bucketClasses:
  vastdata-bucket:
    ...
    bucketOwner: corp-s3-service-account@mine.ad
    bucketOwnerContext: AD

Both parameters are required when setting the bucket owner: bucketOwner specifies the username while bucketOwnerContext indicates the provider type.

The following limitations apply:

  • The name of the user you're going to set as the bucket owner cannot be the same as the name of the bucket provisioned on the VAST cluster.
  • Using externally managed S3 access keys for Active Directory or LDAP user accounts is not supported.

Export Connection Parameters to Environment Variables

You can export endpoint parameters and credentials that the driver uses to connect to the VAST cluster, from the Kubernetes secret to environment variables for further use by applications.

To export the connection parameters, add the flatten-credentials annotation to the bucket access definition, for example:

kind: BucketAccess
metadata:
  ...
  annotations:
    cosi.vastdata.com/flatten-credentials: "true"
spec:
  ...
  credentialsSecretName: <Kubernetes secret name>

Application pods can load the exported variables from secretRef and/or configMapRef resources as follows:

envFrom:
  - secretRef:
      name: <Kubernetes secret name>-flat
  - configMapRef:
      name: <Kubernetes secret name>-flat

Exported Variables

The following environment variables can be exported:

Variable Resource
AWS_ACCESS_KEY_ID secretRef
AWS_SECRET_ACCESS_KEY secretRef
BUCKET_NAME configMapRef
BUCKET_HOST configMapRef
BUCKET_PORT configMapRef
BUCKET_ENDPOINT configMapRef
Related articles