Rclone Configuration

Overview

The CSI driver supports 50+ storage backends through rclone configuration. Store sensitive credentials in Kubernetes secrets and reference them in StorageClass or PersistentVolume.

Configuration Methods

Method 1: Kubernetes Secrets (Recommended)

Store credentials in secrets and reference them in StorageClass:

apiVersion: v1
kind: Secret
metadata:
  name: rclone-secret
  namespace: default
type: Opaque
stringData:
  remote: "s3"
  remotePath: "my-bucket"
  configData: |
    [s3]
    type = s3
    provider = AWS
    access_key_id = YOUR_ACCESS_KEY_ID
    secret_access_key = YOUR_SECRET_ACCESS_KEY
    region = us-east-1

Method 2: Inline Configuration

Include configuration directly in StorageClass parameters:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: rclone-s3
provisioner: rclone.csi.veloxpack.io
parameters:
  remote: "s3"
  remotePath: "my-bucket"
  configData: |
    [s3]
    type = s3
    provider = AWS
    access_key_id = YOUR_ACCESS_KEY_ID
    secret_access_key = YOUR_SECRET_ACCESS_KEY
    region = us-east-1

Method 3: PersistentVolume Configuration

Configure directly in PersistentVolume volumeAttributes:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-rclone
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteMany
  csi:
    driver: rclone.csi.veloxpack.io
    volumeHandle: rclone-volume
    volumeAttributes:
      remote: "s3"
      remotePath: "my-bucket"
      configData: |
        [s3]
        type = s3
        provider = AWS
        access_key_id = YOUR_ACCESS_KEY_ID
        secret_access_key = YOUR_SECRET_ACCESS_KEY
        region = us-east-1

Priority: volumeAttributes > StorageClass parameters > Secrets

Dynamic Path Substitution

Use template variables in remotePath for multi-tenant isolation:

Variable	Description	Example
`${pvc.metadata.name}`	PVC name	`my-pvc-12345`
`${pvc.metadata.namespace}`	PVC namespace	`default`
`${pv.metadata.name}`	PV name	`pv-rclone-abc123`

Example:

apiVersion: v1
kind: Secret
metadata:
  name: rclone-multitenant-secret
type: Opaque
stringData:
  remote: "s3"
  remotePath: "buckets/${pvc.metadata.namespace}/${pvc.metadata.name}"
  configData: |
    [s3]
    type = s3
    provider = AWS
    access_key_id = YOUR_ACCESS_KEY_ID
    secret_access_key = YOUR_SECRET_ACCESS_KEY
    region = us-east-1

VFS Cache Options

Configure caching for better performance using mountOptions:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-rclone-performance
spec:
  mountOptions:
    - vfs-cache-mode=writes
    - vfs-cache-max-size=10G
    - dir-cache-time=30s
  csi:
    driver: rclone.csi.veloxpack.io
    volumeHandle: performance-volume
    volumeAttributes:
      remote: "s3"
      remotePath: "my-bucket"
      configData: |
        [s3]
        type = s3
        provider = AWS
        access_key_id = YOUR_ACCESS_KEY_ID
        secret_access_key = YOUR_SECRET_ACCESS_KEY
        region = us-east-1

Supported Backends

The driver supports all rclone backends, including:

Amazon S3 and S3-compatible storage (MinIO, DigitalOcean Spaces, etc.)
Google Cloud Storage
Azure Blob Storage
Dropbox
SFTP/SSH
Google Drive
OneDrive
Box
Backblaze B2
WebDAV
FTP
And 50+ more backends

Parameter Processing

The driver processes parameters in this order:

Secrets: Loaded as defaults from csi.storage.k8s.io/node-publish-secret-name
Volume Context: Overrides secrets (from StorageClass parameters or PV volumeAttributes)
ConfigData: Parsed INI format and merged with other parameters
Parameter Sanitization: Remote prefixes removed, hyphens converted to underscores

Parameter Sanitization

Parameters are sanitized for consistency:

s3-endpoint → endpoint (when remote is "s3")
--cache-mode → cache_mode
EndPoint → endpoint

Security Best Practices

Use Secrets: Store sensitive credentials in Kubernetes secrets
RBAC: Ensure proper RBAC permissions are configured
Network Policies: Consider using network policies to restrict access
Image Security: Use trusted container images
Credential Rotation: Regularly rotate storage backend credentials
Minimal Permissions: Grant only necessary permissions to storage backends

Troubleshooting Configuration

Common Issues

Authentication failures: Verify credentials in secrets or configData
Network connectivity: Ensure nodes can reach the storage backend
Permission errors: Check that credentials have proper access rights
Configuration format: Ensure configData is valid INI format
Resource constraints: Verify sufficient memory and disk space

Debug Commands

# Check secret contents
kubectl get secret rclone-secret -o yaml

# Decode secret data
kubectl get secret rclone-secret -o jsonpath='{.data.configData}' | base64 -d

# Check driver logs
kubectl logs -l app=csi-rclone-node -n veloxpack

# Check mount options
kubectl describe pv pv-rclone

Rclone Configuration

On this page