Install

Prerequisites

Kubernetes 1.20+
kubectl configured
Container registry (for custom images)

Build From Source (Optional)

git clone https://github.com/veloxpack/csi-driver-rclone.git
cd csi-driver-rclone

# Build binary and image
make build
make container

# (optional) Push to your registry
make push

Install with kubectl (Kustomize)

# If using a custom image, update image refs first
sed -i "s|image: .*|image: ${REGISTRY}/csi-rclone:${IMAGE_VERSION}|g" deploy/csi-rclone-controller.yaml
sed -i "s|image: .*|image: ${REGISTRY}/csi-rclone:${IMAGE_VERSION}|g" deploy/csi-rclone-node.yaml

# Apply controller, node, RBAC, driverinfo, namespace
kubectl apply -k deploy/

Install with Helm (Recommended)

Install directly from the OCI registry:

# Install with default configuration
helm install csi-rclone oci://registry-1.docker.io/veloxpack/csi-driver-rclone-charts

# Install in a specific namespace
helm install csi-rclone oci://registry-1.docker.io/veloxpack/csi-driver-rclone-charts \
  --namespace veloxpack --create-namespace

Verify the installation:

# Check release status
helm list -n veloxpack

# Verify pods are running
kubectl get pods -n veloxpack -l app.kubernetes.io/name=csi-driver-rclone

Custom Configuration

Create a values.yaml for custom configuration:

image:
  repository: your-registry.com/csi-rclone
  tag: latest
  pullPolicy: Always

controller:
  replicas: 2
  resources:
    requests:
      memory: "256Mi"
      cpu: "100m"
    limits:
      memory: "512Mi"
      cpu: "500m"

node:
  resources:
    requests:
      memory: "256Mi"
      cpu: "100m"
    limits:
      memory: "512Mi"
      cpu: "500m"

helm install csi-rclone oci://registry-1.docker.io/veloxpack/csi-driver-rclone-charts \
  -f values.yaml --namespace veloxpack --create-namespace

Verify Installation

# Check driver pods (for Helm installation)
kubectl get pods -n veloxpack -l app.kubernetes.io/name=csi-driver-rclone

# Check driver pods (for kubectl installation)
kubectl get pods -n veloxpack -l app=csi-rclone-controller
kubectl get pods -n veloxpack -l app=csi-rclone-node

# Check CSIDriver
kubectl get csidriver rclone.csi.veloxpack.io

# Check driver logs (for Helm installation)
kubectl logs -n veloxpack -l app.kubernetes.io/name=csi-driver-rclone

# Check driver logs (for kubectl installation)
kubectl logs -n veloxpack -l app=csi-rclone-controller
kubectl logs -n veloxpack -l app=csi-rclone-node

Driver Configuration

The driver supports various configuration options via command-line flags:

Mount Options

--allow-non-empty: Allow mounting over non-empty directories
--allow-other: Allow access to other users
--async-read: Use asynchronous reads
--debug-fuse: Debug FUSE internals
--direct-io: Use Direct IO (disables caching)

VFS Options

--vfs-cache-mode: Cache mode (off|minimal|writes|full)
--vfs-cache-max-size: Maximum cache size
--vfs-cache-max-age: Max time since last access
--dir-cache-time: Directory cache time
--read-only: Read-only access

Default Parameters

The driver sets these defaults:

cache-info-age: "24h"
cache-chunk-clean-interval: "5m"
cache-dir: "/tmp/rclone-vfs-cache/"

Troubleshooting

Common Issues

Driver won't start: Check FUSE installation and permissions
Mount fails: Verify rclone configuration and network connectivity
Performance issues: Adjust VFS cache settings
Permission errors: Check node permissions and FUSE setup

Debug Commands

# Check driver status (for Helm installation)
kubectl get pods -n veloxpack -l app.kubernetes.io/name=csi-driver-rclone

# Check driver status (for kubectl installation)
kubectl get pods -n veloxpack -l app=csi-rclone-controller
kubectl get pods -n veloxpack -l app=csi-rclone-node

# Check driver logs (for Helm installation)
kubectl logs -n veloxpack -l app.kubernetes.io/name=csi-driver-rclone --tail=100

# Check driver logs (for kubectl installation)
kubectl logs -n veloxpack -l app=csi-rclone-controller --tail=100
kubectl logs -n veloxpack -l app=csi-rclone-node --tail=100

# Check CSIDriver
kubectl get csidriver rclone.csi.veloxpack.io -o yaml

# Check events
kubectl get events --sort-by=.metadata.creationTimestamp

Enable Debug Logging

# In controller deployment
args:
  - "--v=5"
  - "--logtostderr=true"
  - "--stderrthreshold=INFO"

# In node deployment
args:
  - "--v=5"
  - "--logtostderr=true"
  - "--stderrthreshold=INFO"

On this page