A Container Storage Interface (CSI) plug-in that provides block devices (/dev) support.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
block
core
provider
service
vendor
.gitignore
.travis.yml
Gopkg.lock
Gopkg.toml
LICENSE
README.md
main.go
plugin.go

README.md

CSI plugin for local block devices [Build Status]

Description

CSI-BlockDevices is a Container Storage Interface (CSI) plugin for locally attached block devices. Block devices can be exposed to the plugin by symlinking them into a directory, by default /dev/disk/csi-blockdevices. See sample commands for details.

This project may be compiled as a stand-alone binary using Golang that, when run, provides a valid CSI endpoint. This project can also be vendored or built as a Golang plugin in order to extend the functionality of other programs.

Runtime Dependencies

None

Installation

CSI-BlockDevices can be installed with Go and the following command:

$ go get github.com/thecodeteam/csi-blockdevices

The resulting binary will be installed to $GOPATH/bin/csi-blockdevices.

If you want to build csi-nblockdevices with accurate version information, you'll need to run the go generate command and build again:

$ go get github.com/thecodeteam/csi-blockdevices
$ cd $GOPATH/src/github.com/thecodeteam/csi-blockdevices
$ go generate && go install

The binary will once again be installed to $GOPATH/bin/csi-blockdevices.

Start plugin

Before starting the plugin please set the environment variable CSI_ENDPOINT to a valid Go network address such as csi.sock:

$ CSI_ENDPOINT=csi.sock ./csi-blockdevices
INFO[0000] configured com.thecodeteam.blockdevices       devicedir=/dev/disk/csi-blockdevices privatedir=/dev/disk/csi-bd-private
INFO[0000] identity service registered
INFO[0000] controller service registered
INFO[0000] node service registered
INFO[0000] serving                                       endpoint="unix://csi.sock"

The server can be shutdown by using Ctrl-C or sending the process any of the standard exit signals.

Using plugin

The CSI specification uses the gRPC protocol for plug-in communication. The easiest way to interact with a CSI plugin is via the Container Storage Client (csc) program provided via the GoCSI project:

$ go get github.com/thecodeteam/gocsi
$ go install github.com/thecodeteam/gocsi/csc

Then, set have csc use the same CSI_ENDPOINT, and you can issue commands to the plugin. Some examples...

Get the plugin's supported versions and plugin info:

$ ./csc -e csi.sock identity supported-versions
0.1.0

$ ./csc -v 0.1.0 -e csi.sock identity plugin-info
"com.thecodeteam.blockdevices"	"0.1.0+11"
"commit"="24167e6b3486c7938243c4a97fd5fb410390b8e5"
"formed"="Wed, 14 Feb 2018 18:40:13 UTC"
"semver"="0.1.0+11"
"url"="https://github.com/thecodeteam/csi-nfs"

Create a loopback device and make it available to plugin:

$ mkdir /dev/disk/csi-blockdevices
$ cd /dev/disk/csi-blockdevices

# make 100MiB disk image
$ dd if=/dev/zero of=test.img bs=1024 count=102400

# attach disk image to /dev/loop0
$ losetup /dev/loop0 test.img

# create symlink named loop0 -> /dev/loop0
$ ln -s /dev/loop0

$ csc -e csi.sock -v 0.1.0 c ls
"loop0"	0

Publish the "loop0" volume as a block volume

# create file to mount device to
$ touch /mnt/target
$ csc -v 0.1.0 n publish --cap SINGLE_NODE_WRITER,block --target-path /mnt/target loop0
loop0
$ mount | grep -e loop -e target
devtmpfs on /dev/disk/csi-bd-private/loop0 type devtmpfs (rw,relatime,seclabel,size=241476k,nr_inodes=60369,mode=755)
devtmpfs on /mnt/target type devtmpfs (rw,relatime,seclabel,size=241476k,nr_inodes=60369,mode=755) (rw,relatime,seclabel,size=241476k,nr_inodes=60369,mode=755)
$ csc -v 0.1.0 n unpublish --target-path /mnt/target loop0
loop0
$ mount | grep loop
$

Publish the "loop0" volume as a mount volume, formatted with ext4

# create directory to mount filesystem to
$ mkdir /mnt/test
$ csc -v 0.1.0 n publish --cap SINGLE_NODE_WRITER,mount,ext4 --target-path /mnt/test loop0
loop0
$ mount | grep loop
/dev/loop0 on /dev/disk/csi-bd-private/loop0 type ext4 (rw,relatime,seclabel,data=ordered)
/dev/loop0 on /mnt/test type ext4 (rw,relatime,seclabel,data=ordered)
$ csc -v 0.1.0 n unpublish --target-path /mnt/target loop0
loop0
$ mount | grep loop
$

Parameters

No additional parameters are currently supported/required by the plugin

Configuration

The CSI-BlockDevices SP is built using the GoCSI CSP package. Please see its configuration section for a complete list of the environment variables that may be used to configure this SP.

The following table is a list of this SP's default configuration values:

Name Value
X_CSI_SPEC_REQ_VALIDATION true
X_CSI_SERIAL_VOL_ACCESS true
X_CSI_SUPPORTED_VERSIONS 0.1.0
X_CSI_PRIVATE_MOUNT_DIR /dev/disk/csi-bd-private

The following table is a list of configuration values that are specific to BlockDevices, their default values, and whether they are required for operation:

Name Description Default Val Required
X_CSI_BD_DEVDIR Directory to scan for block devices /dev/disk/csi-blockdevices false

Capable operational modes

The CSI spec defines a set of AccessModes that a volume can have. CSI-BlockDevices supports the following modes for volumes that will be mounted as a filesystem:

// Can only be published once as read/write on a single node,
// at any given time.
SINGLE_NODE_WRITER = 1;

// Can only be published once as readonly on a single node,
// at any given time.
SINGLE_NODE_READER_ONLY = 2;

This means that mount volumes can be mounted only at one node at a time (because the disk is local to the node) and can be mounted as read-write or read-only.

For volumes that are used as block devices, only the following are supported:

// Can only be published once as read/write on a single node,
// at any given time.
SINGLE_NODE_WRITER = 1;

This means that giving a workload read-only access to a block device is not supported.

Support

For any questions or concerns please file an issue with the csi-blockdevices project or join the Slack channel #project-rexray at codecommunity.slack.com.