From cfb88d438950b213cbb45e3e5c72d4e87febb660 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 6 Jun 2026 06:19:53 +0330 Subject: [PATCH] feat: add readme --- README.md | 226 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d8ba50 --- /dev/null +++ b/README.md @@ -0,0 +1,226 @@ +# kks-csi-plugin + +Kloud CSI driver for Kubernetes user clusters. This plugin runs inside each user cluster and implements the [Container Storage Interface (CSI)](https://github.com/container-storage-interface/spec) so workloads can use persistent volumes backed by Kloud storage. + +Storage operations are forwarded to the **kks management CSI server** over HTTP. The driver does not talk to storage hardware directly; it translates Kubernetes CSI calls into REST API requests against the management plane. + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ User Kubernetes cluster │ +│ │ +│ ┌──────────────────┐ ┌─────────────────────────────┐ │ +│ │ CSI sidecars │ │ kks-csi-plugin │ │ +│ │ (provisioner, │────▶│ controller / node modes │ │ +│ │ attacher, etc.) │ └──────────────┬──────────────┘ │ +│ └──────────────────┘ │ HTTP │ +│ ▼ │ +└────────────────────────────────────────────┼─────────────────┘ + │ + ▼ + ┌──────────────────────────────┐ + │ kks management CSI server │ + │ (Kloud control plane) │ + └──────────────────────────────┘ +``` + +The Helm chart deploys two workloads: + +| Component | Kind | Role | +|-----------|------|------| +| **Controller** | Deployment | Handles volume create/delete and publish/unpublish via CSI controller RPCs | +| **Node** | DaemonSet | Stages and publishes volumes on each node (format, mount, bind-mount) | + +Standard CSI sidecars are bundled with each workload: + +- **csi-provisioner** and **csi-attacher** on the controller +- **csi-node-driver-registrar** on each node +- **liveness-probe** on both + +## Features + +- Dynamic provisioning via a `StorageClass` (optional, enabled by default) +- Controller publish/unpublish (attach/detach) +- Node stage/unstage and publish/unpublish (mount operations) +- Block volumes are not supported +- Volume expansion is not supported + +Driver name: `storage.csi.kloud.team` + +## Prerequisites + +- Kubernetes **1.28+** +- Network access from the user cluster to the kks management CSI server +- A cluster **CSI access token** and **server URL** from your Kloud cluster details + +## Install with Helm + +Install the chart into each user cluster (typically `kube-system`): + +```bash +helm install kloud-csi ./charts/kloud-csi \ + --namespace kube-system \ + --create-namespace \ + --set serverURL=https://csi.example.kloud.team \ + --set accessToken="YOUR_CLUSTER_CSI_ACCESS_TOKEN" +``` + +### Using an existing secret + +If you already have a secret containing the access token: + +```bash +kubectl create secret generic kloud-csi-credentials \ + --namespace kube-system \ + --from-literal=access-token="YOUR_CLUSTER_CSI_ACCESS_TOKEN" + +helm install kloud-csi ./charts/kloud-csi \ + --namespace kube-system \ + --set serverURL=https://csi.example.kloud.team \ + --set existingSecret=kloud-csi-credentials +``` + +### Verify the install + +```bash +kubectl get pods -n kube-system -l app.kubernetes.io/name=kloud-csi +kubectl get csidriver storage.csi.kloud.team +kubectl get storageclass kloud-csi +``` + +## Helm chart + +Chart path: [`charts/kloud-csi`](charts/kloud-csi) + +### Required values + +| Value | Description | +|-------|-------------| +| `serverURL` | Base URL of the kks management CSI server | +| `accessToken` | Cluster CSI access token (required unless `existingSecret` is set) | + +Helm fails at render time if `serverURL` or credentials are missing. + +### Common values + +| Value | Default | Description | +|-------|---------|-------------| +| `image.repository` | `ghcr.io/KubelanCloud/kks-csi-plugin` | Driver container image | +| `image.tag` | `latest` | Image tag (defaults to chart `appVersion` if empty) | +| `existingSecret` | `""` | Use an existing secret instead of creating one | +| `existingSecretAccessTokenKey` | `access-token` | Key in the secret holding the token | +| `driver.name` | `storage.csi.kloud.team` | CSI driver name | +| `storageClass.enabled` | `true` | Create a `StorageClass` | +| `storageClass.name` | `kloud-csi` | StorageClass name | +| `storageClass.isDefault` | `false` | Mark as the default StorageClass | +| `storageClass.reclaimPolicy` | `Delete` | `Delete` or `Retain` | +| `storageClass.volumeBindingMode` | `WaitForFirstConsumer` | Volume binding mode | +| `controller.replicas` | `1` | Controller deployment replicas | +| `rbac.create` | `true` | Create RBAC for controller and node | + +See [`charts/kloud-csi/values.yaml`](charts/kloud-csi/values.yaml) for the full list, including sidecar image versions and resource limits. + +### Chart resources + +The chart creates: + +- `CSIDriver` — registers the driver with Kubernetes +- `StorageClass` — optional, for dynamic provisioning +- `Deployment` — controller + sidecars +- `DaemonSet` — node plugin + registrar on every node +- `ConfigMap` — minimal HCL stub (settings come from env vars) +- `Secret` — access token (unless `existingSecret` is used) +- RBAC — service accounts and roles for controller and node + +### Upgrade and uninstall + +```bash +helm upgrade kloud-csi ./charts/kloud-csi \ + --namespace kube-system \ + --reuse-values \ + --set serverURL=https://csi.example.kloud.team + +helm uninstall kloud-csi --namespace kube-system +``` + +## Using persistent volumes + +With the default StorageClass installed, create a PVC: + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: my-data +spec: + accessModes: + - ReadWriteOnce + storageClassName: kloud-csi + resources: + requests: + storage: 10Gi +``` + +Then mount it in a pod as usual. + +## Configuration reference + +The driver accepts configuration from an HCL file, environment variables, or both. Environment variables take precedence and are what the Helm chart uses. + +### HCL file + +Example: [`examples/csi-client.hcl`](examples/csi-client.hcl) + +```hcl +driver { + name = "storage.csi.kloud.team" + endpoint = "unix:///var/lib/kubelet/plugins/storage.csi.kloud.team/csi.sock" + mode = "all" # all | controller | node +} + +client { + server_url = "https://csi.example.kloud.team" + access_token = "YOUR_CLUSTER_CSI_ACCESS_TOKEN" +} +``` + +### Environment variables + +| Variable | Description | +|----------|-------------| +| `KKS_CSI_SERVER_URL` | Management CSI server base URL | +| `KKS_CSI_ACCESS_TOKEN` | Cluster access token | +| `KKS_CSI_DRIVER_MODE` | `controller`, `node`, or `all` | +| `KKS_CSI_NODE_ID` | Node identifier (set automatically on node pods) | +| `KKS_CSI_DRIVER_NAME` | CSI driver name override | +| `KKS_CSI_DRIVER_ENDPOINT` | gRPC socket path | +| `KKS_CSI_CLIENT_TIMEOUT_SECONDS` | HTTP client timeout (default: 30) | + +## Standalone / development + +Build and run locally: + +```bash +go build -o kks-csi . +./kks-csi -c examples/csi-client.hcl +``` + +Or with Docker: + +```bash +docker build -t kks-csi . +docker run --rm -v "$(pwd)/examples/csi-client.hcl:/csi.hcl:ro" kks-csi -c /csi.hcl +``` + +Container images are published to `ghcr.io/KubelanCloud/kks-csi-plugin` on pushes to `main`. + +## Development + +```bash +go test ./... +``` + +## License + +See repository license terms.