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/[email protected]
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:
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:
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 The default value is 0755. |
X_CSI_ENDPOINT_USER |
When The default value is the user that starts the process. |
X_CSI_ENDPOINT_GROUP |
When The default value is the group that starts the process. |
X_CSI_DEBUG |
A true value is equivalent to:
|
X_CSI_LOG_LEVEL |
The log level. Valid values include:
The default value is |
X_CSI_REQ_LOGGING |
A flag that enables logging of incoming requests to
Enabling this option sets |
X_CSI_REP_LOGGING |
A flag that enables logging of incoming responses to
Enabling this option sets |
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 |
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:
Enabling this option sets |
X_CSI_REQUIRE_VOL_CONTEXT |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_PUB_CONTEXT |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_CREDS |
A true value is equivalent to:
Enabling this option sets |
X_CSI_REQUIRE_CREDS_CREATE_VOL |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_CREDS_DELETE_VOL |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_CREDS_CTRLR_PUB_VOL |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_CREDS_CTRLR_UNPUB_VOL |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_CREDS_NODE_STG_VOL |
A flag that enables treating the following fields as required:
Enabling this option sets |
X_CSI_REQUIRE_CREDS_NODE_PUB_VOL |
A flag that enables treating the following fields as required:
Enabling this option sets |
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:
|
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. |