github.com/Heebron/moby@v0.0.0-20221111184709-6eab4f55faf7/api/types/volume/cluster_volume.go (about) 1 package volume 2 3 import ( 4 "github.com/docker/docker/api/types/swarm" 5 ) 6 7 // ClusterVolume contains options and information specific to, and only present 8 // on, Swarm CSI cluster volumes. 9 type ClusterVolume struct { 10 // ID is the Swarm ID of the volume. Because cluster volumes are Swarm 11 // objects, they have an ID, unlike non-cluster volumes, which only have a 12 // Name. This ID can be used to refer to the cluster volume. 13 ID string 14 15 // Meta is the swarm metadata about this volume. 16 swarm.Meta 17 18 // Spec is the cluster-specific options from which this volume is derived. 19 Spec ClusterVolumeSpec 20 21 // PublishStatus contains the status of the volume as it pertains to its 22 // publishing on Nodes. 23 PublishStatus []*PublishStatus `json:",omitempty"` 24 25 // Info is information about the global status of the volume. 26 Info *Info `json:",omitempty"` 27 } 28 29 // ClusterVolumeSpec contains the spec used to create this volume. 30 type ClusterVolumeSpec struct { 31 // Group defines the volume group of this volume. Volumes belonging to the 32 // same group can be referred to by group name when creating Services. 33 // Referring to a volume by group instructs swarm to treat volumes in that 34 // group interchangeably for the purpose of scheduling. Volumes with an 35 // empty string for a group technically all belong to the same, emptystring 36 // group. 37 Group string `json:",omitempty"` 38 39 // AccessMode defines how the volume is used by tasks. 40 AccessMode *AccessMode `json:",omitempty"` 41 42 // AccessibilityRequirements specifies where in the cluster a volume must 43 // be accessible from. 44 // 45 // This field must be empty if the plugin does not support 46 // VOLUME_ACCESSIBILITY_CONSTRAINTS capabilities. If it is present but the 47 // plugin does not support it, volume will not be created. 48 // 49 // If AccessibilityRequirements is empty, but the plugin does support 50 // VOLUME_ACCESSIBILITY_CONSTRAINTS, then Swarmkit will assume the entire 51 // cluster is a valid target for the volume. 52 AccessibilityRequirements *TopologyRequirement `json:",omitempty"` 53 54 // CapacityRange defines the desired capacity that the volume should be 55 // created with. If nil, the plugin will decide the capacity. 56 CapacityRange *CapacityRange `json:",omitempty"` 57 58 // Secrets defines Swarm Secrets that are passed to the CSI storage plugin 59 // when operating on this volume. 60 Secrets []Secret `json:",omitempty"` 61 62 // Availability is the Volume's desired availability. Analogous to Node 63 // Availability, this allows the user to take volumes offline in order to 64 // update or delete them. 65 Availability Availability `json:",omitempty"` 66 } 67 68 // Availability specifies the availability of the volume. 69 type Availability string 70 71 const ( 72 // AvailabilityActive indicates that the volume is active and fully 73 // schedulable on the cluster. 74 AvailabilityActive Availability = "active" 75 76 // AvailabilityPause indicates that no new workloads should use the 77 // volume, but existing workloads can continue to use it. 78 AvailabilityPause Availability = "pause" 79 80 // AvailabilityDrain indicates that all workloads using this volume 81 // should be rescheduled, and the volume unpublished from all nodes. 82 AvailabilityDrain Availability = "drain" 83 ) 84 85 // AccessMode defines the access mode of a volume. 86 type AccessMode struct { 87 // Scope defines the set of nodes this volume can be used on at one time. 88 Scope Scope `json:",omitempty"` 89 90 // Sharing defines the number and way that different tasks can use this 91 // volume at one time. 92 Sharing SharingMode `json:",omitempty"` 93 94 // MountVolume defines options for using this volume as a Mount-type 95 // volume. 96 // 97 // Either BlockVolume or MountVolume, but not both, must be present. 98 MountVolume *TypeMount `json:",omitempty"` 99 100 // BlockVolume defines options for using this volume as a Block-type 101 // volume. 102 // 103 // Either BlockVolume or MountVolume, but not both, must be present. 104 BlockVolume *TypeBlock `json:",omitempty"` 105 } 106 107 // Scope defines the Scope of a Cluster Volume. This is how many nodes a 108 // Volume can be accessed simultaneously on. 109 type Scope string 110 111 const ( 112 // ScopeSingleNode indicates the volume can be used on one node at a 113 // time. 114 ScopeSingleNode Scope = "single" 115 116 // ScopeMultiNode indicates the volume can be used on many nodes at 117 // the same time. 118 ScopeMultiNode Scope = "multi" 119 ) 120 121 // SharingMode defines the Sharing of a Cluster Volume. This is how Tasks using a 122 // Volume at the same time can use it. 123 type SharingMode string 124 125 const ( 126 // SharingNone indicates that only one Task may use the Volume at a 127 // time. 128 SharingNone SharingMode = "none" 129 130 // SharingReadOnly indicates that the Volume may be shared by any 131 // number of Tasks, but they must be read-only. 132 SharingReadOnly SharingMode = "readonly" 133 134 // SharingOneWriter indicates that the Volume may be shared by any 135 // number of Tasks, but all after the first must be read-only. 136 SharingOneWriter SharingMode = "onewriter" 137 138 // SharingAll means that the Volume may be shared by any number of 139 // Tasks, as readers or writers. 140 SharingAll SharingMode = "all" 141 ) 142 143 // TypeBlock defines options for using a volume as a block-type volume. 144 // 145 // Intentionally empty. 146 type TypeBlock struct{} 147 148 // TypeMount contains options for using a volume as a Mount-type 149 // volume. 150 type TypeMount struct { 151 // FsType specifies the filesystem type for the mount volume. Optional. 152 FsType string `json:",omitempty"` 153 154 // MountFlags defines flags to pass when mounting the volume. Optional. 155 MountFlags []string `json:",omitempty"` 156 } 157 158 // TopologyRequirement expresses the user's requirements for a volume's 159 // accessible topology. 160 type TopologyRequirement struct { 161 // Requisite specifies a list of Topologies, at least one of which the 162 // volume must be accessible from. 163 // 164 // Taken verbatim from the CSI Spec: 165 // 166 // Specifies the list of topologies the provisioned volume MUST be 167 // accessible from. 168 // This field is OPTIONAL. If TopologyRequirement is specified either 169 // requisite or preferred or both MUST be specified. 170 // 171 // If requisite is specified, the provisioned volume MUST be 172 // accessible from at least one of the requisite topologies. 173 // 174 // Given 175 // x = number of topologies provisioned volume is accessible from 176 // n = number of requisite topologies 177 // The CO MUST ensure n >= 1. The SP MUST ensure x >= 1 178 // If x==n, then the SP MUST make the provisioned volume available to 179 // all topologies from the list of requisite topologies. If it is 180 // unable to do so, the SP MUST fail the CreateVolume call. 181 // For example, if a volume should be accessible from a single zone, 182 // and requisite = 183 // {"region": "R1", "zone": "Z2"} 184 // then the provisioned volume MUST be accessible from the "region" 185 // "R1" and the "zone" "Z2". 186 // Similarly, if a volume should be accessible from two zones, and 187 // requisite = 188 // {"region": "R1", "zone": "Z2"}, 189 // {"region": "R1", "zone": "Z3"} 190 // then the provisioned volume MUST be accessible from the "region" 191 // "R1" and both "zone" "Z2" and "zone" "Z3". 192 // 193 // If x<n, then the SP SHALL choose x unique topologies from the list 194 // of requisite topologies. If it is unable to do so, the SP MUST fail 195 // the CreateVolume call. 196 // For example, if a volume should be accessible from a single zone, 197 // and requisite = 198 // {"region": "R1", "zone": "Z2"}, 199 // {"region": "R1", "zone": "Z3"} 200 // then the SP may choose to make the provisioned volume available in 201 // either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1". 202 // Similarly, if a volume should be accessible from two zones, and 203 // requisite = 204 // {"region": "R1", "zone": "Z2"}, 205 // {"region": "R1", "zone": "Z3"}, 206 // {"region": "R1", "zone": "Z4"} 207 // then the provisioned volume MUST be accessible from any combination 208 // of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and 209 // "R1/Z4", or "R1/Z3" and "R1/Z4". 210 // 211 // If x>n, then the SP MUST make the provisioned volume available from 212 // all topologies from the list of requisite topologies and MAY choose 213 // the remaining x-n unique topologies from the list of all possible 214 // topologies. If it is unable to do so, the SP MUST fail the 215 // CreateVolume call. 216 // For example, if a volume should be accessible from two zones, and 217 // requisite = 218 // {"region": "R1", "zone": "Z2"} 219 // then the provisioned volume MUST be accessible from the "region" 220 // "R1" and the "zone" "Z2" and the SP may select the second zone 221 // independently, e.g. "R1/Z4". 222 Requisite []Topology `json:",omitempty"` 223 224 // Preferred is a list of Topologies that the volume should attempt to be 225 // provisioned in. 226 // 227 // Taken from the CSI spec: 228 // 229 // Specifies the list of topologies the CO would prefer the volume to 230 // be provisioned in. 231 // 232 // This field is OPTIONAL. If TopologyRequirement is specified either 233 // requisite or preferred or both MUST be specified. 234 // 235 // An SP MUST attempt to make the provisioned volume available using 236 // the preferred topologies in order from first to last. 237 // 238 // If requisite is specified, all topologies in preferred list MUST 239 // also be present in the list of requisite topologies. 240 // 241 // If the SP is unable to to make the provisioned volume available 242 // from any of the preferred topologies, the SP MAY choose a topology 243 // from the list of requisite topologies. 244 // If the list of requisite topologies is not specified, then the SP 245 // MAY choose from the list of all possible topologies. 246 // If the list of requisite topologies is specified and the SP is 247 // unable to to make the provisioned volume available from any of the 248 // requisite topologies it MUST fail the CreateVolume call. 249 // 250 // Example 1: 251 // Given a volume should be accessible from a single zone, and 252 // requisite = 253 // {"region": "R1", "zone": "Z2"}, 254 // {"region": "R1", "zone": "Z3"} 255 // preferred = 256 // {"region": "R1", "zone": "Z3"} 257 // then the the SP SHOULD first attempt to make the provisioned volume 258 // available from "zone" "Z3" in the "region" "R1" and fall back to 259 // "zone" "Z2" in the "region" "R1" if that is not possible. 260 // 261 // Example 2: 262 // Given a volume should be accessible from a single zone, and 263 // requisite = 264 // {"region": "R1", "zone": "Z2"}, 265 // {"region": "R1", "zone": "Z3"}, 266 // {"region": "R1", "zone": "Z4"}, 267 // {"region": "R1", "zone": "Z5"} 268 // preferred = 269 // {"region": "R1", "zone": "Z4"}, 270 // {"region": "R1", "zone": "Z2"} 271 // then the the SP SHOULD first attempt to make the provisioned volume 272 // accessible from "zone" "Z4" in the "region" "R1" and fall back to 273 // "zone" "Z2" in the "region" "R1" if that is not possible. If that 274 // is not possible, the SP may choose between either the "zone" 275 // "Z3" or "Z5" in the "region" "R1". 276 // 277 // Example 3: 278 // Given a volume should be accessible from TWO zones (because an 279 // opaque parameter in CreateVolumeRequest, for example, specifies 280 // the volume is accessible from two zones, aka synchronously 281 // replicated), and 282 // requisite = 283 // {"region": "R1", "zone": "Z2"}, 284 // {"region": "R1", "zone": "Z3"}, 285 // {"region": "R1", "zone": "Z4"}, 286 // {"region": "R1", "zone": "Z5"} 287 // preferred = 288 // {"region": "R1", "zone": "Z5"}, 289 // {"region": "R1", "zone": "Z3"} 290 // then the the SP SHOULD first attempt to make the provisioned volume 291 // accessible from the combination of the two "zones" "Z5" and "Z3" in 292 // the "region" "R1". If that's not possible, it should fall back to 293 // a combination of "Z5" and other possibilities from the list of 294 // requisite. If that's not possible, it should fall back to a 295 // combination of "Z3" and other possibilities from the list of 296 // requisite. If that's not possible, it should fall back to a 297 // combination of other possibilities from the list of requisite. 298 Preferred []Topology `json:",omitempty"` 299 } 300 301 // Topology is a map of topological domains to topological segments. 302 // 303 // This description is taken verbatim from the CSI Spec: 304 // 305 // A topological domain is a sub-division of a cluster, like "region", 306 // "zone", "rack", etc. 307 // A topological segment is a specific instance of a topological domain, 308 // like "zone3", "rack3", etc. 309 // For example {"com.company/zone": "Z1", "com.company/rack": "R3"} 310 // Valid keys have two segments: an OPTIONAL prefix and name, separated 311 // by a slash (/), for example: "com.company.example/zone". 312 // The key name segment is REQUIRED. The prefix is OPTIONAL. 313 // The key name MUST be 63 characters or less, begin and end with an 314 // alphanumeric character ([a-z0-9A-Z]), and contain only dashes (-), 315 // underscores (_), dots (.), or alphanumerics in between, for example 316 // "zone". 317 // The key prefix MUST be 63 characters or less, begin and end with a 318 // lower-case alphanumeric character ([a-z0-9]), contain only 319 // dashes (-), dots (.), or lower-case alphanumerics in between, and 320 // follow domain name notation format 321 // (https://tools.ietf.org/html/rfc1035#section-2.3.1). 322 // The key prefix SHOULD include the plugin's host company name and/or 323 // the plugin name, to minimize the possibility of collisions with keys 324 // from other plugins. 325 // If a key prefix is specified, it MUST be identical across all 326 // topology keys returned by the SP (across all RPCs). 327 // Keys MUST be case-insensitive. Meaning the keys "Zone" and "zone" 328 // MUST not both exist. 329 // Each value (topological segment) MUST contain 1 or more strings. 330 // Each string MUST be 63 characters or less and begin and end with an 331 // alphanumeric character with '-', '_', '.', or alphanumerics in 332 // between. 333 type Topology struct { 334 Segments map[string]string `json:",omitempty"` 335 } 336 337 // CapacityRange describes the minimum and maximum capacity a volume should be 338 // created with 339 type CapacityRange struct { 340 // RequiredBytes specifies that a volume must be at least this big. The 341 // value of 0 indicates an unspecified minimum. 342 RequiredBytes int64 343 344 // LimitBytes specifies that a volume must not be bigger than this. The 345 // value of 0 indicates an unspecified maximum 346 LimitBytes int64 347 } 348 349 // Secret represents a Swarm Secret value that must be passed to the CSI 350 // storage plugin when operating on this Volume. It represents one key-value 351 // pair of possibly many. 352 type Secret struct { 353 // Key is the name of the key of the key-value pair passed to the plugin. 354 Key string 355 356 // Secret is the swarm Secret object from which to read data. This can be a 357 // Secret name or ID. The Secret data is retrieved by Swarm and used as the 358 // value of the key-value pair passed to the plugin. 359 Secret string 360 } 361 362 // PublishState represents the state of a Volume as it pertains to its 363 // use on a particular Node. 364 type PublishState string 365 366 const ( 367 // StatePending indicates that the volume should be published on 368 // this node, but the call to ControllerPublishVolume has not been 369 // successfully completed yet and the result recorded by swarmkit. 370 StatePending PublishState = "pending-publish" 371 372 // StatePublished means the volume is published successfully to the node. 373 StatePublished PublishState = "published" 374 375 // StatePendingNodeUnpublish indicates that the Volume should be 376 // unpublished on the Node, and we're waiting for confirmation that it has 377 // done so. After the Node has confirmed that the Volume has been 378 // unpublished, the state will move to StatePendingUnpublish. 379 StatePendingNodeUnpublish PublishState = "pending-node-unpublish" 380 381 // StatePendingUnpublish means the volume is still published to the node 382 // by the controller, awaiting the operation to unpublish it. 383 StatePendingUnpublish PublishState = "pending-controller-unpublish" 384 ) 385 386 // PublishStatus represents the status of the volume as published to an 387 // individual node 388 type PublishStatus struct { 389 // NodeID is the ID of the swarm node this Volume is published to. 390 NodeID string `json:",omitempty"` 391 392 // State is the publish state of the volume. 393 State PublishState `json:",omitempty"` 394 395 // PublishContext is the PublishContext returned by the CSI plugin when 396 // a volume is published. 397 PublishContext map[string]string `json:",omitempty"` 398 } 399 400 // Info contains information about the Volume as a whole as provided by 401 // the CSI storage plugin. 402 type Info struct { 403 // CapacityBytes is the capacity of the volume in bytes. A value of 0 404 // indicates that the capacity is unknown. 405 CapacityBytes int64 `json:",omitempty"` 406 407 // VolumeContext is the context originating from the CSI storage plugin 408 // when the Volume is created. 409 VolumeContext map[string]string `json:",omitempty"` 410 411 // VolumeID is the ID of the Volume as seen by the CSI storage plugin. This 412 // is distinct from the Volume's Swarm ID, which is the ID used by all of 413 // the Docker Engine to refer to the Volume. If this field is blank, then 414 // the Volume has not been successfully created yet. 415 VolumeID string `json:",omitempty"` 416 417 // AccessibleTopolgoy is the topology this volume is actually accessible 418 // from. 419 AccessibleTopology []Topology `json:",omitempty"` 420 }