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 |
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/sujeet01/gocsi && \
make -C src/github.com/sujeet01/gocsi csi-sp"The root of the GoCSI project enables storage administrators and developers alike to bootstrap a CSI SP:
$ ./gocsi.sh
usage: ./gocsi.sh GO_IMPORT_PATHThe 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-spThe new SP adheres to the following structure:
|-- provider
| |
| |-- provider.go
|
|-- service
| |
| |-- controller.go
| |-- identity.go
| |-- node.go
| |-- service.go
|
|-- main.go
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.
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).
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).
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. |