{"id":32714887,"url":"https://github.com/veloxpack/csi-driver-rclone","last_synced_at":"2026-04-18T08:01:17.939Z","repository":{"id":318761414,"uuid":"1075392507","full_name":"veloxpack/csi-driver-rclone","owner":"veloxpack","description":"CSI driver built on top of rclone bringing cloud storage mounts to your pods with ease.","archived":false,"fork":false,"pushed_at":"2026-04-09T19:09:45.000Z","size":25261,"stargazers_count":315,"open_issues_count":8,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-09T20:25:04.205Z","etag":null,"topics":["csi","dropbox","google-drive","k8s","rclone","s3","s3-bucket","s3-storage","storage","wasabi-s3"],"latest_commit_sha":null,"homepage":"https://www.veloxpack.io/docs/csi-driver-rclone","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/veloxpack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"paulgrammer","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-10-13T12:45:47.000Z","updated_at":"2026-04-08T12:09:30.000Z","dependencies_parsed_at":"2025-10-15T07:24:44.068Z","dependency_job_id":"a89cb707-25c9-49e0-8613-810782975255","html_url":"https://github.com/veloxpack/csi-driver-rclone","commit_stats":null,"previous_names":["veloxpack/csi-driver-rclone"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/veloxpack/csi-driver-rclone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veloxpack%2Fcsi-driver-rclone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veloxpack%2Fcsi-driver-rclone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veloxpack%2Fcsi-driver-rclone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veloxpack%2Fcsi-driver-rclone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/veloxpack","download_url":"https://codeload.github.com/veloxpack/csi-driver-rclone/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/veloxpack%2Fcsi-driver-rclone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31961348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csi","dropbox","google-drive","k8s","rclone","s3","s3-bucket","s3-storage","storage","wasabi-s3"],"created_at":"2025-11-02T13:00:52.270Z","updated_at":"2026-04-18T08:01:17.916Z","avatar_url":"https://github.com/veloxpack.png","language":"Go","funding_links":["https://ko-fi.com/paulgrammer"],"categories":["Go","Cloud and System Integrations"],"sub_categories":["Kubernetes"],"readme":"\n\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://www.veloxpack.io/docs/csi-driver-rclone\"\u003e\n    \u003cimg src=\".github/banner.png\" alt=\"Rclone CSI Driver for Kubernetes\" width=\"100%\"\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://www.veloxpack.io/docs/csi-driver-rclone\"\u003e\n    Rclone CSI Driver for Kubernetes\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n![build status](https://github.com/veloxpack/csi-driver-rclone/actions/workflows/test.yaml/badge.svg)\n[![Trivy vulnerability scanner](https://github.com/veloxpack/csi-driver-rclone/actions/workflows/trivy.yaml/badge.svg?branch=main)](https://github.com/veloxpack/csi-driver-rclone/actions/workflows/trivy.yaml)\n\u003ca href=\"https://ko-fi.com/paulgrammer\"\u003e\n  \u003cimg src=\"https://ko-fi.com/img/githubbutton_sm.svg\" width=\"150\" alt=\"Support on Ko-fi\"/\u003e\n\u003c/a\u003e\n\n**Quick Links:** [Features](#features) | [Requirements](#requirements) | [Installation](#install-driver-on-a-kubernetes-cluster) | [Quick Start](#quick-start-guide) | [Examples](#examples) | [Development](#development) | [Documentation](./docs/)\n\n### Overview\n\nThis is a repository for [Rclone](https://rclone.org/) [CSI](https://kubernetes-csi.github.io/docs/) driver, csi plugin name: `rclone.csi.veloxpack.io`. This driver enables Kubernetes pods to mount cloud storage backends as persistent volumes using rclone, supporting 50+ storage providers including S3, Google Cloud Storage, Azure Blob, Dropbox, and many more.\n\n### Container Images \u0026 Kubernetes Compatibility:\n|driver version  | supported k8s version | status |\n|----------------|-----------------------|--------|\n|main branch     | 1.20+                 | GA     |\n|v0.2.0          | 1.20+                 | GA     |\n\n## Features\n\n- **50+ Storage Providers**: Supports Amazon S3, Google Cloud Storage, Azure Blob, Dropbox, SFTP, and [many more](./deploy/example/README.md)\n- **No External Dependencies**: Uses rclone as a Go library directly - no rclone binary installation required\n- **No Process Overhead**: Direct library integration means no subprocess spawning or external process management\n- **Dynamic Volume Provisioning**: Create persistent volumes via StorageClass\n- **Ephemeral/Inline Volumes**: Define storage directly in Pod specs without separate PV/PVC resources\n- **Secret-based Configuration**: Secure credential management using Kubernetes secrets\n- **Inline Configuration**: Direct configuration in StorageClass parameters\n- **Template Variable Support**: Dynamic path substitution using PVC/PV metadata\n- **VFS Caching**: High-performance caching with configurable options\n- **Remote Control API**: Expose rclone RC API for programmatic control (VFS cache refresh, stats, etc.)\n- **No Staging Required**: Direct mount without volume staging\n- **Flexible Backend Support**: Choose between minimal or full backend support for smaller images\n\n## Requirements\n\n### Production\n- Kubernetes 1.20 or later\n- CSI node driver registrar\n- FUSE support on nodes (for mounting)\n- **No rclone installation required** - the driver uses rclone as a Go library directly\n\n### Development/Testing\nFor local development and testing, we recommend using one of these lightweight Kubernetes distributions:\n- **[minikube](https://minikube.sigs.k8s.io/)** - Easy local Kubernetes cluster with good driver support\n- **[kind](https://kind.sigs.k8s.io/)** (Kubernetes in Docker) - Lightweight and fast for CI/CD\n- **[k3s](https://k3s.io/)** - Minimal Kubernetes distribution, great for edge and IoT\n\nSee the [Development](#development) section for using Skaffold with these tools for the fastest development workflow.\n\n## Install driver on a Kubernetes cluster\n\n\u003e **💡 For Development:** Use [Skaffold](#development) for the fastest development workflow with automatic rebuilds and live reload.\n\n#### Option 1: Install via Helm (Recommended for Production)\n\n**Which installation method should I use?**\n- **Production deployment?** → Use Helm (this section)\n- **Development with live reload?** → Use [Skaffold](#development) (see Development section)\n- **Manual control needed?** → Use [kubectl](#option-2-install-via-kubectl-manual)\n\n**Basic Installation:**\n\n```bash\n# Install with default configuration\nhelm install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone\n\n# Install in a specific namespace\nhelm install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace\n```\n\n**Selecting a specific driver image:**\n\n**With Monitoring \u0026 Observability:**\n\nChoose the monitoring level that fits your needs:\n\n```bash\n# Option A: Basic metrics endpoint\n# Use this for custom Prometheus configurations or basic monitoring\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.metrics.enabled=true\n\n# Option B: Metrics + Kubernetes Service\n# Use this if you have Prometheus configured to discover services\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.metrics.enabled=true \\\n  --set node.metrics.service.enabled=true\n\n# Option C: Full monitoring stack (Recommended for production monitoring)\n# Includes: metrics + ServiceMonitor (Prometheus Operator) + Grafana Dashboard\n# Requires: Prometheus Operator installed (kube-prometheus-stack)\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.metrics.enabled=true \\\n  --set node.metrics.service.enabled=true \\\n  --set node.metrics.serviceMonitor.enabled=true \\\n  --set node.metrics.dashboard.enabled=true \\\n  --set node.metrics.dashboard.namespace=monitoring\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eAdvanced metrics configuration options\u003c/summary\u003e\n\nCustomize metrics server settings:\n\n```bash\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.metrics.enabled=true \\\n  --set node.metrics.addr=:5572 \\\n  --set node.metrics.path=/metrics \\\n  --set node.metrics.readTimeout=10s \\\n  --set node.metrics.writeTimeout=10s \\\n  --set node.metrics.idleTimeout=60s\n```\n\n\u003c/details\u003e\n\n**With Remote Control (RC) API:**\n\nEnable the rclone Remote Control API for programmatic control (e.g., VFS cache refresh, stats):\n\n```bash\n# Option A: RC API with basic auth (recommended for production)\n# First, create a secret with credentials\nkubectl create secret generic csi-rclone-rc-auth \\\n  --from-literal=username=admin \\\n  --from-literal=password=secure-password \\\n  -n veloxpack\n\n# Install with RC API enabled\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.rc.enabled=true \\\n  --set node.rc.basicAuth.existingSecret=csi-rclone-rc-auth \\\n  --set node.rc.service.enabled=true\n\n# Option B: RC API without auth (development only - not recommended)\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.rc.enabled=true \\\n  --set node.rc.noAuth=true \\\n  --set node.rc.service.enabled=true\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eAdvanced RC API configuration options\u003c/summary\u003e\n\nCustomize RC API server settings:\n\n```bash\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.rc.enabled=true \\\n  --set node.rc.addr=:5573 \\\n  --set node.rc.basicAuth.existingSecret=csi-rclone-rc-auth \\\n  --set node.rc.service.enabled=true \\\n  --set node.rc.service.type=ClusterIP\n```\n\n\u003c/details\u003e\n\n**Using RC API:**\n\nOnce enabled, you can call the RC API from within your cluster:\n\n```bash\n# Get RC API endpoint\nRC_SERVICE=$(kubectl get svc -n veloxpack -l app.kubernetes.io/component=node-rc -o jsonpath='{.items[0].metadata.name}')\n\n# Example: Refresh VFS cache for a mount\ncurl -X POST http://${RC_SERVICE}:5573/vfs/refresh \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"recursive\": true, \"dir\": \"/path/to/mount\"}'\n\n# Example: Get mount stats\ncurl -X POST http://${RC_SERVICE}:5573/vfs/stats \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'\n```\n\nFor more RC API endpoints, see the [rclone RC documentation](https://rclone.org/rc/).\n\n**With Ephemeral/Inline Volumes:**\n\nEnable support for ephemeral volumes (inline volumes defined directly in Pod specs):\n\n```bash\n# Enable ephemeral volumes support\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set feature.enableInlineVolume=true\n```\n\nEphemeral volumes allow you to define storage configuration directly in Pod specifications without creating separate PV/PVC resources (see [Kubernetes Ephemeral Volumes](https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/)). This is useful for:\n- Temporary storage that should be deleted with the pod\n- Pod-specific configurations\n- Simplified deployment manifests\n\nVerify the installation:\n\n```bash\n# Check release status\nhelm list -n veloxpack\n\n# Verify pods are running\nkubectl get pods -n veloxpack -l app.kubernetes.io/name=csi-driver-rclone\n```\n\n#### Option 2: Install via kubectl (Manual)\n\nFor manual installation using kubectl and kustomize:\n\n```bash\n# Deploy the driver\nkubectl apply -k deploy/overlays/default\n```\n\nThis will install:\n- CSI Controller (StatefulSet)\n- CSI Node Driver (DaemonSet)\n- RBAC permissions\n- CSIDriver CRD\n\n**Enable RC API with kustomize:**\n\n```bash\n# Create RC auth secret\nkubectl create secret generic csi-rclone-rc-auth \\\n  --from-literal=username=admin \\\n  --from-literal=password=secure-password \\\n  -n veloxpack\n\n# Deploy with RC API enabled\nkubectl apply -k deploy/overlays/default\n# Then apply RC components\nkubectl apply -k deploy/components/rc-basic\nkubectl apply -k deploy/components/rc-service\n```\n\nFor detailed manual installation options and overlays, see the [manual installation guide](./docs/install-rclone-csi-driver.md).\n\n### Driver parameters\nPlease refer to [`rclone.csi.veloxpack.io` driver parameters](./docs/driver-parameters.md)\n\n### Examples\n - [Basic usage](./deploy/example/README.md)\n - [Ephemeral/Inline Volumes](./deploy/example/README-EPHEMERAL.md)\n - [S3 Storage](./deploy/example/storageclass-s3.yaml)\n - [Google Cloud Storage](./deploy/example/storageclass-gcs.yaml)\n - [Azure Blob Storage](./deploy/example/storageclass-azure.yaml)\n - [MinIO](./deploy/example/storageclass-minio.yaml)\n - [Dropbox](./deploy/example/secret-dropbox.yaml)\n - [SFTP](./deploy/example/secret-sftp.yaml)\n\n### Troubleshooting\n - [CSI driver troubleshooting guide](./docs/csi-debug.md)\n\n## Development\n\n### Quick Start with Skaffold (Recommended)\n\n[Skaffold](https://skaffold.dev/) provides the fastest development workflow with automatic rebuilds and deployments.\n\n**Install Skaffold:**\n```bash\n# macOS\nbrew install skaffold\n\n# Linux\ncurl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 \u0026\u0026 \\\nsudo install skaffold /usr/local/bin/\n\n# Windows\nchoco install skaffold\n```\n\n**Start developing:**\n```bash\n# Basic development (no metrics)\nskaffold dev\n\n# Full monitoring stack (Prometheus + Grafana)\nskaffold dev -p metrics-full\n```\n\nSkaffold will:\n- Build the Docker image on code changes\n- Deploy to your local cluster (minikube/kind/k3s)\n- Stream logs from all components\n- Auto-reload on file changes\n- Setup port-forwarding for metrics and dashboards\n\n### Available Skaffold Profiles\n\n| Profile | Description | Port Forwards | Use Case |\n|---------|-------------|---------------|----------|\n| `default` | Basic CSI driver | None | Development without metrics |\n| `metrics` | Metrics endpoint only | None | Testing metrics collection |\n| `metrics-service` | Metrics + Service | :5572 | Service-based scraping |\n| `metrics-prometheus` | Full Prometheus integration | :5572, :9090 | Prometheus development |\n| `metrics-dashboard` | Grafana dashboard only | :3000 | Dashboard testing |\n| `metrics-full` | Complete monitoring | :5572, :9090, :3000 | Full stack development |\n\n**Examples:**\n```bash\n# Development with full monitoring (recommended)\nskaffold dev -p metrics-full\n# Access: http://localhost:5572/metrics (metrics)\n#         http://localhost:9090 (Prometheus)\n#         http://localhost:3000 (Grafana - admin/prom-operator)\n\n# Just metrics endpoint\nskaffold dev -p metrics\n\n# Prometheus integration only\nskaffold dev -p metrics-prometheus\n```\n\n### Metrics Dashboard\n\nThe driver includes a comprehensive Grafana dashboard for monitoring and observability:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/metrics-dashboard.png\" alt=\"Rclone CSI Driver Metrics Dashboard\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n**Dashboard Features:**\n- **Overview \u0026 Rclone Statistics**: Real-time health, uptime, file operations summary\n- **Transfer Performance**: Data transfer rates, cumulative transfers, operation timelines\n- **VFS Cache Performance**: File handles, disk cache usage, metadata cache, upload queues\n- **Mount Health \u0026 Details**: Detailed mount information with health status\n- **System Resources**: CPU, memory, and Go runtime metrics\n\nAccess the dashboard at `http://localhost:3000` when using Skaffold profiles with monitoring enabled.\n\n### Prerequisites for Metrics Profiles\n\nFor `metrics-prometheus` and `metrics-full` profiles, install Prometheus Operator:\n\n```bash\nhelm repo add prometheus-community https://prometheus-community.github.io/helm-charts\nhelm repo update\nhelm install kube-prometheus-stack prometheus-community/kube-prometheus-stack \\\n  --namespace monitoring --create-namespace\n```\n\n### Testing \u0026 Code Quality\n\n```bash\n# Run tests\ngo test ./pkg/rclone/...\n\n# Run linter\n./bin/golangci-lint run --config .golangci.yml ./...\n```\n\n### Local Binary Development\n\nFor testing the driver binary directly without Kubernetes:\n\n```bash\n# Build the binary\nmake build\n\n# Run driver locally\n./bin/rcloneplugin --endpoint unix:///tmp/csi.sock --nodeid CSINode -v=5\n```\n\n### Alternative: Manual Development\n\nFor detailed manual setup and testing procedures, see the [development guide](./docs/csi-dev.md).\n\n## Quick Start Guide\n\nOnce you've [installed the driver](#install-driver-on-a-kubernetes-cluster), follow these steps to start using cloud storage in your pods:\n\n### 1. Configure Storage Backend\n\nCreate a secret with your storage backend configuration:\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: rclone-secret\n  namespace: default\ntype: Opaque\nstringData:\n  remote: \"s3\"\n  remotePath: \"my-bucket\"\n  configData: |\n    [s3]\n    type = s3\n    provider = AWS\n    access_key_id = YOUR_ACCESS_KEY_ID\n    secret_access_key = YOUR_SECRET_ACCESS_KEY\n    region = us-east-1\n```\n\n### 2. Create StorageClass\n\n```yaml\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: rclone-csi\nprovisioner: rclone.csi.veloxpack.io\nparameters:\n  remote: \"s3\"\n  remotePath: \"my-bucket\"\n  csi.storage.k8s.io/node-publish-secret-name: \"rclone-secret\"\n  csi.storage.k8s.io/node-publish-secret-namespace: \"default\"\nreclaimPolicy: Delete\nvolumeBindingMode: Immediate\nallowVolumeExpansion: true\n```\n\n### 3. Create PVC and Pod\n\n```yaml\napiVersion: v1\nkind: PersistentVolumeClaim\nmetadata:\n  name: pvc-rclone\nspec:\n  accessModes:\n    - ReadWriteMany\n  resources:\n    requests:\n      storage: 10Gi\n  storageClassName: rclone-csi\n---\napiVersion: v1\nkind: Pod\nmetadata:\n  name: nginx-rclone\nspec:\n  containers:\n  - name: nginx\n    image: nginx\n    volumeMounts:\n    - name: data\n      mountPath: /data\n  volumes:\n  - name: data\n    persistentVolumeClaim:\n      claimName: pvc-rclone\n```\n\n## Configuration Methods\n\n### Method 1: Kubernetes Secrets (Recommended)\nStore sensitive credentials in Kubernetes secrets and reference them in StorageClass.\n\n### Method 2: Inline Configuration\nInclude configuration directly in StorageClass parameters.\n\n### Method 3: PersistentVolume Configuration\nConfigure directly in PersistentVolume volumeAttributes.\n\n**Priority**: volumeAttributes \u003e StorageClass parameters \u003e Secrets\n\n## Dynamic Path Substitution\n\nThe driver supports template variables in the `remotePath` parameter:\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `${pvc.metadata.name}` | PVC name | `my-pvc-12345` |\n| `${pvc.metadata.namespace}` | PVC namespace | `default` |\n| `${pv.metadata.name}` | PV name | `pv-rclone-abc123` |\n\n**Example:**\n```yaml\nparameters:\n  remote: \"s3\"\n  remotePath: \"my-bucket/${pvc.metadata.namespace}/${pvc.metadata.name}\"\n```\n\n### VFS Cache Options\n```yaml\napiVersion: v1\nkind: PersistentVolume\nmetadata:\n  name: pv-rclone-performance\nspec:\n  mountOptions:\n    - vfs-cache-mode=writes\n    - vfs-cache-max-size=10G\n    - dir-cache-time=30s\n  csi:\n    driver: rclone.csi.veloxpack.io\n    volumeHandle: performance-volume\n    volumeAttributes:\n      remote: \"s3\"\n      remotePath: \"my-bucket\"\n      configData: |\n        [s3]\n        type = s3\n        provider = AWS\n        access_key_id = YOUR_ACCESS_KEY_ID\n        secret_access_key = YOUR_SECRET_ACCESS_KEY\n```\n\n### Separate Cache Directory Mount\n\nFor improved performance, you can mount a separate host path for the rclone cache directory. This is especially useful for:\n- Using faster local storage for cache (e.g., SSD, NVMe)\n- Mounting dedicated disks\n\n```bash\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.cache.enabled=true \\\n  --set node.cache.hostPath=/mnt/rclone-cache\n```\n\n**Using the Cache Directory**\n\nOnce the cache mount is enabled, specify the cache directory in your volume configuration:\n\n```yaml\napiVersion: v1\nkind: PersistentVolume\nmetadata:\n  name: pv-rclone-with-cache\nspec:\n  csi:\n    driver: rclone.csi.veloxpack.io\n    volumeHandle: cache-volume\n    volumeAttributes:\n      remote: \"s3\"\n      remotePath: \"my-bucket\"\n      cache_dir: /var/lib/rclone-cache/my-volume  # Use the mounted cache path\n      configData: |\n        [s3]\n        type = s3\n        provider = AWS\n        access_key_id = YOUR_ACCESS_KEY_ID\n        secret_access_key = YOUR_SECRET_ACCESS_KEY\n```\n\n**Configuration Options:**\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `node.cache.enabled` | Enable cache volume mount | `false` |\n| `node.cache.hostPath` | Host path (required when enabled) | `\"\"` |\n| `node.cache.mountPath` | Mount path in container | `/var/lib/rclone-cache` |\n\n### Remote Control (RC) API\n\nThe driver can expose rclone's Remote Control API, allowing programmatic control of mounts from within your cluster. This is useful for:\n\n- **VFS Cache Refresh**: Trigger cache refresh for specific paths\n- **Statistics**: Get real-time mount statistics\n- **Operations**: Control rclone operations programmatically\n\n**Enable RC API via Helm:**\n\n```bash\n# Create authentication secret\nkubectl create secret generic csi-rclone-rc-auth \\\n  --from-literal=username=admin \\\n  --from-literal=password=secure-password \\\n  -n veloxpack\n\n# Install with RC API\nhelm upgrade --install csi-rclone oci://ghcr.io/veloxpack/charts/csi-driver-rclone \\\n  --namespace veloxpack --create-namespace \\\n  --set node.rc.enabled=true \\\n  --set node.rc.basicAuth.existingSecret=csi-rclone-rc-auth \\\n  --set node.rc.service.enabled=true\n```\n\n**Example: Refresh VFS Cache**\n\n```bash\n# Get the RC service endpoint\nRC_SERVICE=$(kubectl get svc -n veloxpack csi-rclone-node-rc -o jsonpath='{.metadata.name}')\n\n# Refresh cache for a specific path\ncurl -X POST http://${RC_SERVICE}:5573/vfs/refresh \\\n  -u admin:secure-password \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"recursive\": true, \"dir\": \"/path/to/mount\"}'\n```\n\n**Example: Get Mount Statistics**\n\n```bash\ncurl -X POST http://${RC_SERVICE}:5573/vfs/stats \\\n  -u admin:secure-password \\\n  -H \"Content-Type: application/json\" \\\n  -d '{}'\n```\n\n**Configuration Options:**\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `node.rc.enabled` | Enable RC API server | `false` |\n| `node.rc.addr` | RC API listening address | `:5573` |\n| `node.rc.noAuth` | Disable authentication (not recommended) | `false` |\n| `node.rc.basicAuth.existingSecret` | Secret name for credentials | `\"\"` |\n| `node.rc.service.enabled` | Create Kubernetes Service for RC API | `false` |\n\n**Security Considerations:**\n\n- Always use authentication in production (`node.rc.noAuth=false`)\n- Store credentials in Kubernetes secrets\n- Use network policies to restrict access to the RC service\n- The RC API has full control over mounts - restrict access appropriately\n\nFor more RC API endpoints and capabilities, see the [rclone RC documentation](https://rclone.org/rc/).\n\n## Troubleshooting\n\n### Check Driver Status\n```bash\n# Check controller pods\nkubectl get pods -n veloxpack -l app=csi-rclone-controller\n\n# Check node pods\nkubectl get pods -n veloxpack -l app=csi-rclone-node\n\n# Check logs\nkubectl logs -n veloxpack -l app=csi-rclone-controller\nkubectl logs -n veloxpack -l app=csi-rclone-node\n```\n\n### Verify Driver Functionality\n```bash\n# Check if the driver is working correctly\nkubectl exec -n veloxpack -l app=csi-rclone-node -- /rcloneplugin --help\n\n# Check driver version information (shows when driver starts)\nkubectl logs -n veloxpack -l app=csi-rclone-node --tail=10 | grep \"DRIVER INFORMATION\" -A 10\n```\n\n### Common Issues\n1. **Authentication failures**: Verify credentials in secrets or configData\n2. **Network connectivity**: Ensure nodes can reach the storage backend\n3. **Permission errors**: Check that credentials have proper access rights\n4. **Configuration format**: Ensure configData is valid INI format\n5. **Resource constraints**: Verify sufficient memory and disk space\n\nFor detailed troubleshooting, see the [debug guide](./docs/csi-debug.md).\n\n## Building from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/veloxpack/csi-driver-rclone.git\ncd csi-driver-rclone\n\n# Build binary\nmake build\n\n# Build Docker image\nmake container\n\n# Push to registry\nmake push\n```\n\n### Docker Build Options\n\nThe driver supports two backend configurations for different use cases:\n\n#### Full Backend Support (Default)\nIncludes all 50+ rclone backends for maximum compatibility:\n\n```bash\n# Build with all backends (default)\ndocker build -t csi-rclone:latest .\n\n# Or explicitly specify\ndocker build --build-arg RCLONE_BACKEND_MODE=all -t csi-rclone:latest .\n```\n\n#### Minimal Backend Support\nIncludes only the most common backends for smaller image size:\n\n```bash\n# Build with minimal backends\ndocker build --build-arg RCLONE_BACKEND_MODE=minimal -t csi-rclone:minimal .\n```\n\n**Minimal backends include:**\n- Amazon S3 and S3-compatible storage\n- Google Cloud Storage\n- Azure Blob Storage\n- Dropbox\n- Google Drive\n- OneDrive\n- Box\n- Backblaze B2\n- SFTP\n- WebDAV\n- FTP\n- Local filesystem\n\n**Benefits of minimal build:**\n- Smaller Docker image size\n- Faster container startup\n- Reduced attack surface\n- Lower memory footprint\n\nChoose the build that fits your needs - full support for maximum compatibility or minimal for production efficiency.\n\n## Architecture\n\nThis driver is based on the [csi-driver-nfs](https://github.com/kubernetes-csi/csi-driver-nfs) reference implementation, following CSI specification best practices. It also draws inspiration from the original [csi-rclone](https://github.com/wunderio/csi-rclone) implementation by WunderIO.\n\n**Components:**\n- **Identity Server**: Plugin metadata and health checks\n- **Controller Server**: Volume lifecycle management (create/delete)\n- **Node Server**: Volume mounting/unmounting on nodes\n\n**Key Design Decisions:**\n1. **No Staging**: Rclone volumes don't require staging\n2. **Direct Rclone Integration**: Uses rclone's Go library directly\n3. **Remote Creation**: Creates temporary remotes for each mount\n4. **VFS Caching**: Leverages rclone's VFS for improved performance\n5. **Template Variable Support**: Dynamic path substitution using PVC/PV metadata\n\n## Security Considerations\n\n1. **Use Secrets**: Store sensitive credentials in Kubernetes secrets\n2. **RBAC**: Ensure proper RBAC permissions are configured\n3. **Network Policies**: Consider using network policies to restrict access\n4. **Image Security**: Use trusted container images\n5. **Credential Rotation**: Regularly rotate storage backend credentials\n6. **RC API Security**: When enabling Remote Control API, always use authentication and restrict access via network policies\n\n### Log Levels\nSet log level for debugging:\n```yaml\nargs:\n  - \"--v=5\"  # Verbose logging\n  - \"--logtostderr=true\"\n```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions welcome! Please ensure:\n- All code passes `golangci-lint` checks\n- Follow existing code patterns\n- Add tests for new functionality\n- Update documentation\n\n## Acknowledgments\n\nThis project builds upon the excellent work of several open source communities:\n\n- **[WunderIO/csi-rclone](https://github.com/wunderio/csi-rclone)** - The original rclone CSI driver implementation that inspired this project\n- **[Kubernetes CSI NFS Driver](https://github.com/kubernetes-csi/csi-driver-nfs)** - Reference implementation and architectural patterns\n- **[Rclone](https://rclone.org/)** - The powerful cloud storage sync tool that makes this driver possible\n- **[Kubernetes CSI Community](https://github.com/kubernetes-csi)** - For the Container Storage Interface specification and ecosystem\n\nSpecial thanks to the maintainers and contributors of these projects for their dedication to open source software.\n\n## Support\n\n- [Rclone Documentation](https://rclone.org/)\n- [CSI Specification](https://github.com/container-storage-interface/spec)\n- [Issue Tracker](https://github.com/veloxpack/csi-driver-rclone/issues)\n- [Discussions](https://github.com/veloxpack/csi-driver-rclone/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveloxpack%2Fcsi-driver-rclone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveloxpack%2Fcsi-driver-rclone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveloxpack%2Fcsi-driver-rclone/lists"}