GoCSI

The Container Storage Interface (CSI) is an industry standard specification for creating storage plug-ins for container orchestrators. GoCSI aids in the development and testing of CSI storage plug-ins (SP):

Component	Description
csc	CSI command line interface (CLI) client
gocsi	Go-based CSI SP bootstrapper
mock	Mock CSI SP

Quick Start

The following example illustrates using Docker in combination with the GoCSI SP bootstrapper to create a new CSI SP from scratch, serve it on a UNIX socket, and then use the GoCSI command line client csc to invoke the GetPluginInfo RPC:

$ docker run -it golang:latest sh -c \
  "go get github.com/rexray/gocsi && \
  make -C src/github.com/rexray/gocsi csi-sp"

Bootstrapping a Storage Plug-in

The root of the GoCSI project enables storage administrators and developers alike to bootstrap a CSI SP:

$ ./gocsi.sh
usage: ./gocsi.sh GO_IMPORT_PATH

Bootstrap Example

The GoCSI Mock SP illustrates the features and configuration options available via the bootstrapping method. The following example demonstrates creating a new SP at the Go import path github.com/rexray/csi-sp:

$ ./gocsi.sh github.com/rexray/csi-sp
creating project directories:
  /home/akutz/go/src/github.com/rexray/csi-sp
  /home/akutz/go/src/github.com/rexray/csi-sp/provider
  /home/akutz/go/src/github.com/rexray/csi-sp/service
creating project files:
  /home/akutz/go/src/github.com/rexray/csi-sp/main.go
  /home/akutz/go/src/github.com/rexray/csi-sp/provider/provider.go
  /home/akutz/go/src/github.com/rexray/csi-sp/service/service.go
  /home/akutz/go/src/github.com/rexray/csi-sp/service/controller.go
  /home/akutz/go/src/github.com/rexray/csi-sp/service/identity.go
  /home/akutz/go/src/github.com/rexray/csi-sp/service/node.go
use golang/dep? Enter yes (default) or no and press [ENTER]:
  downloading golang/dep@v0.3.2
  executing dep init
building csi-sp:
  success!
  example: CSI_ENDPOINT=csi.sock \
           /home/akutz/go/src/github.com/rexray/csi-sp/csi-sp

The new SP adheres to the following structure:

|-- provider
|   |
|   |-- provider.go
|
|-- service
|   |
|   |-- controller.go
|   |-- identity.go
|   |-- node.go
|   |-- service.go
|
|-- main.go

Provider

The provider package leverages GoCSI to construct an SP from the CSI services defined in service package. The file provider.go may be modified to:

Supply default values for the SP's environment variable configuration properties

Please see the Mock SP's provider.go file for a more complete example.

Service

The service package is where the business logic occurs. The files controller.go, identity.go, and node.go each correspond to their eponymous CSI services. A developer creating a new CSI SP with GoCSI will work mostly in these files. Each of the files have a complete skeleton implementation for their respective service's remote procedure calls (RPC).

Main

The root, or main, package leverages GoCSI to launch the SP as a stand-alone server process. The only requirement is that the environment variable CSI_ENDPOINT must be set, otherwise a help screen is emitted that lists all of the SP's available configuration options (environment variables).

Configuration

All CSI SPs created using this package are able to leverage the following environment variables:

Name	Description
`CSI_ENDPOINT`	The CSI endpoint may also be specified by the environment variable CSI_ENDPOINT. The endpoint should adhere to Go's network address pattern: `tcp://host:port` `unix:///path/to/file.sock` If the network type is omitted then the value is assumed to be an absolute or relative filesystem path to a UNIX socket file.
`X_CSI_MODE`	Specifies the service mode of the storage plug-in. Valid values are: `<empty>` `controller` `node` If unset or set to an empty value the storage plug-in activates both controller and node services. The identity service is always activated.
`X_CSI_ENDPOINT_PERMS`	When `CSI_ENDPOINT` is set to a UNIX socket file this environment variable may be used to specify the socket's file permissions. Please note this value has no effect if `CSI_ENDPOINT` specifies a TCP socket. The default value is 0755.
`X_CSI_ENDPOINT_USER`	When `CSI_ENDPOINT` is set to a UNIX socket file this environment variable may be used to specify the UID or name of the user that owns the file. Please note this value has no effect if `CSI_ENDPOINT` specifies a TCP socket. The default value is the user that starts the process.
`X_CSI_ENDPOINT_GROUP`	When `CSI_ENDPOINT` is set to a UNIX socket file this environment variable may be used to specify the GID or name of the group that owns the file. Please note this value has no effect if `CSI_ENDPOINT` specifies a TCP socket. The default value is the group that starts the process.
`X_CSI_DEBUG`	A `true` value is equivalent to: `X_CSI_LOG_LEVEL=debug` `X_CSI_REQ_LOGGING=true` `X_CSI_REP_LOGGING=true`
`X_CSI_LOG_LEVEL`	The log level. Valid values include: `PANIC` `FATAL` `ERROR` `WARN` `INFO` `DEBUG` The default value is `WARN`.
`X_CSI_REQ_LOGGING`	A flag that enables logging of incoming requests to `STDOUT`. Enabling this option sets `X_CSI_REQ_ID_INJECTION=true`.
`X_CSI_REP_LOGGING`	A flag that enables logging of incoming responses to `STDOUT`. Enabling this option sets `X_CSI_REQ_ID_INJECTION=true`.
`X_CSI_LOG_DISABLE_VOL_CTX`	A flag that disables the logging of the VolumeContext field. Only takes effect if Request or Reply logging is enabled.
`X_CSI_REQ_ID_INJECTION`	A flag that enables request ID injection. The ID is parsed from the incoming request's metadata with a key of `csi.requestid`. If no value for that key is found then a new request ID is generated using an atomic sequence counter.
`X_CSI_SPEC_VALIDATION`	Setting `X_CSI_SPEC_VALIDATION=true` is the same as: `X_CSI_SPEC_REQ_VALIDATION=true` `X_CSI_SPEC_REP_VALIDATION=true`
`X_CSI_SPEC_REQ_VALIDATION`	A flag that enables the validation of CSI request messages.
`X_CSI_SPEC_REP_VALIDATION`	A flag that enables the validation of CSI response messages. Invalid responses are marshalled into a gRPC error with a code of `Internal`.
`X_CSI_SPEC_DISABLE_LEN_CHECK`	A flag that disables validation of CSI message field lengths.
`X_CSI_REQUIRE_STAGING_TARGET_PATH`	A flag that enables treating the following fields as required: `NodePublishVolumeRequest.StagingTargetPath` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_VOL_CONTEXT`	A flag that enables treating the following fields as required: `ControllerPublishVolumeRequest.VolumeContext` `ValidateVolumeCapabilitiesRequest.VolumeContext` `ValidateVolumeCapabilitiesResponse.VolumeContext` `NodeStageVolumeRequest.VolumeContext` `NodePublishVolumeRequest.VolumeContext` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_PUB_CONTEXT`	A flag that enables treating the following fields as required: `ControllerPublishVolumeResponse.PublishContext` `NodeStageVolumeRequest.PublishContext` `NodePublishVolumeRequest.PublishContext` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS`	A `true` value is equivalent to: `X_CSI_REQUIRE_CREDS_CREATE_VOL=true` `X_CSI_REQUIRE_CREDS_DELETE_VOL=true` `X_CSI_REQUIRE_CREDS_CTRLR_PUB_VOL=true` `X_CSI_REQUIRE_CREDS_CTRLR_UNPUB_VOL=true` `X_CSI_REQUIRE_CREDS_NODE_PUB_VOL=true` `X_CSI_REQUIRE_CREDS_NODE_UNPUB_VOL=true` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS_CREATE_VOL`	A flag that enables treating the following fields as required: `CreateVolumeRequest.UserCredentials` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS_DELETE_VOL`	A flag that enables treating the following fields as required: `DeleteVolumeRequest.UserCredentials` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS_CTRLR_PUB_VOL`	A flag that enables treating the following fields as required: `ControllerPublishVolumeRequest.UserCredentials` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS_CTRLR_UNPUB_VOL`	A flag that enables treating the following fields as required: `ControllerUnpublishVolumeRequest.UserCredentials` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS_NODE_STG_VOL`	A flag that enables treating the following fields as required: `NodeStageVolumeRequest.UserCredentials` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_REQUIRE_CREDS_NODE_PUB_VOL`	A flag that enables treating the following fields as required: `NodePublishVolumeRequest.UserCredentials` Enabling this option sets `X_CSI_SPEC_REQ_VALIDATION=true`
`X_CSI_SERIAL_VOL_ACCESS`	A flag that enables the serial volume access middleware.
`X_CSI_SERIAL_VOL_ACCESS_TIMEOUT`	A `time.Duration` string that determines how long the serial volume access middleware waits to obtain a lock for the request's volume before returning the gRPC error code `FailedPrecondition` to indicate an operation is already pending for the specified volume.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_ENDPOINTS`	A list comma-separated etcd endpoint values. If this environment variable is defined then the serial volume access middleware will automatically use etcd for locking, providing distributed serial volume access.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_DOMAIN`	The etcd key prefix to use with the locks that provide distributed, serial volume access. The key paths are: `/DOMAIN/volumesByID/VOLUME_ID` `/DOMAIN/volumesByName/VOLUME_NAME`
`X_CSI_SERIAL_VOL_ACCESS_ETCD_TTL`	The length of time etcd will wait before releasing ownership of a distributed lock if the lock's session has not been renewed.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_AUTO_SYNC_INTERVAL`	A time.Duration string that specifies the interval to update endpoints with its latest members. A value of 0 disables auto-sync. By default auto-sync is disabled.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_DIAL_TIMEOUT`	A time.Duration string that specifies the timeout for failing to establish a connection.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_DIAL_KEEP_ALIVE_TIME`	A time.Duration string that defines the time after which the client pings the server to see if the transport is alive.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_DIAL_KEEP_ALIVE_TIMEOUT`	A time.Duration string that defines the time that the client waits for a response for the keep-alive probe. If the response is not received in this time, the connection is closed.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_MAX_CALL_SEND_MSG_SZ`	Defines the client-side request send limit in bytes. If 0, it defaults to 2.0 MiB (2 * 1024 * 1024). Make sure that "MaxCallSendMsgSize" < server-side default send/recv limit. ("--max-request-bytes" flag to etcd or "embed.Config.MaxRequestBytes").
`X_CSI_SERIAL_VOL_ACCESS_ETCD_MAX_CALL_RECV_MSG_SZ`	Defines the client-side response receive limit. If 0, it defaults to "math.MaxInt32", because range response can easily exceed request send limits. Make sure that "MaxCallRecvMsgSize" >= server-side default send/recv limit. ("--max-request-bytes" flag to etcd or "embed.Config.MaxRequestBytes").
`X_CSI_SERIAL_VOL_ACCESS_ETCD_USERNAME`	The user name used for authentication.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_PASSWORD`	The password used for authentication.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_REJECT_OLD_CLUSTER`	A flag that indicates refusal to create a client against an outdated cluster.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_TLS`	A flag that indicates the client should use TLS.
`X_CSI_SERIAL_VOL_ACCESS_ETCD_TLS_INSECURE`	A flag that indicates the TLS connection should not verify peer certificates.

cornfeedhobo / gocsi