csi

package
v0.12.8 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2020 License: MPL-2.0 Imports: 17 Imported by: 45

Documentation

Index

Constants

View Source
const PluginTypeCSI = "csi"

PluginTypeCSI implements the CSI plugin interface

Variables

Functions

This section is empty.

Types

type CSIControllerClient

CSIControllerClient defines the minimal CSI Controller Plugin interface used by nomad to simplify the interface required for testing.

type CSINodeClient

CSINodeClient defines the minimal CSI Node Plugin interface used by nomad to simplify the interface required for testing.

type CSIPlugin

type CSIPlugin interface {
	base.BasePlugin

	// PluginProbe is used to verify that the plugin is in a healthy state
	PluginProbe(ctx context.Context) (bool, error)

	// PluginGetInfo is used to return semantic data about the plugin.
	// Response:
	//  - string: name, the name of the plugin in domain notation format.
	//  - string: version, the vendor version of the plugin
	PluginGetInfo(ctx context.Context) (string, string, error)

	// PluginGetCapabilities is used to return the available capabilities from the
	// identity service. This currently only looks for the CONTROLLER_SERVICE and
	// Accessible Topology Support
	PluginGetCapabilities(ctx context.Context) (*PluginCapabilitySet, error)

	// GetControllerCapabilities is used to get controller-specific capabilities
	// for a plugin.
	ControllerGetCapabilities(ctx context.Context) (*ControllerCapabilitySet, error)

	// ControllerPublishVolume is used to attach a remote volume to a cluster node.
	ControllerPublishVolume(ctx context.Context, req *ControllerPublishVolumeRequest, opts ...grpc.CallOption) (*ControllerPublishVolumeResponse, error)

	// ControllerUnpublishVolume is used to deattach a remote volume from a cluster node.
	ControllerUnpublishVolume(ctx context.Context, req *ControllerUnpublishVolumeRequest, opts ...grpc.CallOption) (*ControllerUnpublishVolumeResponse, error)

	// ControllerValidateCapabilities is used to validate that a volume exists and
	// supports the requested capability.
	ControllerValidateCapabilities(ctx context.Context, req *ControllerValidateVolumeRequest, opts ...grpc.CallOption) error

	// NodeGetCapabilities is used to return the available capabilities from the
	// Node Service.
	NodeGetCapabilities(ctx context.Context) (*NodeCapabilitySet, error)

	// NodeGetInfo is used to return semantic data about the current node in
	// respect to the SP.
	NodeGetInfo(ctx context.Context) (*NodeGetInfoResponse, error)

	// NodeStageVolume is used when a plugin has the STAGE_UNSTAGE volume capability
	// to prepare a volume for usage on a host. If err == nil, the response should
	// be assumed to be successful.
	NodeStageVolume(ctx context.Context, req *NodeStageVolumeRequest, opts ...grpc.CallOption) error

	// NodeUnstageVolume is used when a plugin has the STAGE_UNSTAGE volume capability
	// to undo the work performed by NodeStageVolume. If a volume has been staged,
	// this RPC must be called before freeing the volume.
	//
	// If err == nil, the response should be assumed to be successful.
	NodeUnstageVolume(ctx context.Context, volumeID string, stagingTargetPath string, opts ...grpc.CallOption) error

	// NodePublishVolume is used to prepare a volume for use by an allocation.
	// if err == nil the response should be assumed to be successful.
	NodePublishVolume(ctx context.Context, req *NodePublishVolumeRequest, opts ...grpc.CallOption) error

	// NodeUnpublishVolume is used to cleanup usage of a volume for an alloc. This
	// MUST be called before calling NodeUnstageVolume or ControllerUnpublishVolume
	// for the given volume.
	NodeUnpublishVolume(ctx context.Context, volumeID, targetPath string, opts ...grpc.CallOption) error

	// Shutdown the client and ensure any connections are cleaned up.
	Close() error
}

