Dynamic Provisioning

Dynamic provisioning enables on-demand creation of S3 buckets and PersistentVolumes through Kubernetes' native storage provisioning system. When a PersistentVolumeClaim (PVC) references a StorageClass with the Scality S3 CSI provisioner, the system automatically creates both the S3 bucket and corresponding PersistentVolume (PV).

How Dynamic Provisioning Works

Workflow Overview

sequenceDiagram
    participant Developer
    participant K8s as Kubernetes
    participant Provisioner as CSI Provisioner
    participant Controller as CSI Controller
    participant S3 as S3 Storage

    Developer->>K8s: Create PVC referencing StorageClass
    K8s->>K8s: Queue PVC (status: Pending)
    Provisioner->>K8s: Watch for new PVCs
    K8s-->>Provisioner: PVC event notification
    Provisioner->>Controller: CreateVolume RPC
    Controller->>Controller: Generate Volume ID (csi-s3-{uuid})
    Controller->>S3: Create S3 bucket with Volume ID as name
    S3-->>Controller: Bucket created
    Controller-->>Provisioner: Volume created response (includes Volume ID)
    Provisioner->>K8s: Create PersistentVolume with Volume ID
    K8s->>K8s: Bind PV to PVC
    K8s-->>Developer: PVC ready for use

Core Components

1. StorageClass: Defines provisioning parameters and credentials
2. CSI Provisioner: Watches for PVCs and triggers volume creation
3. CSI Controller: Handles S3 bucket creation and deletion
4. PersistentVolumeClaim: Requests storage with specific requirements

Volume ID System

The CSI driver ensures perfect consistency between Kubernetes resources and S3 storage through a unified volume identification system:

• Volume ID Generation: Each volume gets a unique identifier: csi-s3-{uuid}
• Dual Purpose: This ID serves as both the CSI Volume ID (stored in PersistentVolume) and the S3 bucket name
• Lifecycle Consistency: Creation and deletion operations use the same identifier, eliminating any ambiguity about which bucket corresponds to which volume

Key Requirements

Basic Configuration

StorageClass Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: s3-dynamic
provisioner: s3.csi.scality.com
reclaimPolicy: Delete
volumeBindingMode: Immediate
parameters:
  # Credential configuration
  csi.storage.k8s.io/provisioner-secret-name: s3-provisioner-secret
  csi.storage.k8s.io/provisioner-secret-namespace: kube-system
  csi.storage.k8s.io/node-publish-secret-name: s3-node-secret
  csi.storage.k8s.io/node-publish-secret-namespace: kube-system
mountOptions:
  - allow-delete
  - allow-other
  - region=us-east-1

PersistentVolumeClaim Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-storage
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: s3-dynamic
  resources:
    requests:
      storage: 10Gi  # Arbitrary value for S3

Volume Binding Modes

Immediate Binding (Default)

• PV created immediately when PVC is created
• Bucket created before pod scheduling
• Suitable for most use cases

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: s3-immediate
provisioner: s3.csi.scality.com
reclaimPolicy: Delete
volumeBindingMode: Immediate  # Default behavior
parameters:
  csi.storage.k8s.io/provisioner-secret-name: s3-provisioner-secret
  csi.storage.k8s.io/provisioner-secret-namespace: kube-system

WaitForFirstConsumer

• PV creation delayed until pod is scheduled
• Ensures bucket is created in optimal location
• Recommended if using ${pv.name} templating in StorageClass parameters

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: s3-wait-for-consumer
provisioner: s3.csi.scality.com
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer  # Wait for pod scheduling
parameters:
  # Using ${pv.name} templating requires WaitForFirstConsumer
  csi.storage.k8s.io/provisioner-secret-name: "${pv.name}-secret"
  csi.storage.k8s.io/provisioner-secret-namespace: "${pvc.namespace}"
  csi.storage.k8s.io/node-publish-secret-name: "${pv.name}-secret"
  csi.storage.k8s.io/node-publish-secret-namespace: "${pvc.namespace}"

Lifecycle Management

Bucket Creation

• Automatic Naming: Buckets use csi-s3-{uuid} format (e.g., csi-s3-12345678-abcd-1234-abcd-123456789012)
• Volume ID Consistency: The same identifier is used as both the CSI Volume ID and S3 bucket name
• Bucket Configuration: Created with default configuration using S3 API CreateBucket

Bucket Deletion

Controlled by the reclaimPolicy:

• Delete: Bucket deleted when PVC is deleted (only if bucket is empty) using S3 API DeleteBucket
• Retain: Bucket preserved after PVC deletion

1

reclaimPolicy: Delete  # or Retain

Mount Options

Dynamic provisioning supports all mount options through the StorageClass specification:

Authentication

Dynamic provisioning requires two sets of credentials. If either or both credential types are missing from the StorageClass configuration, the CSI driver will fall back to the default driver-level credentials.

1. Provisioner Secrets: Used by CSI controller for bucket creation and deletion
2. Node Secrets: Used by nodes for mounting operations

See the Credential Management Guide for detailed configuration.

Limitations

• Single Access Mode: Only ReadWriteMany is supported
• S3 Bucket Deletion: Bucket deletion only occurs when completely empty (no objects)

Next Steps

• Learn about StorageClass Parameters
• Set up Credential Management