Skip to content

DEVELOPING.md

Latest commit

 

History

History
100 lines (79 loc) · 4.35 KB

DEVELOPING.md

File metadata and controls

100 lines (79 loc) · 4.35 KB
Raw

Developing the CSI driver

CSI driver's primary goal is to conform to Container Storage Interface (CSI) specification by implementing required gRPC endpoints. Unsupported endpoints should return an CALL_NOT_IMPLEMENTED error.
Depending on CO, endpoints are called directly or by sidecar containers (see values.yaml for available sidecars).

Requirements

  • Go >= 1.26
  • Buildah — required for make container-build

Get the source code:

$ git clone git@github.com:upcloud-tools/upcloud-csi.git
$ cd upcloud-csi

Building the plugin

Container image (recommended for testing):

$ make container-build

This builds the plugin inside a multistage Containerfile: Go compilation in a golang:1.26 image, then the binary is copied into an alpine:3.23 runtime image with all required filesystem tools.

Local binary (for quick iteration):

$ go build -o cmd/upcloud-csi-plugin/upcloud-csi-plugin ./cmd/upcloud-csi-plugin

Project layout

Applications

Project's application can be found under cmd directory:

  • upcloud-csi-plugin is monolith CSI driver that can be run as controller or node driver (or both).

Plugin

Required CSI interfaces are implemented in controller, node and ìdentity packages. Plugin's gRPC server uses these packages to expose endpoints described in following interfaces:

Testing

Run tests using make

$ make test

Integration test (CSI sanity suite)

Runs the CSI sanity test suite against a running driver instance. Requires UpCloud API credentials.

$ make test-integration

Logging

Driver uses structured logging which level can be set using --log-level flag. Only errors are logged by default. OS level commands are logged using DEBUG level which also logs gRPC request and response objects. Debug level is only suitable for debugging purposes.
Logging keys are defined in driver/log.go to keep keys consistent across driver.
Correlation ID (correlation_id) is attached to log messages using request interceptor (aka middleware) so that driver operations can be tracked across controller and node.

Tooling

CSI driver's controller functionality can be tested locally but node functions requires that driver is run in UpCloud VM so that driver can see attached disks.

Following example commands expects that driver is running and using endpoint /tmp/csi.sock e.g:

$ upcloud-csi-plugin --username=$UPCLOUD_USERNAME --password=$UPCLOUD_PASSWORD --nodehost=$HOSTNAME --endpoint=unix:///tmp/csi.sock --log-level=debug

Sanity Test Command Line Program

Sanity Test is the command line program that tests a CSI driver using the sanity package test suite.

$ csi-sanity --csi.endpoint=/tmp/csi.sock --ginkgo.fail-fast -csi.testnodevolumeattachlimit

Focus only specs that match regular expression

$ csi-sanity --csi.endpoint=/tmp/csi.sock --ginkgo.fail-fast -csi.testnodevolumeattachlimit --ginkgo.focus ListSnapshots

Container Storage Client

The Container Storage Client (csc) is a command line interface (CLI) tool that provides analogues for all of the CSI RPCs. Print command help

$ csc -e unix:///tmp/csi.sock help

Get controller capabilities

$ csc -e unix:///tmp/csi.sock controller get-capabilities
&{type:CREATE_DELETE_VOLUME }
&{type:PUBLISH_UNPUBLISH_VOLUME }
&{type:LIST_VOLUMES }
&{type:CREATE_DELETE_SNAPSHOT }
&{type:LIST_SNAPSHOTS }
&{type:EXPAND_VOLUME }
&{type:CLONE_VOLUME }

Releasing

See RELEASING.md.