csp

package
v0.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 4, 2017 License: Apache-2.0 Imports: 22 Imported by: 0

README

Container Storage Plug-in (CSP)

The CSP package enables the rapid development of Container Storage Interface (CSI) storage plug-ins (SP).

Overview

Creating a new CSI SP using the CSP is simple and straight-forward. The GoCSI Mock SP illustrates the features and configuration options available to a CSI SP by leveraging CSP.

Creating a Storage Plug-in

The script csp.sh can be used to create a new CSI SP:

$ ./csp.sh
usage: ./csp.sh GO_IMPORT_PATH

The following example demonstrates creating a new SP at the Go import path github.com/thecodeteam/csi-sp:

$ ./csp.sh github.com/thecodeteam/csi-sp
creating project directories:
  /home/akutz/go/src/github.com/thecodeteam/csi-sp
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/provider
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/service
creating project files:
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/main.go
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/provider/provider.go
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/service/service.go
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/service/controller.go
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/service/idemp.go
  /home/akutz/go/src/github.com/thecodeteam/csi-sp/service/identity.go
  /home/akutz/go/src/github.com/thecodeteam/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/thecodeteam/csi-sp/csi-sp

The new SP adheres to the following structure:

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

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

  • Add an idempotency provider
  • Supply default values for the SP's environment variable configuration properties

The generated file configures the following options and their default values:

Option Value Description
X_CSI_IDEMP true In concert with the file service/idemp.go, this option enables idempotency for the SP
X_CSI_SUPPORTED_VERSIONS 0.0.0 The CSI versions supported by the SP. Settings this option also relieves the SP of its responsibility to provide an implementation of the RPC GetSupportedVersions

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 csp 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 file idemp.go contains a skeleton implementation of the interface gocsi.IdemptotencyProvider. An SP is able to achieve idempotency simply by implementing the functions contained in this file.

Main

The root, or main, package leverages csp 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_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_SUPPORTED_VERSIONS A space-delimited list of versions formatted MAJOR.MINOR.PATCH. Setting this environment variable bypasses the SP's GetSupportedVersions RPC and returns this list of versions instead.
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 A flag that enables validation of incoming requests and outgoing responses against the CSI specification.
X_CSI_CREATE_VOL_ALREADY_EXISTS

A flag that enables treating CreateVolume responses as successful when they have an associated error code of AlreadyExists.

Enabling this option sets X_CSI_SPEC_VALIDATION=true
X_CSI_DELETE_VOL_NOT_FOUND

A flag that enables treating DeleteVolume responses as successful when they have an associated error code of NotFound.

Enabling this option sets X_CSI_SPEC_VALIDATION=true
X_CSI_REQUIRE_NODE_ID

A flag that enables treating the following fields as required:

  • ControllerPublishVolumeRequest.NodeId
  • GetNodeIDResponse.NodeId

Enabling this option sets X_CSI_SPEC_VALIDATION=true
X_CSI_REQUIRE_PUB_VOL_INFO

A flag that enables treating the following fields as required:

  • ControllerPublishVolumeResponse.PublishVolumeInfo
  • NodePublishVolumeRequest.PublishVolumeInfo

Enabling this option sets X_CSI_SPEC_VALIDATION=true
X_CSI_REQUIRE_VOL_ATTRIBS

A flag that enables treating the following fields as required:

  • ControllerPublishVolumeRequest.VolumeAttributes
  • ValidateVolumeCapabilitiesRequest.VolumeAttributes
  • NodePublishVolumeRequest.VolumeAttributes

Enabling this option sets X_CSI_SPEC_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_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_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_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_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_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_VALIDATION=true
X_CSI_REQUIRE_CREDS_NODE_UNPUB_VOL

A flag that enables treating the following fields as required:

  • NodeUnpublishVolumeRequest.UserCredentials

