sanity

README

CSI Driver Sanity Tester

This library provides a simple way to ensure that a CSI driver conforms to the CSI specification. There are two ways to leverage this testing framework. For CSI drivers written in Golang, the framework provides a simple API function to call to test the driver. Another way to run the test suite is to use the command line program csi-sanity.

For Golang CSI Drivers

This framework leverages the Ginkgo BDD testing framework to deliver a descriptive test suite for your driver. To test your driver, simply call the API in one of your Golang TestXXX functions. For example:

func TestMyDriver(t *testing.T) {
	// Setup the full driver and its environment
	... setup driver ...
	config := &sanity.Config{
		TargetPath:     ...
		StagingPath:    ...
		Address:        endpoint,
	}


	// Now call the test suite
	sanity.Test(t, config)
}

Only one such test function is supported because under the hood a Ginkgo test suite gets constructed and executed by the call.

Alternatively, the tests can also be embedded inside a Ginkgo test suite. In that case it is possible to define multiple tests with different configurations:

var _ = Describe("MyCSIDriver", func () {
	Context("Config A", func () {
		var config &sanity.Config

		BeforeEach(func() {
			//... setup driver and config...
		})

		AfterEach(func() {
			//...tear down driver...
		})

		Describe("CSI sanity", func() {
			sanity.GinkgoTest(config)
		})
	})

	Context("Config B", func () {
		// other configs
	})
})

Command line program

Please see csi-sanity

Documentation

Index

• Constants
• func ControllerUnpublishAndDeleteVolume(sc *SanityContext, c csi.ControllerClient, volID, nodeID string) error
• func CreateAndControllerPublishVolume(sc *SanityContext, c csi.ControllerClient, volName, nodeID string) (volID string, err error)
• func DescribeSanity(text string, body func(*SanityContext)) bool
• func GinkgoTest(reqConfig *Config)
• func MakeControllerPublishVolumeReq(sc *SanityContext, volID, nodeID string) *csi.ControllerPublishVolumeRequest
• func MakeControllerUnpublishVolumeReq(sc *SanityContext, volID, nodeID string) *csi.ControllerUnpublishVolumeRequest
• func MakeCreateSnapshotReq(sc *SanityContext, name, sourceVolumeId string, parameters map[string]string) *csi.CreateSnapshotRequest
• func MakeCreateVolumeReq(sc *SanityContext, name string) *csi.CreateVolumeRequest
• func MakeDeleteSnapshotReq(sc *SanityContext, id string) *csi.DeleteSnapshotRequest
• func MakeDeleteVolumeReq(sc *SanityContext, id string) *csi.DeleteVolumeRequest
• func PseudoUUID() string
• func Test(t *testing.T, reqConfig *Config)
• func TestVolumeSize(sc *SanityContext) int64
• func UniqueString(prefix string) string
• type CSISecrets
• type Cleanup
  • func (cl *Cleanup) DeleteVolumes()
  • func (cl *Cleanup) MaybeRegisterVolume(name string, vol *csi.CreateVolumeResponse, err error)
  • func (cl *Cleanup) RegisterVolume(name string, info VolumeInfo)
  • func (cl *Cleanup) UnregisterVolume(name string)
• type Config
• type SanityContext
  • func (sc *SanityContext) Setup()
  • func (sc *SanityContext) Teardown()
• type VolumeInfo

Constants

const (
	// DefTestVolumeSize defines the base size of dynamically
	// provisioned volumes. 10GB by default, can be overridden by
	// setting Config.TestVolumeSize.
	DefTestVolumeSize int64 = 10 * 1024 * 1024 * 1024

	MaxNameLength int = 128
)

Functions

func ControllerUnpublishAndDeleteVolume

func ControllerUnpublishAndDeleteVolume(sc *SanityContext, c csi.ControllerClient, volID, nodeID string) error

ControllerUnpublishAndDeleteVolume controller unpublishes and deletes a volume, given volume ID and node ID.

