Skip to content

Latest commit

 

History

History
111 lines (93 loc) · 4.72 KB

DEVELOPING.md

File metadata and controls

111 lines (93 loc) · 4.72 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.

Requirements

  • Go >= 1.20

Get the source code:

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

To compile the plugin, run make build-plugin. This will build the driver plugin binary cmd/upcloud-csi-plugin/upcloud-csi-plugin .

$ make build-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

Docker image sanity test

Requirements

  • Sanity Test binary
  • Docker
  • UpCloud Linux server and root privileges

Running test

Login to server and create temporary directory for CSI socket

$ mkdir tmp

Start plugin container

$ docker run --privileged -it --rm \
    --mount type=bind,source=/mnt,target=/mnt,bind-propagation=shared \
    -v `pwd`/tmp:/tmp \
    -v /dev:/dev \
     ghcr.io/upcloudltd/upcloud-csi:latest \
    --username=$UPCLOUD_USERNAME \
    --password=$UPCLOUD_PASSWORD \
    --nodehost=$HOSTNAME \
    --endpoint=unix:///tmp/csi.sock \
    --log-level=debug

Open second terminal to server and run test suite

$ csi-sanity --csi.endpoint=`pwd`/tmp/csi.sock --csi.stagingdir=/mnt/csi-staging --csi.mountdir=/mnt/csi-mount --ginkgo.v --ginkgo.fail-fast -csi.testnodevolumeattachlimit=true

Use -csi.testvolumeaccesstype=block csi-sanity test option to test block devices instead of volumes.

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 }