Categorygithub.com/rexray/gocsi
modulepackage
1.2.2
Repository: https://github.com/rexray/gocsi.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
28
Dependents
37
Files
1.3k SLOC

# README

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):

ComponentDescription
cscCSI command line interface (CLI) client
gocsiGo-based CSI SP bootstrapper
mockMock 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:

NameDescription
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_DEBUGA 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_INJECTIONA 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_VALIDATIONSetting 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_VALIDATIONA flag that enables the validation of CSI request messages.
X_CSI_SPEC_REP_VALIDATIONA 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_CHECKA 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_CREDSA 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_ACCESSA flag that enables the serial volume access middleware.
X_CSI_SERIAL_VOL_ACCESS_TIMEOUTA 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_ENDPOINTSA 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_DOMAINThe 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_TTLThe 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_INTERVALA 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_TIMEOUTA time.Duration string that specifies the timeout for failing to establish a connection.
X_CSI_SERIAL_VOL_ACCESS_ETCD_DIAL_KEEP_ALIVE_TIMEA 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_TIMEOUTA 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_SZDefines 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_SZDefines 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_USERNAMEThe user name used for authentication.
X_CSI_SERIAL_VOL_ACCESS_ETCD_PASSWORDThe password used for authentication.
X_CSI_SERIAL_VOL_ACCESS_ETCD_REJECT_OLD_CLUSTERA flag that indicates refusal to create a client against an outdated cluster.
X_CSI_SERIAL_VOL_ACCESS_ETCD_TLSA flag that indicates the client should use TLS.
X_CSI_SERIAL_VOL_ACCESS_ETCD_TLS_INSECUREA flag that indicates the TLS connection should not verify peer certificates.

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

Run launches a CSI storage plug-in.

# Constants

EnvVarCreds is the name of the environment variable used to determine whether or not user credentials are required for all RPCs.
EnvVarCredsCreateVol is the name of the environment variable used to determine whether or not user credentials are required for the eponymous RPC.
EnvVarCredsCtrlrPubVol is the name of the environment variable used to determine whether or not user credentials are required for the eponymous RPC.
EnvVarCredsCtrlrUnpubVol is the name of the environment variable used to determine whether or not user credentials are required for the eponymous RPC.
EnvVarCredsDeleteVol is the name of the environment variable used to determine whether or not user credentials are required for the eponymous RPC.
EnvVarCredsNodePubVol is the name of the environment variable used to determine whether or not user credentials are required for the eponymous RPC.
EnvVarCredsNodeStgVol is the name of the environment variable used to determine whether or not user credentials are required for the eponymous RPC.
EnvVarDebug is the name of the environment variable used to determine whether or not debug mode is enabled.
EnvVarDisableFieldLen is the name of the environment variable used to determine whether or not to disable validation of CSI request and response field lengths against the permitted lenghts defined in the spec.
EnvVarEndpoint is the name of the environment variable used to specify the CSI endpoint.
EnvVarEndpointGroup is the name of the environment variable used to specify the GID or name of the group that owns the endpoint's UNIX socket file.
EnvVarEndpointPerms is the name of the environment variable used to specify the file permissions for the CSI endpoint when it is a UNIX socket file.
EnvVarEndpointUser is the name of the environment variable used to specify the UID or name of the user that owns the endpoint's UNIX socket file.
EnvVarLoggingDisableVolCtx is the name of the environment variable used to disable the logging of the VolumeContext field when request or response logging is enabled.
EnvVarLogLevel is the name of the environment variable used to specify the log level.
EnvVarMode is the name of the environment variable used to specify the service mode of the storage plug-in.
EnvVarPluginInfo is the name of the environment variable used to specify the plug-in info in the format: NAME, VENDOR_VERSION[, MANIFEST...] The MANIFEST value may be a series of additional comma-separated key/value pairs.
EnvVarRepLogging is the name of the environment variable used to determine whether or not to enable response logging.
EnvVarReqIDInjection is the name of the environment variable used to determine whether or not to enable request ID injection.
EnvVarReqLogging is the name of the environment variable used to determine whether or not to enable request logging.
EnvVarRequirePubContext is the name of the environment variable used to determine whether or not publish context is required for requests that accept it and responses that return it such as NodePublishVolume and ControllerPublishVolume.
EnvVarRequireStagingTargetPath is the name of the environment variable used to determine whether or not the NodePublishVolume request field StagingTargetPath is required.
EnvVarRequireVolContext is the name of the environment variable used to determine whether or not volume context is required for requests that accept it and responses that return it such as NodePublishVolume and ControllerPublishVolume.
EnvVarSerialVolAccess is the name of the environment variable used to determine whether or not to enable serial volume access.
EnvVarSerialVolAccessEtcdAutoSyncInterval is the name of the environment variable that defines the interval to update endpoints with its latest members.
EnvVarSerialVolAccessEtcdDialKeepAliveTime is the name of the environment variable that defines the time after which client pings the server to see if transport is alive.
EnvVarSerialVolAccessEtcdDialKeepAliveTimeout is the name of the environment variable that defines the time that the client waits for a response for the keep-alive probe.
EnvVarSerialVolAccessEtcdDialTimeout is the name of the environment variable that defines the timeout for failing to establish a connection.
EnvVarSerialVolAccessEtcdDomain is the name of the environment variable that defines the lock provider's concurrency domain.
EnvVarSerialVolAccessEtcdEndpoints is the name of the environment variable that defines the lock provider's etcd endoints.
EnvVarSerialVolAccessEtcdMaxCallRecvMsgSz is the name of the environment variable that defines the client-side response receive limit.
EnvVarSerialVolAccessEtcdMaxCallSendMsgSz is the name of the environment variable that defines the client-side request send limit in bytes.
EnvVarSerialVolAccessEtcdPassword is the name of the environment variable that defines the password used for authentication.
EnvVarSerialVolAccessEtcdRejectOldCluster is the name of the environment variable that defines when set will refuse to create a client against an outdated cluster.
EnvVarSerialVolAccessEtcdTLS is the name of the environment variable that defines whether or not the client should attempt to use TLS when connecting to the server.
EnvVarSerialVolAccessEtcdTLSInsecure is the name of the environment variable that defines whether or not the TLS connection should verify certificates.
EnvVarSerialVolAccessEtcdTTL is the name of the environment variable that defines the length of time etcd will wait before releasing ownership of a distributed lock if the lock's session has not been renewed.
EnvVarSerialVolAccessEtcdUsername is the name of the environment variable that defines the user name used for authentication.
EnvVarSerialVolAccessTimeout is the name of the environment variable used to specify the timeout for obtaining a volume lock.
EnvVarSpecRepValidation is the name of the environment variable used to determine whether or not to enable validation of CSI response messages.
EnvVarSpecReqValidation is the name of the environment variable used to determine whether or not to enable validation of CSI request messages.
EnvVarSpecValidation is the name of the environment variable used to determine whether or not to enable validation of CSI request and response messages.

# Structs

StoragePlugin is the collection of services and data used to server a new gRPC endpoint that acts as a CSI storage plug-in (SP).

# Interfaces

StoragePluginProvider is able to serve a gRPC endpoint that provides the CSI services: Controller, Identity, Node.