func CreateAndControllerPublishVolume

func CreateAndControllerPublishVolume(sc *SanityContext, c csi.ControllerClient, volName, nodeID string) (volID string, err error)

CreateAndControllerPublishVolume creates and controller publishes a volume given a volume name and node ID.

func DescribeSanity

func DescribeSanity(text string, body func(*SanityContext)) bool

DescribeSanity must be used instead of the usual Ginkgo Describe to register a test block. The difference is that the body function will be called multiple times with the right context (when setting up a Ginkgo suite or a testing.T test, with the right configuration).

func GinkgoTest

func GinkgoTest(reqConfig *Config)

func MakeControllerPublishVolumeReq

func MakeControllerPublishVolumeReq(sc *SanityContext, volID, nodeID string) *csi.ControllerPublishVolumeRequest

MakeControllerPublishVolumeReq creates and returns a ControllerPublishVolumeRequest.

func MakeControllerUnpublishVolumeReq

func MakeControllerUnpublishVolumeReq(sc *SanityContext, volID, nodeID string) *csi.ControllerUnpublishVolumeRequest

MakeControllerUnpublishVolumeReq creates and returns a ControllerUnpublishVolumeRequest.

func MakeCreateSnapshotReq

func MakeCreateSnapshotReq(sc *SanityContext, name, sourceVolumeId string, parameters map[string]string) *csi.CreateSnapshotRequest

func MakeCreateVolumeReq

func MakeCreateVolumeReq(sc *SanityContext, name string) *csi.CreateVolumeRequest

func MakeDeleteSnapshotReq

func MakeDeleteSnapshotReq(sc *SanityContext, id string) *csi.DeleteSnapshotRequest

func MakeDeleteVolumeReq

func MakeDeleteVolumeReq(sc *SanityContext, id string) *csi.DeleteVolumeRequest

func PseudoUUID

func PseudoUUID() string

PseudoUUID returns a unique string generated from random bytes, empty string in case of error.

func Test

func Test(t *testing.T, reqConfig *Config)

Test will test the CSI driver at the specified address by setting up a Ginkgo suite and running it.

func TestVolumeSize

func TestVolumeSize(sc *SanityContext) int64

func UniqueString

func UniqueString(prefix string) string

UniqueString returns a unique string by appending a random number. In case of an error, just the prefix is returned, so it alone should already be fairly unique.

Types

type CSISecrets

type CSISecrets struct {
	CreateVolumeSecret                         map[string]string `yaml:"CreateVolumeSecret"`
	DeleteVolumeSecret                         map[string]string `yaml:"DeleteVolumeSecret"`
	ControllerPublishVolumeSecret              map[string]string `yaml:"ControllerPublishVolumeSecret"`
	ControllerUnpublishVolumeSecret            map[string]string `yaml:"ControllerUnpublishVolumeSecret"`
	ControllerValidateVolumeCapabilitiesSecret map[string]string `yaml:"ControllerValidateVolumeCapabilitiesSecret"`
	NodeStageVolumeSecret                      map[string]string `yaml:"NodeStageVolumeSecret"`
	NodePublishVolumeSecret                    map[string]string `yaml:"NodePublishVolumeSecret"`
	CreateSnapshotSecret                       map[string]string `yaml:"CreateSnapshotSecret"`
	DeleteSnapshotSecret                       map[string]string `yaml:"DeleteSnapshotSecret"`
}

CSISecrets consists of secrets used in CSI credentials.

type Cleanup

type Cleanup struct {
	Context                    *SanityContext
	ControllerClient           csi.ControllerClient
	NodeClient                 csi.NodeClient
	ControllerPublishSupported bool
	NodeStageSupported         bool
	// contains filtered or unexported fields
}

Cleanup keeps track of resources, in particular volumes, which need to be freed when testing is done.

func (*Cleanup) DeleteVolumes

func (cl *Cleanup) DeleteVolumes()

DeleteVolumes stops using the registered volumes and tries to delete all of them.

func (*Cleanup) MaybeRegisterVolume

func (cl *Cleanup) MaybeRegisterVolume(name string, vol *csi.CreateVolumeResponse, err error)

MaybeRegisterVolume adds or updates an entry for the volume with the given name if CreateVolume was successful.

func (*Cleanup) RegisterVolume

func (cl *Cleanup) RegisterVolume(name string, info VolumeInfo)

RegisterVolume adds or updates an entry for the volume with the given name.

func (*Cleanup) UnregisterVolume

func (cl *Cleanup) UnregisterVolume(name string)

UnregisterVolume removes the entry for the volume with the given name, thus preventing all cleanup operations for it.

type Config

type Config struct {
	// TargetPath is the *parent* directory for NodePublishVolumeRequest.target_path.
	// It gets created and removed by csi-sanity.
	TargetPath string

	// StagingPath is the NodeStageVolumeRequest.staging_target_path.
	// It gets created and removed by csi-sanity.
	StagingPath string

	Address           string
	ControllerAddress string
	SecretsFile       string

	TestVolumeSize            int64
	TestVolumeParametersFile  string
	TestVolumeParameters      map[string]string
	TestNodeVolumeAttachLimit bool

	JUnitFile string

	// Callback functions to customize the creation of target and staging
	// directories. Returns the new paths for mount and staging.
	// If not defined, directories are created in the default way at TargetPath
	// and StagingPath on the host.
	//
	// Both functions can replace the suggested path. What the test then uses
	// is the path returned by them.
	//
	// Note that target and staging directory have different
	// semantics in the CSI spec: for NodeStateVolume,
	// CreateTargetDir must create the directory and return the
	// full path to it. For NodePublishVolume, CreateStagingDir
	// must create the *parent* directory of `path` (or some other
	// directory) and return the full path for an entry inside
	// that created directory.
	CreateTargetDir  func(path string) (string, error)
	CreateStagingDir func(path string) (string, error)

	// Callback functions to customize the removal of the target and staging
	// directories.
	// If not defined, directories are removed in the default way at TargetPath
	// and StagingPath on the host.
	//
	// Both functions are passed the actual paths as used during the test.
	//
	// Note that RemoveTargetPath only needs to remove the *parent* of the
	// given path. The CSI driver should have removed the entry at that path
	// already.
	RemoveTargetPath  func(path string) error
	RemoveStagingPath func(path string) error

	// Commands to be executed for customized creation of the target and staging
	// paths. This command must be available on the host where sanity runs. The
	// stdout of the commands are the paths for mount and staging.
	CreateTargetPathCmd  string
	CreateStagingPathCmd string
	// Timeout for the executed commands for path creation.
	CreatePathCmdTimeout int

	// Commands to be executed for customized removal of the target and staging
	// paths. Thie command must be available on the host where sanity runs.
	RemoveTargetPathCmd  string
	RemoveStagingPathCmd string
	// Timeout for the executed commands for path removal.
	RemovePathCmdTimeout int
}

Config provides the configuration for the sanity tests. It needs to be initialized by the user of the sanity package.

type SanityContext

type SanityContext struct {
	Config         *Config
	Conn           *grpc.ClientConn
	ControllerConn *grpc.ClientConn
	Secrets        *CSISecrets

	// Target and staging paths derived from the sanity config.
	TargetPath  string
	StagingPath string
	// contains filtered or unexported fields
}

SanityContext holds the variables that each test can depend on. It gets initialized before each test block runs.

func (*SanityContext) Setup

func (sc *SanityContext) Setup()

func (*SanityContext) Teardown

func (sc *SanityContext) Teardown()

type VolumeInfo

type VolumeInfo struct {
	// Node on which the volume was published, empty if none
	// or publishing is not supported.
	NodeID string

	// Volume ID assigned by CreateVolume.
	VolumeID string
}

VolumeInfo keeps track of the information needed to delete a volume.