https://github.com/errordeveloper/gocsi

A Container Storage Interface (CSI) library, client, and other helpful utilities created with Go.
https://github.com/errordeveloper/gocsi

Last synced: 5 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/errordeveloper/gocsi
• Owner: errordeveloper
• License: apache-2.0
• Fork: true (rexray/gocsi)
• Created: 2021-12-08T13:35:56.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2021-12-08T13:36:04.000Z (over 4 years ago)
• Last Synced: 2024-06-20T10:22:28.118Z (about 2 years ago)
• Language: Go
• Size: 12.7 MB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: .github/contributing.md
  • License: LICENSE
  • Code of conduct: .github/code_of_conduct.md

Awesome Lists containing this project

README

          
# GoCSI

The Container Storage Interface

([CSI](https://github.com/container-storage-interface/spec))

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](./csc/) | CSI command line interface (CLI) client |

| [gocsi](#bootstrapper) | Go-based CSI SP bootstrapper  |

| [mock](./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`](./csc/) to

invoke the `GetPluginInfo` RPC:

```shell

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

```shell

$ ./gocsi.sh

usage: ./gocsi.sh GO_IMPORT_PATH

```

### Bootstrap Example

The GoCSI [Mock SP](./mock) 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`:

```shell

$ ./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`](./mock/provider/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.

      

    

    

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