CSIPlugin implements a lightweight abstraction layer around a CSI Plugin. It validates that responses from storage providers (SP's), correctly conform to the specification before returning response data or erroring.

func NewClient

func NewClient(addr string, logger hclog.Logger) (CSIPlugin, error)

type ControllerCapabilitySet

type ControllerCapabilitySet struct {
	HasPublishUnpublishVolume    bool
	HasPublishReadonly           bool
	HasListVolumes               bool
	HasListVolumesPublishedNodes bool
}

type ControllerPublishVolumeRequest

type ControllerPublishVolumeRequest struct {
	ExternalID       string
	NodeID           string
	ReadOnly         bool
	VolumeCapability *VolumeCapability
	Secrets          structs.CSISecrets
	VolumeContext    map[string]string
}

func (*ControllerPublishVolumeRequest) ToCSIRepresentation

func (*ControllerPublishVolumeRequest) Validate

func (r *ControllerPublishVolumeRequest) Validate() error

type ControllerPublishVolumeResponse

type ControllerPublishVolumeResponse struct {
	PublishContext map[string]string
}

type ControllerUnpublishVolumeRequest

type ControllerUnpublishVolumeRequest struct {
	ExternalID string
	NodeID     string
	Secrets    structs.CSISecrets
}

func (*ControllerUnpublishVolumeRequest) ToCSIRepresentation

func (*ControllerUnpublishVolumeRequest) Validate

type ControllerUnpublishVolumeResponse

type ControllerUnpublishVolumeResponse struct{}

type ControllerValidateVolumeRequest added in v0.11.3

type ControllerValidateVolumeRequest struct {
	ExternalID   string
	Secrets      structs.CSISecrets
	Capabilities *VolumeCapability
	Parameters   map[string]string
	Context      map[string]string
}

func (*ControllerValidateVolumeRequest) ToCSIRepresentation added in v0.11.3

type NodeCapabilitySet

type NodeCapabilitySet struct {
	HasStageUnstageVolume bool
}

type NodeGetInfoResponse

type NodeGetInfoResponse struct {
	NodeID             string
	MaxVolumes         int64
	AccessibleTopology *Topology
}

type NodePublishVolumeRequest

type NodePublishVolumeRequest struct {
	// The external ID of the volume to publish.
	ExternalID string

	// If the volume was attached via a call to `ControllerPublishVolume` then
	// we need to provide the returned PublishContext here.
	PublishContext map[string]string

	// The path to which the volume was staged by `NodeStageVolume`.
	// It MUST be an absolute path in the root filesystem of the process
	// serving this request.
	// E.g {the plugins internal mount path}/staging/volumeid/...
	//
	// It MUST be set if the Node Plugin implements the
	// `STAGE_UNSTAGE_VOLUME` node capability.
	StagingTargetPath string

	// The path to which the volume will be published.
	// It MUST be an absolute path in the root filesystem of the process serving this
	// request.
	// E.g {the plugins internal mount path}/per-alloc/allocid/volumeid/...
	//
	// The CO SHALL ensure uniqueness of target_path per volume.
	// The CO SHALL ensure that the parent directory of this path exists
	// and that the process serving the request has `read` and `write`
	// permissions to that parent directory.
	TargetPath string

	// Volume capability describing how the CO intends to use this volume.
	VolumeCapability *VolumeCapability

	Readonly bool

	// Secrets required by plugins to complete the node publish volume
	// request. This field is OPTIONAL.
	Secrets structs.CSISecrets

	// Volume context as returned by SP in the CSI
	// CreateVolumeResponse.Volume.volume_context which we don't implement but
	// can be entered by hand in the volume spec.  This field is OPTIONAL.
	VolumeContext map[string]string
}

func (*NodePublishVolumeRequest) ToCSIRepresentation

func (r *NodePublishVolumeRequest) ToCSIRepresentation() *csipbv1.NodePublishVolumeRequest

func (*NodePublishVolumeRequest) Validate

func (r *NodePublishVolumeRequest) Validate() error

type NodeStageVolumeRequest added in v0.12.0

type NodeStageVolumeRequest struct {
	// The external ID of the volume to stage.
	ExternalID string

	// If the volume was attached via a call to `ControllerPublishVolume` then
	// we need to provide the returned PublishContext here.
	PublishContext map[string]string

	// The path to which the volume MAY be staged. It MUST be an
	// absolute path in the root filesystem of the process serving this
	// request, and MUST be a directory. The CO SHALL ensure that there
	// is only one `staging_target_path` per volume. The CO SHALL ensure
	// that the path is directory and that the process serving the
	// request has `read` and `write` permission to that directory. The
	// CO SHALL be responsible for creating the directory if it does not
	// exist.
	// This is a REQUIRED field.
	StagingTargetPath string

	// Volume capability describing how the CO intends to use this volume.
	VolumeCapability *VolumeCapability

	// Secrets required by plugins to complete the node stage volume
	// request. This field is OPTIONAL.
	Secrets structs.CSISecrets

	// Volume context as returned by SP in the CSI
	// CreateVolumeResponse.Volume.volume_context which we don't implement but
	// can be entered by hand in the volume spec.  This field is OPTIONAL.
	VolumeContext map[string]string
}

func (*NodeStageVolumeRequest) ToCSIRepresentation added in v0.12.0

func (r *NodeStageVolumeRequest) ToCSIRepresentation() *csipbv1.NodeStageVolumeRequest

func (*NodeStageVolumeRequest) Validate added in v0.12.0

func (r *NodeStageVolumeRequest) Validate() error

type PluginCapabilitySet

type PluginCapabilitySet struct {
	// contains filtered or unexported fields
}

func NewPluginCapabilitySet

func NewPluginCapabilitySet(capabilities *csipbv1.GetPluginCapabilitiesResponse) *PluginCapabilitySet

func NewTestPluginCapabilitySet

func NewTestPluginCapabilitySet(topologies, controller bool) *PluginCapabilitySet

func (*PluginCapabilitySet) HasControllerService

func (p *PluginCapabilitySet) HasControllerService() bool

func (*PluginCapabilitySet) HasToplogies

func (p *PluginCapabilitySet) HasToplogies() bool

HasTopologies indicates whether the volumes for this plugin are equally accessible by all nodes in the cluster. If true, we MUST use the topology information when scheduling workloads.

func (*PluginCapabilitySet) IsEqual

type Topology

type Topology struct {
	Segments map[string]string
}

Topology is a map of topological domains to topological segments. A topological domain is a sub-division of a cluster, like "region", "zone", "rack", etc.

According to CSI, there are a few requirements for the keys within this map:

  • Valid keys have two segments: an OPTIONAL prefix and name, separated by a slash (/), for example: "com.company.example/zone".
  • The key name segment is REQUIRED. The prefix is OPTIONAL.
  • The key name MUST be 63 characters or less, begin and end with an alphanumeric character ([a-z0-9A-Z]), and contain only dashes (-), underscores (_), dots (.), or alphanumerics in between, for example "zone".
  • The key prefix MUST be 63 characters or less, begin and end with a lower-case alphanumeric character ([a-z0-9]), contain only dashes (-), dots (.), or lower-case alphanumerics in between, and follow domain name notation format (https://tools.ietf.org/html/rfc1035#section-2.3.1).
  • The key prefix SHOULD include the plugin's host company name and/or the plugin name, to minimize the possibility of collisions with keys from other plugins.
  • If a key prefix is specified, it MUST be identical across all topology keys returned by the SP (across all RPCs).
  • Keys MUST be case-insensitive. Meaning the keys "Zone" and "zone" MUST not both exist.
  • Each value (topological segment) MUST contain 1 or more strings.
  • Each string MUST be 63 characters or less and begin and end with an alphanumeric character with '-', '_', '.', or alphanumerics in between.

type VolumeAccessMode

VolumeAccessMode represents the desired access mode of the CSI Volume

func (VolumeAccessMode) String

func (a VolumeAccessMode) String() string

func (VolumeAccessMode) ToCSIRepresentation

type VolumeAccessType

type VolumeAccessType int32

VolumeAccessType represents the filesystem apis that the user intends to use with the volume. E.g whether it will be used as a block device or if they wish to have a mounted filesystem.

var (
	VolumeAccessTypeBlock VolumeAccessType = 1
	VolumeAccessTypeMount VolumeAccessType = 2
)

func (VolumeAccessType) String

func (v VolumeAccessType) String() string

type VolumeCapability

type VolumeCapability struct {
	AccessType VolumeAccessType
	AccessMode VolumeAccessMode

	// Indicate that the volume will be accessed via the filesystem API.
	MountVolume *structs.CSIMountOptions
}

VolumeCapability describes the overall usage requirements for a given CSI Volume

func VolumeCapabilityFromStructs

func VolumeCapabilityFromStructs(sAccessType structs.CSIVolumeAttachmentMode, sAccessMode structs.CSIVolumeAccessMode) (*VolumeCapability, error)

func (*VolumeCapability) ToCSIRepresentation

func (c *VolumeCapability) ToCSIRepresentation() *csipbv1.VolumeCapability

Directories

Path Synopsis
fake is a package that includes fake implementations of public interfaces from the CSI package for testing.
fake is a package that includes fake implementations of public interfaces from the CSI package for testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL