/gocsi

A Container Storage Interface (CSI) library, client, and other helpful utilities created with Go.

Primary LanguageGoApache License 2.0Apache-2.0

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.
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_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.