Documentation ¶
Index ¶
- type AccessMode
- type Availability
- type CapacityRange
- type ClusterVolume
- type ClusterVolumeSpec
- type CreateOptions
- type Info
- type ListOptions
- type ListResponse
- type PublishState
- type PublishStatus
- type Scope
- type Secret
- type SharingMode
- type Topology
- type TopologyRequirement
- type TypeBlock
- type TypeMount
- type UpdateOptions
- type UsageData
- type Volume
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AccessMode ¶
type AccessMode struct { // Scope defines the set of nodes this volume can be used on at one time. Scope Scope `json:",omitempty"` // Sharing defines the number and way that different tasks can use this // volume at one time. Sharing SharingMode `json:",omitempty"` // MountVolume defines options for using this volume as a Mount-type // volume. // // Either BlockVolume or MountVolume, but not both, must be present. MountVolume *TypeMount `json:",omitempty"` // BlockVolume defines options for using this volume as a Block-type // volume. // // Either BlockVolume or MountVolume, but not both, must be present. BlockVolume *TypeBlock `json:",omitempty"` }
AccessMode defines the access mode of a volume.
type Availability ¶
type Availability string
Availability specifies the availability of the volume.
const ( // AvailabilityActive indicates that the volume is active and fully // schedulable on the cluster. AvailabilityActive Availability = "active" // AvailabilityPause indicates that no new workloads should use the // volume, but existing workloads can continue to use it. AvailabilityPause Availability = "pause" // AvailabilityDrain indicates that all workloads using this volume // should be rescheduled, and the volume unpublished from all nodes. AvailabilityDrain Availability = "drain" )
type CapacityRange ¶
type CapacityRange struct { // RequiredBytes specifies that a volume must be at least this big. The // value of 0 indicates an unspecified minimum. RequiredBytes int64 // LimitBytes specifies that a volume must not be bigger than this. The // value of 0 indicates an unspecified maximum LimitBytes int64 }
CapacityRange describes the minimum and maximum capacity a volume should be created with
type ClusterVolume ¶
type ClusterVolume struct { // ID is the Swarm ID of the volume. Because cluster volumes are Swarm // objects, they have an ID, unlike non-cluster volumes, which only have a // Name. This ID can be used to refer to the cluster volume. ID string // Meta is the swarm metadata about this volume. swarm.Meta // Spec is the cluster-specific options from which this volume is derived. Spec ClusterVolumeSpec // PublishStatus contains the status of the volume as it pertains to its // publishing on Nodes. PublishStatus []*PublishStatus `json:",omitempty"` // Info is information about the global status of the volume. Info *Info `json:",omitempty"` }
ClusterVolume contains options and information specific to, and only present on, Swarm CSI cluster volumes.
type ClusterVolumeSpec ¶
type ClusterVolumeSpec struct { // Group defines the volume group of this volume. Volumes belonging to the // same group can be referred to by group name when creating Services. // Referring to a volume by group instructs swarm to treat volumes in that // group interchangeably for the purpose of scheduling. Volumes with an // empty string for a group technically all belong to the same, emptystring // group. Group string `json:",omitempty"` // AccessMode defines how the volume is used by tasks. AccessMode *AccessMode `json:",omitempty"` // AccessibilityRequirements specifies where in the cluster a volume must // be accessible from. // // This field must be empty if the plugin does not support // VOLUME_ACCESSIBILITY_CONSTRAINTS capabilities. If it is present but the // plugin does not support it, volume will not be created. // // If AccessibilityRequirements is empty, but the plugin does support // VOLUME_ACCESSIBILITY_CONSTRAINTS, then Swarmkit will assume the entire // cluster is a valid target for the volume. AccessibilityRequirements *TopologyRequirement `json:",omitempty"` // CapacityRange defines the desired capacity that the volume should be // created with. If nil, the plugin will decide the capacity. CapacityRange *CapacityRange `json:",omitempty"` // Secrets defines Swarm Secrets that are passed to the CSI storage plugin // when operating on this volume. Secrets []Secret `json:",omitempty"` // Availability is the Volume's desired availability. Analogous to Node // Availability, this allows the user to take volumes offline in order to // update or delete them. Availability Availability `json:",omitempty"` }
ClusterVolumeSpec contains the spec used to create this volume.
type CreateOptions ¶
type CreateOptions struct { // cluster volume spec ClusterVolumeSpec *ClusterVolumeSpec `json:"ClusterVolumeSpec,omitempty"` // Name of the volume driver to use. Driver string `json:"Driver,omitempty"` // A mapping of driver options and values. These options are // passed directly to the driver and are driver specific. // DriverOpts map[string]string `json:"DriverOpts,omitempty"` // User-defined key/value metadata. Labels map[string]string `json:"Labels,omitempty"` // The new volume's name. If not specified, Docker generates a name. // Name string `json:"Name,omitempty"` }
CreateOptions VolumeConfig
Volume configuration swagger:model CreateOptions
type Info ¶
type Info struct { // CapacityBytes is the capacity of the volume in bytes. A value of 0 // indicates that the capacity is unknown. CapacityBytes int64 `json:",omitempty"` // VolumeContext is the context originating from the CSI storage plugin // when the Volume is created. VolumeContext map[string]string `json:",omitempty"` // VolumeID is the ID of the Volume as seen by the CSI storage plugin. This // is distinct from the Volume's Swarm ID, which is the ID used by all of // the Docker Engine to refer to the Volume. If this field is blank, then // the Volume has not been successfully created yet. VolumeID string `json:",omitempty"` // AccessibleTopolgoy is the topology this volume is actually accessible // from. AccessibleTopology []Topology `json:",omitempty"` }
Info contains information about the Volume as a whole as provided by the CSI storage plugin.
type ListOptions ¶
ListOptions holds parameters to list volumes.
type ListResponse ¶
type ListResponse struct { // List of volumes Volumes []*Volume `json:"Volumes"` // Warnings that occurred when fetching the list of volumes. // Warnings []string `json:"Warnings"` }
ListResponse VolumeListResponse
Volume list response swagger:model ListResponse
type PublishState ¶
type PublishState string
PublishState represents the state of a Volume as it pertains to its use on a particular Node.
const ( // StatePending indicates that the volume should be published on // this node, but the call to ControllerPublishVolume has not been // successfully completed yet and the result recorded by swarmkit. StatePending PublishState = "pending-publish" // StatePublished means the volume is published successfully to the node. StatePublished PublishState = "published" // StatePendingNodeUnpublish indicates that the Volume should be // unpublished on the Node, and we're waiting for confirmation that it has // done so. After the Node has confirmed that the Volume has been // unpublished, the state will move to StatePendingUnpublish. StatePendingNodeUnpublish PublishState = "pending-node-unpublish" // StatePendingUnpublish means the volume is still published to the node // by the controller, awaiting the operation to unpublish it. StatePendingUnpublish PublishState = "pending-controller-unpublish" )
type PublishStatus ¶
type PublishStatus struct { // NodeID is the ID of the swarm node this Volume is published to. NodeID string `json:",omitempty"` // State is the publish state of the volume. State PublishState `json:",omitempty"` // PublishContext is the PublishContext returned by the CSI plugin when // a volume is published. PublishContext map[string]string `json:",omitempty"` }
PublishStatus represents the status of the volume as published to an individual node
type Scope ¶
type Scope string
Scope defines the Scope of a Cluster Volume. This is how many nodes a Volume can be accessed simultaneously on.
type Secret ¶
type Secret struct { // Key is the name of the key of the key-value pair passed to the plugin. Key string // Secret is the swarm Secret object from which to read data. This can be a // Secret name or ID. The Secret data is retrieved by Swarm and used as the // value of the key-value pair passed to the plugin. Secret string }
Secret represents a Swarm Secret value that must be passed to the CSI storage plugin when operating on this Volume. It represents one key-value pair of possibly many.
type SharingMode ¶
type SharingMode string
SharingMode defines the Sharing of a Cluster Volume. This is how Tasks using a Volume at the same time can use it.
const ( // SharingNone indicates that only one Task may use the Volume at a // time. SharingNone SharingMode = "none" // SharingReadOnly indicates that the Volume may be shared by any // number of Tasks, but they must be read-only. SharingReadOnly SharingMode = "readonly" // SharingOneWriter indicates that the Volume may be shared by any // number of Tasks, but all after the first must be read-only. SharingOneWriter SharingMode = "onewriter" // SharingAll means that the Volume may be shared by any number of // Tasks, as readers or writers. SharingAll SharingMode = "all" )
type Topology ¶
Topology is a map of topological domains to topological segments.
This description is taken verbatim from the CSI Spec:
A topological domain is a sub-division of a cluster, like "region", "zone", "rack", etc. A topological segment is a specific instance of a topological domain, like "zone3", "rack3", etc. For example {"com.company/zone": "Z1", "com.company/rack": "R3"} 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 ¶
type TopologyRequirement struct { // Requisite specifies a list of Topologies, at least one of which the // volume must be accessible from. // // Taken verbatim from the CSI Spec: // // Specifies the list of topologies the provisioned volume MUST be // accessible from. // This field is OPTIONAL. If TopologyRequirement is specified either // requisite or preferred or both MUST be specified. // // If requisite is specified, the provisioned volume MUST be // accessible from at least one of the requisite topologies. // // Given // x = number of topologies provisioned volume is accessible from // n = number of requisite topologies // The CO MUST ensure n >= 1. The SP MUST ensure x >= 1 // If x==n, then the SP MUST make the provisioned volume available to // all topologies from the list of requisite topologies. If it is // unable to do so, the SP MUST fail the CreateVolume call. // For example, if a volume should be accessible from a single zone, // and requisite = // {"region": "R1", "zone": "Z2"} // then the provisioned volume MUST be accessible from the "region" // "R1" and the "zone" "Z2". // Similarly, if a volume should be accessible from two zones, and // requisite = // {"region": "R1", "zone": "Z2"}, // {"region": "R1", "zone": "Z3"} // then the provisioned volume MUST be accessible from the "region" // "R1" and both "zone" "Z2" and "zone" "Z3". // // If x<n, then the SP SHALL choose x unique topologies from the list // of requisite topologies. If it is unable to do so, the SP MUST fail // the CreateVolume call. // For example, if a volume should be accessible from a single zone, // and requisite = // {"region": "R1", "zone": "Z2"}, // {"region": "R1", "zone": "Z3"} // then the SP may choose to make the provisioned volume available in // either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1". // Similarly, if a volume should be accessible from two zones, and // requisite = // {"region": "R1", "zone": "Z2"}, // {"region": "R1", "zone": "Z3"}, // {"region": "R1", "zone": "Z4"} // then the provisioned volume MUST be accessible from any combination // of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and // "R1/Z4", or "R1/Z3" and "R1/Z4". // // If x>n, then the SP MUST make the provisioned volume available from // all topologies from the list of requisite topologies and MAY choose // the remaining x-n unique topologies from the list of all possible // topologies. If it is unable to do so, the SP MUST fail the // CreateVolume call. // For example, if a volume should be accessible from two zones, and // requisite = // {"region": "R1", "zone": "Z2"} // then the provisioned volume MUST be accessible from the "region" // "R1" and the "zone" "Z2" and the SP may select the second zone // independently, e.g. "R1/Z4". Requisite []Topology `json:",omitempty"` // Preferred is a list of Topologies that the volume should attempt to be // provisioned in. // // Taken from the CSI spec: // // Specifies the list of topologies the CO would prefer the volume to // be provisioned in. // // This field is OPTIONAL. If TopologyRequirement is specified either // requisite or preferred or both MUST be specified. // // An SP MUST attempt to make the provisioned volume available using // the preferred topologies in order from first to last. // // If requisite is specified, all topologies in preferred list MUST // also be present in the list of requisite topologies. // // If the SP is unable to make the provisioned volume available // from any of the preferred topologies, the SP MAY choose a topology // from the list of requisite topologies. // If the list of requisite topologies is not specified, then the SP // MAY choose from the list of all possible topologies. // If the list of requisite topologies is specified and the SP is // unable to make the provisioned volume available from any of the // requisite topologies it MUST fail the CreateVolume call. // // Example 1: // Given a volume should be accessible from a single zone, and // requisite = // {"region": "R1", "zone": "Z2"}, // {"region": "R1", "zone": "Z3"} // preferred = // {"region": "R1", "zone": "Z3"} // then the SP SHOULD first attempt to make the provisioned volume // available from "zone" "Z3" in the "region" "R1" and fall back to // "zone" "Z2" in the "region" "R1" if that is not possible. // // Example 2: // Given a volume should be accessible from a single zone, and // requisite = // {"region": "R1", "zone": "Z2"}, // {"region": "R1", "zone": "Z3"}, // {"region": "R1", "zone": "Z4"}, // {"region": "R1", "zone": "Z5"} // preferred = // {"region": "R1", "zone": "Z4"}, // {"region": "R1", "zone": "Z2"} // then the SP SHOULD first attempt to make the provisioned volume // accessible from "zone" "Z4" in the "region" "R1" and fall back to // "zone" "Z2" in the "region" "R1" if that is not possible. If that // is not possible, the SP may choose between either the "zone" // "Z3" or "Z5" in the "region" "R1". // // Example 3: // Given a volume should be accessible from TWO zones (because an // opaque parameter in CreateVolumeRequest, for example, specifies // the volume is accessible from two zones, aka synchronously // replicated), and // requisite = // {"region": "R1", "zone": "Z2"}, // {"region": "R1", "zone": "Z3"}, // {"region": "R1", "zone": "Z4"}, // {"region": "R1", "zone": "Z5"} // preferred = // {"region": "R1", "zone": "Z5"}, // {"region": "R1", "zone": "Z3"} // then the SP SHOULD first attempt to make the provisioned volume // accessible from the combination of the two "zones" "Z5" and "Z3" in // the "region" "R1". If that's not possible, it should fall back to // a combination of "Z5" and other possibilities from the list of // requisite. If that's not possible, it should fall back to a // combination of "Z3" and other possibilities from the list of // requisite. If that's not possible, it should fall back to a // combination of other possibilities from the list of requisite. Preferred []Topology `json:",omitempty"` }
TopologyRequirement expresses the user's requirements for a volume's accessible topology.
type TypeBlock ¶
type TypeBlock struct{}
TypeBlock defines options for using a volume as a block-type volume.
Intentionally empty.
type TypeMount ¶
type TypeMount struct { // FsType specifies the filesystem type for the mount volume. Optional. FsType string `json:",omitempty"` // MountFlags defines flags to pass when mounting the volume. Optional. MountFlags []string `json:",omitempty"` }
TypeMount contains options for using a volume as a Mount-type volume.
type UpdateOptions ¶
type UpdateOptions struct { // Spec is the ClusterVolumeSpec to update the volume to. Spec *ClusterVolumeSpec `json:"Spec,omitempty"` }
UpdateOptions is configuration to update a Volume with.
type UsageData ¶
type UsageData struct { // The number of containers referencing this volume. This field // is set to `-1` if the reference-count is not available. // // Required: true RefCount int64 `json:"RefCount"` // Amount of disk space used by the volume (in bytes). This information // is only available for volumes created with the `"local"` volume // driver. For volumes created with other volume drivers, this field // is set to `-1` ("not available") // // Required: true Size int64 `json:"Size"` }
UsageData Usage details about the volume. This information is used by the `GET /system/df` endpoint, and omitted in other endpoints.
swagger:model UsageData
type Volume ¶
type Volume struct { // cluster volume ClusterVolume *ClusterVolume `json:"ClusterVolume,omitempty"` // Date/Time the volume was created. CreatedAt string `json:"CreatedAt,omitempty"` // Name of the volume driver used by the volume. // Required: true Driver string `json:"Driver"` // User-defined key/value metadata. // Required: true Labels map[string]string `json:"Labels"` // Mount path of the volume on the host. // Required: true Mountpoint string `json:"Mountpoint"` // Name of the volume. // Required: true Name string `json:"Name"` // The driver specific options used when creating the volume. // // Required: true Options map[string]string `json:"Options"` // The level at which the volume exists. Either `global` for cluster-wide, // or `local` for machine level. // // Required: true Scope string `json:"Scope"` // Low-level details about the volume, provided by the volume driver. // Details are returned as a map with key/value pairs: // `{"key":"value","key2":"value2"}`. // // The `Status` field is optional, and is omitted if the volume driver // does not support this feature. // Status map[string]interface{} `json:"Status,omitempty"` // usage data UsageData *UsageData `json:"UsageData,omitempty"` }
Volume volume swagger:model Volume