csi-hyperstack

Hyperstack CSI driver

This is an official kubernetes CSI Driver for Nexgen Hyperstack platform. It uses the Hyperstack Go SDK to interact with the Hyperstack API and manage resources. The driver is written in Go and is inspired by other popular cloud adapters.

🚀 Getting Started

This repository contains Taskfile with various helper commands to manage current project

Before you start, make sure you have the following tools installed:

Go 1.22
Task 3.25: A task runner for executing project tasks.
Docker: container builder and runtime
docker-compose: local docker automation

There are also CLI dependencies that are installed with Go:

GoReleaser: manages Go builds ````bash go install github.com/goreleaser/goreleaser@latest
optional / gRPCurl: helps debugging gRPC calls ````bash go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

🏗️ Usage

Hyperstack CSI driver is deployed as a Helm chart. To provision it to the cluster:

Provision a k8s cluster on Hyperstack
Ensure that KUBECONFIG env variable is set to kubeconfig file path

Create a new namespace:

NS="csi-driver"
kubectl create namespace "${NS}"

Create values.yaml (see deploy/helm/values.yaml for details):

components:
  csiHyperstack:
    # Set tag to latest if you are testing locally pushed build
    image: reg.digitalocean.ngbackend.cloud/nexgenk8s/csi-hyperstack:main-latest
    hyperstackClusterId: "Your cluster ID"
hyperstack:
  apiKey: "Your key"
  apiAddress: "Here you can change address if needed"

Set API address
Set API key
Set ClusterID to correct cluster ID (returned by Hyperstack API)

Run install:

helm upgrade --install -f values.yaml -n "${NS}" csi-hyperstack ./deploy/helm
kubectl -n "${NS}" get po -w

💻 Development

To build the driver, run the following command:

task build

If you want to push images for testing:

# User Profile -> Username
USER=""
# User Profile -> CLI Secret
PASSWORD=""
docker login -u "${USER}" -p "${PASSWORD}" https://reg.digitalocean.ngbackend.cloud

Build and push image:
```
task docker-build
task docker-push
```

This will compile the CSI driver and output the binary in the dist directory.

🔎 Testing

This project is intended to be used in a k8s cluster running on Hyperstack. To run it locally (for testing) you can run it directly:

export HYPERSTACK_API_KEY=""
export HYPERSTACK_API_ADDRESS=""

# Start the csi-hyperstack binary
./dist/csi-hyperstack start \
  --endpoint "unix://tmp/csi-hyperstack.sock" \
  --hyperstack-cluster-id "" \
  --hyperstack-node-id "" \
  --service-controller-enabled \
  --service-node-enabled

To get more information on available commands and options run help:

./dist/csi-hyperstack --help

Better approach is using docker-compose.

Firstly run docker build:
```
task docker-build
```

Create a local docker-compose.local.yml with required env variables:

services:
  csi-hyperstack:
    environment:
      HYPERSTACK_API_KEY: "Your key"
      HYPERSTACK_API_ADDRESS: "Here you can change address if needed"

Run it:
```
task start
```
Check metrics
Check that ./data/csi/csi.sock UNIX socket file is created

Testing gRPC calls

You can use gRPCurl to send requests and read responses:

For local run with UNIX socket:

alias gsi='grpcurl -plaintext -unix /tmp/csi-hyperstack.sock'
gsi list

When running in docker:

alias gsi='grpcurl -plaintext localhost:8081'
gsi list

Example output for list:

csi.v1.Controller
csi.v1.Identity
csi.v1.Node
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection

Some helpful endpoints ( see specification for more info):

Driver name and version:
```
gsi csi.v1.Identity/GetPluginInfo
```

Plugin capabilities:

gsi csi.v1.Identity/GetPluginCapabilities

Controller capabilities:

gsi csi.v1.Controller/ControllerGetCapabilities

Node capabilities:
```
gsi csi.v1.Node/NodeGetCapabilities
```

Documentation

For more information about the features of the Hyperstack API, visit the Hyperstack Documentation.

Relevant docs:

Simple guide
Kubernetes CSI Developer Documentation: official documentation on CSI plugin development
CSI Volume Plugins in Kubernetes Design Doc: initial CSI proposal

Examples (reference for development):

Contributing

Contributions to this project are welcome. Please make sure to test your changes before submitting a pull request.