csi

package
v1.5.5 Latest Latest
Warning

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

Go to latest
Published: May 5, 2023 License: MPL-2.0 Imports: 18 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

type CSIControllerClient interface {
	ControllerGetCapabilities(ctx context.Context, in *csipbv1.ControllerGetCapabilitiesRequest, opts ...grpc.CallOption) (*csipbv1.ControllerGetCapabilitiesResponse, error)
	ControllerPublishVolume(ctx context.Context, in *csipbv1.ControllerPublishVolumeRequest, opts ...grpc.CallOption) (*csipbv1.ControllerPublishVolumeResponse, error)
	ControllerUnpublishVolume(ctx context.Context, in *csipbv1.ControllerUnpublishVolumeRequest, opts ...grpc.CallOption) (*csipbv1.ControllerUnpublishVolumeResponse, error)
	ValidateVolumeCapabilities(ctx context.Context, in *csipbv1.ValidateVolumeCapabilitiesRequest, opts ...grpc.CallOption) (*csipbv1.ValidateVolumeCapabilitiesResponse, error)
	CreateVolume(ctx context.Context, in *csipbv1.CreateVolumeRequest, opts ...grpc.CallOption) (*csipbv1.CreateVolumeResponse, error)
	ListVolumes(ctx context.Context, in *csipbv1.ListVolumesRequest, opts ...grpc.CallOption) (*csipbv1.ListVolumesResponse, error)
	DeleteVolume(ctx context.Context, in *csipbv1.DeleteVolumeRequest, opts ...grpc.CallOption) (*csipbv1.DeleteVolumeResponse, error)
	CreateSnapshot(ctx context.Context, in *csipbv1.CreateSnapshotRequest, opts ...grpc.CallOption) (*csipbv1.CreateSnapshotResponse, error)
	DeleteSnapshot(ctx context.Context, in *csipbv1.DeleteSnapshotRequest, opts ...grpc.CallOption) (*csipbv1.DeleteSnapshotResponse, error)
	ListSnapshots(ctx context.Context, in *csipbv1.ListSnapshotsRequest, opts ...grpc.CallOption) (*csipbv1.ListSnapshotsResponse, error)
}

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

	// ControllerCreateVolume is used to create a remote volume in the
	// external storage provider
	ControllerCreateVolume(ctx context.Context, req *ControllerCreateVolumeRequest, opts ...grpc.CallOption) (*ControllerCreateVolumeResponse, error)

	// ControllerDeleteVolume is used to delete a remote volume in the
	// external storage provider
	ControllerDeleteVolume(ctx context.Context, req *ControllerDeleteVolumeRequest, opts ...grpc.CallOption) error

	// ControllerListVolumes is used to list all volumes available in the
	// external storage provider
	ControllerListVolumes(ctx context.Context, req *ControllerListVolumesRequest, opts ...grpc.CallOption) (*ControllerListVolumesResponse, error)

	// ControllerCreateSnapshot is used to create a volume snapshot in the
	// external storage provider
	ControllerCreateSnapshot(ctx context.Context, req *ControllerCreateSnapshotRequest, opts ...grpc.CallOption) (*ControllerCreateSnapshotResponse, error)

	// ControllerDeleteSnapshot is used to delete a volume snapshot from the
	// external storage provider
	ControllerDeleteSnapshot(ctx context.Context, req *ControllerDeleteSnapshotRequest, opts ...grpc.CallOption) error

	// ControllerListSnapshots is used to list all volume snapshots available
	// in the external storage provider
	ControllerListSnapshots(ctx context.Context, req *ControllerListSnapshotsRequest, opts ...grpc.CallOption) (*ControllerListSnapshotsResponse, 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

type CapacityRange added in v1.1.0

type CapacityRange struct {
	RequiredBytes int64
	LimitBytes    int64
}

func (*CapacityRange) ToCSIRepresentation added in v1.1.0

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

type ControllerCapabilitySet

type ControllerCapabilitySet struct {
	HasCreateDeleteVolume        bool
	HasPublishUnpublishVolume    bool
	HasListVolumes               bool
	HasGetCapacity               bool
	HasCreateDeleteSnapshot      bool
	HasListSnapshots             bool
	HasCloneVolume               bool
	HasPublishReadonly           bool
	HasExpandVolume              bool
	HasListVolumesPublishedNodes bool
	HasVolumeCondition           bool
	HasGetVolume                 bool
}

type ControllerCreateSnapshotRequest added in v1.1.0

type ControllerCreateSnapshotRequest struct {
	VolumeID   string
	Name       string
	Secrets    structs.CSISecrets
	Parameters map[string]string
}

func (*ControllerCreateSnapshotRequest) ToCSIRepresentation added in v1.1.0

func (*ControllerCreateSnapshotRequest) Validate added in v1.1.0

func (r *ControllerCreateSnapshotRequest) Validate() error

type ControllerCreateSnapshotResponse added in v1.1.0

type ControllerCreateSnapshotResponse struct {
	Snapshot *Snapshot
}

type ControllerCreateVolumeRequest added in v1.1.0

type ControllerCreateVolumeRequest struct {
	// note that Name is intentionally differentiated from both CSIVolume.ID
	// and ExternalVolumeID. This name is only a recommendation for the
	// storage provider, and many will discard this suggestion
	Name                      string
	CapacityRange             *CapacityRange
	VolumeCapabilities        []*VolumeCapability
	Parameters                map[string]string
	Secrets                   structs.CSISecrets
	ContentSource             *VolumeContentSource
	AccessibilityRequirements *TopologyRequirement
}

func (*ControllerCreateVolumeRequest) ToCSIRepresentation added in v1.1.0

func (r *ControllerCreateVolumeRequest) ToCSIRepresentation() *csipbv1.CreateVolumeRequest

func (*ControllerCreateVolumeRequest) Validate added in v1.1.0

func (r *ControllerCreateVolumeRequest) Validate() error

type ControllerCreateVolumeResponse added in v1.1.0

type ControllerCreateVolumeResponse struct {
	Volume *Volume
}

func NewCreateVolumeResponse added in v1.1.0

func NewCreateVolumeResponse(resp *csipbv1.CreateVolumeResponse) *ControllerCreateVolumeResponse

type ControllerDeleteSnapshotRequest added in v1.1.0

type ControllerDeleteSnapshotRequest struct {
	SnapshotID string
	Secrets    structs.CSISecrets
}

func (*ControllerDeleteSnapshotRequest) ToCSIRepresentation added in v1.1.0

func (*ControllerDeleteSnapshotRequest) Validate added in v1.1.0

func (r *ControllerDeleteSnapshotRequest) Validate() error

type ControllerDeleteVolumeRequest added in v1.1.0

type ControllerDeleteVolumeRequest struct {
	ExternalVolumeID string
	Secrets          structs.CSISecrets
}

func (*ControllerDeleteVolumeRequest) ToCSIRepresentation added in v1.1.0

func (r *ControllerDeleteVolumeRequest) ToCSIRepresentation() *csipbv1.DeleteVolumeRequest

func (*ControllerDeleteVolumeRequest) Validate added in v1.1.0

func (r *ControllerDeleteVolumeRequest) Validate() error

type ControllerListSnapshotsRequest added in v1.1.0

type ControllerListSnapshotsRequest struct {
	MaxEntries    int32
	StartingToken string
	Secrets       structs.CSISecrets
}

func (*ControllerListSnapshotsRequest) ToCSIRepresentation added in v1.1.0

func (*ControllerListSnapshotsRequest) Validate added in v1.1.0

func (r *ControllerListSnapshotsRequest) Validate() error

type ControllerListSnapshotsResponse added in v1.1.0

type ControllerListSnapshotsResponse struct {
	Entries   []*ListSnapshotsResponse_Entry
	NextToken string
}

func NewListSnapshotsResponse added in v1.1.0

func NewListSnapshotsResponse(resp *csipbv1.ListSnapshotsResponse) *ControllerListSnapshotsResponse

type ControllerListVolumesRequest added in v1.1.0

type ControllerListVolumesRequest struct {
	MaxEntries    int32
	StartingToken string
}

func (*ControllerListVolumesRequest) ToCSIRepresentation added in v1.1.0

func (r *ControllerListVolumesRequest) ToCSIRepresentation() *csipbv1.ListVolumesRequest

func (*ControllerListVolumesRequest) Validate added in v1.1.0

func (r *ControllerListVolumesRequest) Validate() error

type ControllerListVolumesResponse added in v1.1.0

type ControllerListVolumesResponse struct {
	Entries   []*ListVolumesResponse_Entry
	NextToken string
}

func NewListVolumesResponse added in v1.1.0

func NewListVolumesResponse(resp *csipbv1.ListVolumesResponse) *ControllerListVolumesResponse

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 ListSnapshotsResponse_Entry added in v1.1.0

type ListSnapshotsResponse_Entry struct {
	Snapshot *Snapshot
}

type ListVolumesResponse_Entry added in v1.1.0

type ListVolumesResponse_Entry struct {
	Volume *Volume
	Status *ListVolumesResponse_VolumeStatus
}

type ListVolumesResponse_VolumeStatus added in v1.1.0

type ListVolumesResponse_VolumeStatus struct {
	PublishedNodeIds []string
	VolumeCondition  *VolumeCondition
}

type NodeCapabilitySet

type NodeCapabilitySet struct {
	HasStageUnstageVolume bool
	HasGetVolumeStats     bool
	HasExpandVolume       bool
	HasVolumeCondition    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

HasToplogies 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 Snapshot added in v1.1.0

type Snapshot struct {
	ID             string
	SourceVolumeID string
	SizeBytes      int64
	CreateTime     int64
	IsReady        bool
}

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 TopologyRequirement added in v1.1.0

type TopologyRequirement struct {
	Requisite []*Topology
	Preferred []*Topology
}

func (*TopologyRequirement) ToCSIRepresentation added in v1.1.0

func (tr *TopologyRequirement) ToCSIRepresentation() *csipbv1.TopologyRequirement

type Volume added in v1.1.0

type Volume struct {
	CapacityBytes int64

	// this is differentiated from VolumeID so as not to create confusion
	// between the Nomad CSIVolume.ID and the storage provider's ID.
	ExternalVolumeID   string
	VolumeContext      map[string]string
	ContentSource      *VolumeContentSource
	AccessibleTopology []*Topology
}

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, sMountOptions *structs.CSIMountOptions) (*VolumeCapability, error)

func (*VolumeCapability) ToCSIRepresentation

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

type VolumeCondition added in v1.1.0

type VolumeCondition struct {
	Abnormal bool
	Message  string
}

type VolumeContentSource added in v1.1.0

type VolumeContentSource struct {
	SnapshotID string
	CloneID    string
}

VolumeContentSource is snapshot or volume that the plugin will use to create the new volume. At most one of these fields can be set, but nil (and not an empty struct) is expected by CSI plugins if neither field is set.

func (*VolumeContentSource) ToCSIRepresentation added in v1.1.0

func (vcr *VolumeContentSource) ToCSIRepresentation() *csipbv1.VolumeContentSource

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