Enabling this option sets X_CSI_SPEC_VALIDATION=true
X_CSI_IDEMP A flag that enables the idempotency interceptor. Even when true, the StoragePlugin must still provide a valid IdempotencyProvider in order to enable the idempotency interceptor.
X_CSI_IDEMP_TIMEOUT A time.Duration string that determines how long the idempotency interceptor 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_IDEMP_REQUIRE_VOL A flag that indicates whether the idempotency interceptor validates the existence of a volume before allowing an operation to proceed.

Documentation

Index

Constants

View Source 
const (
	// EnvVarEndpoint is the name of the environment variable used to
	// specify the CSI endpoint.
	EnvVarEndpoint = "CSI_ENDPOINT"

	// 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. This setting has no effect if CSI_ENDPOINT
	// specifies a TCP socket. The default value is 0755.
	EnvVarEndpointPerms = "X_CSI_ENDPOINT_PERMS"

	// 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. This setting has no effect if CSI_ENDPOINT
	// specifies a TCP socket. The default value is the user that starts
	// the process.
	EnvVarEndpointUser = "X_CSI_ENDPOINT_USER"

	// 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. This setting has no effect if CSI_ENDPOINT
	// specifies a TCP socket. The default value is the group that starts
	// the process.
	EnvVarEndpointGroup = "X_CSI_ENDPOINT_GROUP"

	// EnvVarDebug is the name of the environment variable used to
	// determine whether or not debug mode is enabled.
	//
	// Setting this environment variable to a truthy value is the
	// equivalent of X_CSI_LOG_LEVEL=DEBUG, X_CSI_REQ_LOGGING=true,
	// and X_CSI_REP_LOGGING=true.
	EnvVarDebug = "X_CSI_DEBUG"

	// EnvVarLogLevel is the name of the environment variable used to
	// specify the log level. Valid values include PANIC, FATAL, ERROR,
	// WARN, INFO, and DEBUG.
	EnvVarLogLevel = "X_CSI_LOG_LEVEL"

	// EnvVarSupportedVersions is the name of the environment variable used
	// to specify a list of comma-separated versions supported by the SP. If
	// no value is specified then the SP does not perform a version check on
	// the RPC.
	EnvVarSupportedVersions = "X_CSI_SUPPORTED_VERSIONS"

	// 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.
	//
	// Please see the encoding/csv package (https://goo.gl/1j1xb9) for
	// information on how to quote keys and/or values to include leading
	// and trailing whitespace.
	//
	// Setting this environment variable will cause the program to
	// bypass the SP's GetPluginInfo RPC and returns the specified
	// information instead.
	EnvVarPluginInfo = "X_CSI_PLUGIN_INFO"

	// EnvVarNodeSvcOnly is the name of the environment variable
	// used to specify that only the CSI Node Service should be started,
	// meaning that the Controller service should not
	EnvVarNodeSvcOnly = "X_CSI_NODESVC_ONLY"

	// EnvVarCtrlSvcOnly is the name of the environment variable
	// used to specify that only the CSI Controller Service should be
	// started, meaning that the Node service should not
	EnvVarCtrlSvcOnly = "X_CSI_CTRLSVC_ONLY"

	// EnvVarReqLogging is the name of the environment variable
	// used to determine whether or not to enable request logging.
	//
	// Setting this environment variable to a truthy value enables
	// request logging to STDOUT.
	EnvVarReqLogging = "X_CSI_REQ_LOGGING"

	// EnvVarRepLogging is the name of the environment variable
	// used to determine whether or not to enable response logging.
	//
	// Setting this environment variable to a truthy value enables
	// response logging to STDOUT.
	EnvVarRepLogging = "X_CSI_REP_LOGGING"

	// EnvVarReqIDInjection is the name of the environment variable
	// used to determine whether or not to enable request ID injection.
	EnvVarReqIDInjection = "X_CSI_REQ_ID_INJECTION"

	// EnvVarSpecValidation is the name of the environment variable
	// used to determine whether or not to enable validation of incoming
	// requests and outgoing responses against the CSI specification.
	EnvVarSpecValidation = "X_CSI_SPEC_VALIDATION"

	// EnvVarCreateVolAlreadyExistsSuccess is the name of the environment
	// variable used to determine whether or not to treat CreateVolume
	// responses with an error code of AlreadyExists as a successful.
	EnvVarCreateVolAlreadyExistsSuccess = "X_CSI_CREATE_VOL_ALREADY_EXISTS"

	// EnvVarDeleteVolNotFoundSuccess is the name of the environment
	// variable used to determine whether or not to treat DeleteVolume
	// responses with an error code of NotFound as a successful.
	EnvVarDeleteVolNotFoundSuccess = "X_CSI_DELETE_VOL_NOT_FOUND"

	// EnvVarRequireNodeID is the name of the environment variable used
	// to determine whether or not the node ID value is required for
	// requests that accept it and responses that return it such as
	// ControllerPublishVolume and GetNodeId.
	EnvVarRequireNodeID = "X_CSI_REQUIRE_NODE_ID"

	// EnvVarRequirePubVolInfo is the name of the environment variable used
	// to determine whether or not publish volume info is required for
	// requests that accept it and responses that return it such as
	// NodePublishVolume and ControllerPublishVolume.
	EnvVarRequirePubVolInfo = "X_CSI_REQUIRE_PUB_VOL_INFO"

	// EnvVarRequireVolAttribs is the name of the environment variable used
	// to determine whether or not volume attributes are required for
	// requests that accept them and responses that return them such as
	// ControllerPublishVolume and CreateVolume.
	EnvVarRequireVolAttribs = "X_CSI_REQUIRE_VOL_ATTRIBS"

	// EnvVarCreds is the name of the environment variable
	// used to determine whether or not user credentials are required for
	// all RPCs. This value may be overridden for specific RPCs.
	EnvVarCreds = "X_CSI_REQUIRE_CREDS"

	// EnvVarCredsCreateVol is the name of the environment variable
	// used to determine whether or not user credentials are required for
	// the eponymous RPC.
	EnvVarCredsCreateVol = "X_CSI_REQUIRE_CREDS_CREATE_VOL"

	// EnvVarCredsDeleteVol is the name of the environment variable
	// used to determine whether or not user credentials are required for
	// the eponymous RPC.
	EnvVarCredsDeleteVol = "X_CSI_REQUIRE_CREDS_DELETE_VOL"

	// EnvVarCredsCtrlrPubVol is the name of the environment
	// variable used to determine whether or not user credentials are required
	// for the eponymous RPC.
	EnvVarCredsCtrlrPubVol = "X_CSI_REQUIRE_CREDS_CTRLR_PUB_VOL"

	// EnvVarCredsCtrlrUnpubVol is the name of the
	// environment variable used to determine whether or not user credentials
	// are required for the eponymous RPC.
	EnvVarCredsCtrlrUnpubVol = "X_CSI_REQUIRE_CREDS_CTRLR_UNPUB_VOL"

	// EnvVarCredsNodePubVol is the name of the environment
	// variable used to determine whether or not user credentials are required
	// for the eponymous RPC.
	EnvVarCredsNodePubVol = "X_CSI_REQUIRE_CREDS_NODE_PUB_VOL"

	// EnvVarCredsNodeUnpubVol is the name of the environment
	// variable used to determine whether or not user credentials are required
	// for the eponymous RPC.
	EnvVarCredsNodeUnpubVol = "X_CSI_REQUIRE_CREDS_NODE_UNPUB_VOL"

	// EnvVarIdemp is the name of the environment variable
	// used to determine whether or not to enable idempotency.
	EnvVarIdemp = "X_CSI_IDEMP"

	// EnvVarIdempTimeout is the name of the environment variable
	// used to specify the timeout for gRPC operations.
	EnvVarIdempTimeout = "X_CSI_IDEMP_TIMEOUT"

	// EnvVarIdempRequireVolume is the name of the environment variable
	// used to determine whether or not the idempotency interceptor
	// checks to see if a volume exists before allowing an operation.
	EnvVarIdempRequireVolume = "X_CSI_IDEMP_REQUIRE_VOL"

	// EnvVarPrivateMountDir is the name of the environment variable
	// that specifies the path of the private mount directory used by
	// SPs to mount a device during a NodePublishVolume RPC before
	// bind mounting the file/directory from the private mount area
	// to the target path.
	EnvVarPrivateMountDir = "X_CSI_PRIVATE_MOUNT_DIR"
)

