kloude/kks-provider-plugin
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

feat: consolidate provider plugin and chart

Browse Source
This commit is contained in:
josh
2026-07-12 14:42:22 +03:30
parent 4996a511eb
commit 077c472b9d
48 changed files with 1870 additions and 854 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+27 -258
View File
@@ -1,279 +1,48 @@
# kks-csi-plugin
# kks-provider-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.
Combined provider plugin for Kubernetes user clusters.
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.
This repository now contains a single plugin and Helm chart that bundles:
## Architecture
- KloudLB controller + speaker logic
- Kloud CSI controller + node logic
```
┌─────────────────────────────────────────────────────────────┐
│ 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 one DaemonSet (`kks-provider-plugin-provider`) that runs all required LB and CSI containers in the same pod on each node.
The Helm chart deploys two workloads:
## Helm Chart
| 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) |
Chart path: `charts/kks-provider-plugin`
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 two `StorageClass` types (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
### From the published chart repository
Charts are published as [GitHub Releases](https://github.com/KubelanCloud/kks-csi-plugin/releases) and to GHCR as OCI artifacts.
**GitHub Release (public):**
Example install:
```bash
helm install kloud-csi \
https://github.com/KubelanCloud/kks-csi-plugin/releases/download/kloud-csi-0.1.0/kloud-csi-0.1.0.tgz \
helm install kks-provider-plugin ./charts/kks-provider-plugin \
--namespace kube-system \
--create-namespace \
--set serverURL=https://csi.example.kloud.team \
--set accessToken="YOUR_CLUSTER_CSI_ACCESS_TOKEN"
--set lb.serverURL=https://lb.example.kloud.team \
--set lb.accessToken="$LB_TOKEN" \
--set csi.serverURL=https://csi.example.kloud.team \
--set csi.accessToken="$CSI_TOKEN"
```
**OCI (requires GHCR access):**
## Binary Commands
```bash
helm registry login ghcr.io
The container/binary entrypoint is `kks-provider` and exposes:
helm install kloud-csi oci://ghcr.io/kubelancloud/charts/kloud-csi \
--version 0.1.0 \
--namespace kube-system \
--create-namespace \
--set serverURL=https://csi.example.kloud.team \
--set accessToken="YOUR_CLUSTER_CSI_ACCESS_TOKEN"
```
- `kks-provider csi`
- `kks-provider lb-controller`
- `kks-provider lb-speaker`
To allow anonymous OCI pulls, set the `charts/kloud-csi` package visibility to public under **GitHub → Packages**.
Each command also starts a Prometheus metrics endpoint on `/metrics` by default:
### From a local checkout
- `kks-provider csi` on `:10080`
- `kks-provider lb-controller` on `:10081`
- `kks-provider lb-speaker` on `:10082`
```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"
```
You can override the bind address with `--metrics-bind-address` (or disable metrics with `--metrics-bind-address=off`).
### Using an existing secret
## Image
If you already have a secret containing the access token:
Default image repository is:
```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)
Published releases are available at [GitHub Releases](https://github.com/KubelanCloud/kks-csi-plugin/releases) and as OCI charts at `oci://ghcr.io/kubelancloud/charts/kloud-csi`. Bump `version` in [`Chart.yaml`](charts/kloud-csi/Chart.yaml) to publish a new chart release.
### 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/kloud-csi-plugin` | Driver container image |
| `image.tag` | *(chart appVersion)* | Image tag (defaults to chart `appVersion` when empty) |
| `imagePullSecrets` | `[]` | Pull secrets for private registries such as GHCR |
| `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 StorageClasses |
| `storageClass.immediate.enabled` | `true` | Create immediate-binding StorageClass |
| `storageClass.immediate.name` | `kloud-csi` | Immediate-binding StorageClass name |
| `storageClass.immediate.isDefault` | `true` | Mark immediate StorageClass as default |
| `storageClass.waitForFirstConsumer.enabled` | `true` | Create WaitForFirstConsumer StorageClass |
| `storageClass.waitForFirstConsumer.name` | `kloud-csi-wait-for-first-consumer` | WaitForFirstConsumer StorageClass name |
| `storageClass.waitForFirstConsumer.isDefault` | `false` | Mark WaitForFirstConsumer StorageClass as default |
| `storageClass.reclaimPolicy` | `Delete` | `Delete` or `Retain` |
| `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` (Immediate) — optional, default class for immediate provisioning
- `StorageClass` (WaitForFirstConsumer) — optional, delayed provisioning until pod scheduling
- `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 immediate 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.
To delay provisioning until the first pod is scheduled, use the second class:
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-data-wait
spec:
accessModes:
- ReadWriteOnce
storageClassName: kloud-csi-wait-for-first-consumer
resources:
requests:
storage: 10Gi
```
## 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/kloud-csi-plugin` on pushes to `main`.
## Development
```bash
go test ./...
```
## License
See repository license terms.
`ghcr.io/kubelancloud/kks-provider-plugin`