Variables

This section is empty.

Functions

func Run 

func Run(
	ctx context.Context,
	appName, appDescription, appUsage string,
	sp StoragePluginProvider)

Run launches a CSI storage plug-in.

Types

type StoragePlugin 

type StoragePlugin struct {
	// Controller is the eponymous CSI service.
	Controller csi.ControllerServer

	// Identity is the eponymous CSI service.
	Identity csi.IdentityServer

	// Node is the eponymous CSI service.
	Node csi.NodeServer

	// ServerOpts is a list of gRPC server options used when serving
	// the SP. This list should not include a gRPC interceptor option
	// as one is created automatically based on the interceptor configuration
	// or provided list of interceptors.
	ServerOpts []grpc.ServerOption

	// Interceptors is a list of gRPC server interceptors to use when
	// serving the SP. This list should not include the interceptors
	// defined in the GoCSI package as those are configured by default
	// based on runtime configuration settings.
	Interceptors []grpc.UnaryServerInterceptor

	// IdempotencyProvider is used to provide a simple way of ensuring the
	// SP is idempotent. If this value nil then the SP is responsible for
	// ensuring idempotency.
	IdempotencyProvider gocsi.IdempotencyProvider

	// BeforeServe is an optional callback that is invoked after the
	// StoragePlugin has been initialized, just prior to the creation
	// of the gRPC server. This callback may be used to perform custom
	// initialization logic, modify the interceptors and server options,
	// or prevent the server from starting by returning a non-nil error.
	BeforeServe func(context.Context, *StoragePlugin, net.Listener) error

	// EnvVars is a list of default environment variables and values.
	EnvVars []string
	// contains filtered or unexported fields
}

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

func (*StoragePlugin) GracefulStop 

func (sp *StoragePlugin) GracefulStop(ctx context.Context)

GracefulStop stops the gRPC server gracefully. It stops the server from accepting new connections and RPCs and blocks until all the pending RPCs are finished.

func (*StoragePlugin) Serve 

func (sp *StoragePlugin) Serve(ctx context.Context, lis net.Listener) error

Serve accepts incoming connections on the listener lis, creating a new ServerTransport and service goroutine for each. The service goroutine read gRPC requests and then call the registered handlers to reply to them. Serve returns when lis.Accept fails with fatal errors. lis will be closed when this method returns. Serve always returns non-nil error.

func (*StoragePlugin) Stop 

func (sp *StoragePlugin) Stop(ctx context.Context)

Stop stops the gRPC server. It immediately closes all open connections and listeners. It cancels all active RPCs on the server side and the corresponding pending RPCs on the client side will get notified by connection errors.

type StoragePluginProvider 

type StoragePluginProvider interface {

	// Serve accepts incoming connections on the listener lis, creating
	// a new ServerTransport and service goroutine for each. The service
	// goroutine read gRPC requests and then call the registered handlers
	// to reply to them. Serve returns when lis.Accept fails with fatal
	// errors.  lis will be closed when this method returns.
	// Serve always returns non-nil error.
	Serve(ctx context.Context, lis net.Listener) error

	// Stop stops the gRPC server. It immediately closes all open
	// connections and listeners.
	// It cancels all active RPCs on the server side and the corresponding
	// pending RPCs on the client side will get notified by connection
	// errors.
	Stop(ctx context.Context)

	// GracefulStop stops the gRPC server gracefully. It stops the server
	// from accepting new connections and RPCs and blocks until all the
	// pending RPCs are finished.
	GracefulStop(ctx context.Context)
}

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.