1/* 2Copyright 2016 The Kubernetes Authors. 3 4Licensed under the Apache License, Version 2.0 (the "License"); 5you may not use this file except in compliance with the License. 6You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10Unless required by applicable law or agreed to in writing, software 11distributed under the License is distributed on an "AS IS" BASIS, 12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13See the License for the specific language governing permissions and 14limitations under the License. 15*/ 16 17package v1beta1 18 19import ( 20 v1 "k8s.io/api/core/v1" 21 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" 22) 23 24// +genclient 25// +genclient:nonNamespaced 26// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 27 28// StorageClass describes the parameters for a class of storage for 29// which PersistentVolumes can be dynamically provisioned. 30// 31// StorageClasses are non-namespaced; the name of the storage class 32// according to etcd is in ObjectMeta.Name. 33type StorageClass struct { 34 metav1.TypeMeta `json:",inline"` 35 // Standard object's metadata. 36 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 37 // +optional 38 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 39 40 // Provisioner indicates the type of the provisioner. 41 Provisioner string `json:"provisioner" protobuf:"bytes,2,opt,name=provisioner"` 42 43 // Parameters holds the parameters for the provisioner that should 44 // create volumes of this storage class. 45 // +optional 46 Parameters map[string]string `json:"parameters,omitempty" protobuf:"bytes,3,rep,name=parameters"` 47 48 // Dynamically provisioned PersistentVolumes of this storage class are 49 // created with this reclaimPolicy. Defaults to Delete. 50 // +optional 51 ReclaimPolicy *v1.PersistentVolumeReclaimPolicy `json:"reclaimPolicy,omitempty" protobuf:"bytes,4,opt,name=reclaimPolicy,casttype=k8s.io/api/core/v1.PersistentVolumeReclaimPolicy"` 52 53 // Dynamically provisioned PersistentVolumes of this storage class are 54 // created with these mountOptions, e.g. ["ro", "soft"]. Not validated - 55 // mount of the PVs will simply fail if one is invalid. 56 // +optional 57 MountOptions []string `json:"mountOptions,omitempty" protobuf:"bytes,5,opt,name=mountOptions"` 58 59 // AllowVolumeExpansion shows whether the storage class allow volume expand 60 // +optional 61 AllowVolumeExpansion *bool `json:"allowVolumeExpansion,omitempty" protobuf:"varint,6,opt,name=allowVolumeExpansion"` 62 63 // VolumeBindingMode indicates how PersistentVolumeClaims should be 64 // provisioned and bound. When unset, VolumeBindingImmediate is used. 65 // This field is only honored by servers that enable the VolumeScheduling feature. 66 // +optional 67 VolumeBindingMode *VolumeBindingMode `json:"volumeBindingMode,omitempty" protobuf:"bytes,7,opt,name=volumeBindingMode"` 68 69 // Restrict the node topologies where volumes can be dynamically provisioned. 70 // Each volume plugin defines its own supported topology specifications. 71 // An empty TopologySelectorTerm list means there is no topology restriction. 72 // This field is only honored by servers that enable the VolumeScheduling feature. 73 // +optional 74 AllowedTopologies []v1.TopologySelectorTerm `json:"allowedTopologies,omitempty" protobuf:"bytes,8,rep,name=allowedTopologies"` 75} 76 77// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 78 79// StorageClassList is a collection of storage classes. 80type StorageClassList struct { 81 metav1.TypeMeta `json:",inline"` 82 // Standard list metadata 83 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 84 // +optional 85 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 86 87 // Items is the list of StorageClasses 88 Items []StorageClass `json:"items" protobuf:"bytes,2,rep,name=items"` 89} 90 91// VolumeBindingMode indicates how PersistentVolumeClaims should be bound. 92type VolumeBindingMode string 93 94const ( 95 // VolumeBindingImmediate indicates that PersistentVolumeClaims should be 96 // immediately provisioned and bound. This is the default mode. 97 VolumeBindingImmediate VolumeBindingMode = "Immediate" 98 99 // VolumeBindingWaitForFirstConsumer indicates that PersistentVolumeClaims 100 // should not be provisioned and bound until the first Pod is created that 101 // references the PeristentVolumeClaim. The volume provisioning and 102 // binding will occur during Pod scheduing. 103 VolumeBindingWaitForFirstConsumer VolumeBindingMode = "WaitForFirstConsumer" 104) 105 106// +genclient 107// +genclient:nonNamespaced 108// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 109 110// VolumeAttachment captures the intent to attach or detach the specified volume 111// to/from the specified node. 112// 113// VolumeAttachment objects are non-namespaced. 114type VolumeAttachment struct { 115 metav1.TypeMeta `json:",inline"` 116 117 // Standard object metadata. 118 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 119 // +optional 120 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 121 122 // Specification of the desired attach/detach volume behavior. 123 // Populated by the Kubernetes system. 124 Spec VolumeAttachmentSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"` 125 126 // Status of the VolumeAttachment request. 127 // Populated by the entity completing the attach or detach 128 // operation, i.e. the external-attacher. 129 // +optional 130 Status VolumeAttachmentStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"` 131} 132 133// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 134 135// VolumeAttachmentList is a collection of VolumeAttachment objects. 136type VolumeAttachmentList struct { 137 metav1.TypeMeta `json:",inline"` 138 // Standard list metadata 139 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 140 // +optional 141 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 142 143 // Items is the list of VolumeAttachments 144 Items []VolumeAttachment `json:"items" protobuf:"bytes,2,rep,name=items"` 145} 146 147// VolumeAttachmentSpec is the specification of a VolumeAttachment request. 148type VolumeAttachmentSpec struct { 149 // Attacher indicates the name of the volume driver that MUST handle this 150 // request. This is the name returned by GetPluginName(). 151 Attacher string `json:"attacher" protobuf:"bytes,1,opt,name=attacher"` 152 153 // Source represents the volume that should be attached. 154 Source VolumeAttachmentSource `json:"source" protobuf:"bytes,2,opt,name=source"` 155 156 // The node that the volume should be attached to. 157 NodeName string `json:"nodeName" protobuf:"bytes,3,opt,name=nodeName"` 158} 159 160// VolumeAttachmentSource represents a volume that should be attached. 161// Right now only PersistenVolumes can be attached via external attacher, 162// in future we may allow also inline volumes in pods. 163// Exactly one member can be set. 164type VolumeAttachmentSource struct { 165 // Name of the persistent volume to attach. 166 // +optional 167 PersistentVolumeName *string `json:"persistentVolumeName,omitempty" protobuf:"bytes,1,opt,name=persistentVolumeName"` 168 169 // inlineVolumeSpec contains all the information necessary to attach 170 // a persistent volume defined by a pod's inline VolumeSource. This field 171 // is populated only for the CSIMigration feature. It contains 172 // translated fields from a pod's inline VolumeSource to a 173 // PersistentVolumeSpec. This field is alpha-level and is only 174 // honored by servers that enabled the CSIMigration feature. 175 // +optional 176 InlineVolumeSpec *v1.PersistentVolumeSpec `json:"inlineVolumeSpec,omitempty" protobuf:"bytes,2,opt,name=inlineVolumeSpec"` 177} 178 179// VolumeAttachmentStatus is the status of a VolumeAttachment request. 180type VolumeAttachmentStatus struct { 181 // Indicates the volume is successfully attached. 182 // This field must only be set by the entity completing the attach 183 // operation, i.e. the external-attacher. 184 Attached bool `json:"attached" protobuf:"varint,1,opt,name=attached"` 185 186 // Upon successful attach, this field is populated with any 187 // information returned by the attach operation that must be passed 188 // into subsequent WaitForAttach or Mount calls. 189 // This field must only be set by the entity completing the attach 190 // operation, i.e. the external-attacher. 191 // +optional 192 AttachmentMetadata map[string]string `json:"attachmentMetadata,omitempty" protobuf:"bytes,2,rep,name=attachmentMetadata"` 193 194 // The last error encountered during attach operation, if any. 195 // This field must only be set by the entity completing the attach 196 // operation, i.e. the external-attacher. 197 // +optional 198 AttachError *VolumeError `json:"attachError,omitempty" protobuf:"bytes,3,opt,name=attachError,casttype=VolumeError"` 199 200 // The last error encountered during detach operation, if any. 201 // This field must only be set by the entity completing the detach 202 // operation, i.e. the external-attacher. 203 // +optional 204 DetachError *VolumeError `json:"detachError,omitempty" protobuf:"bytes,4,opt,name=detachError,casttype=VolumeError"` 205} 206 207// VolumeError captures an error encountered during a volume operation. 208type VolumeError struct { 209 // Time the error was encountered. 210 // +optional 211 Time metav1.Time `json:"time,omitempty" protobuf:"bytes,1,opt,name=time"` 212 213 // String detailing the error encountered during Attach or Detach operation. 214 // This string may be logged, so it should not contain sensitive 215 // information. 216 // +optional 217 Message string `json:"message,omitempty" protobuf:"bytes,2,opt,name=message"` 218} 219 220// +genclient 221// +genclient:nonNamespaced 222// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 223 224// CSIDriver captures information about a Container Storage Interface (CSI) 225// volume driver deployed on the cluster. 226// CSI drivers do not need to create the CSIDriver object directly. Instead they may use the 227// cluster-driver-registrar sidecar container. When deployed with a CSI driver it automatically 228// creates a CSIDriver object representing the driver. 229// Kubernetes attach detach controller uses this object to determine whether attach is required. 230// Kubelet uses this object to determine whether pod information needs to be passed on mount. 231// CSIDriver objects are non-namespaced. 232type CSIDriver struct { 233 metav1.TypeMeta `json:",inline"` 234 235 // Standard object metadata. 236 // metadata.Name indicates the name of the CSI driver that this object 237 // refers to; it MUST be the same name returned by the CSI GetPluginName() 238 // call for that driver. 239 // The driver name must be 63 characters or less, beginning and ending with 240 // an alphanumeric character ([a-z0-9A-Z]) with dashes (-), dots (.), and 241 // alphanumerics between. 242 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 243 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 244 245 // Specification of the CSI Driver. 246 Spec CSIDriverSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"` 247} 248 249// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 250 251// CSIDriverList is a collection of CSIDriver objects. 252type CSIDriverList struct { 253 metav1.TypeMeta `json:",inline"` 254 255 // Standard list metadata 256 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 257 // +optional 258 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 259 260 // items is the list of CSIDriver 261 Items []CSIDriver `json:"items" protobuf:"bytes,2,rep,name=items"` 262} 263 264// CSIDriverSpec is the specification of a CSIDriver. 265type CSIDriverSpec struct { 266 // attachRequired indicates this CSI volume driver requires an attach 267 // operation (because it implements the CSI ControllerPublishVolume() 268 // method), and that the Kubernetes attach detach controller should call 269 // the attach volume interface which checks the volumeattachment status 270 // and waits until the volume is attached before proceeding to mounting. 271 // The CSI external-attacher coordinates with CSI volume driver and updates 272 // the volumeattachment status when the attach operation is complete. 273 // If the CSIDriverRegistry feature gate is enabled and the value is 274 // specified to false, the attach operation will be skipped. 275 // Otherwise the attach operation will be called. 276 // +optional 277 AttachRequired *bool `json:"attachRequired,omitempty" protobuf:"varint,1,opt,name=attachRequired"` 278 279 // If set to true, podInfoOnMount indicates this CSI volume driver 280 // requires additional pod information (like podName, podUID, etc.) during 281 // mount operations. 282 // If set to false, pod information will not be passed on mount. 283 // Default is false. 284 // The CSI driver specifies podInfoOnMount as part of driver deployment. 285 // If true, Kubelet will pass pod information as VolumeContext in the CSI 286 // NodePublishVolume() calls. 287 // The CSI driver is responsible for parsing and validating the information 288 // passed in as VolumeContext. 289 // The following VolumeConext will be passed if podInfoOnMount is set to true. 290 // This list might grow, but the prefix will be used. 291 // "csi.storage.k8s.io/pod.name": pod.Name 292 // "csi.storage.k8s.io/pod.namespace": pod.Namespace 293 // "csi.storage.k8s.io/pod.uid": string(pod.UID) 294 // "csi.storage.k8s.io/ephemeral": "true" iff the volume is an ephemeral inline volume 295 // defined by a CSIVolumeSource, otherwise "false" 296 // 297 // "csi.storage.k8s.io/ephemeral" is a new feature in Kubernetes 1.16. It is only 298 // required for drivers which support both the "Persistent" and "Ephemeral" VolumeLifecycleMode. 299 // Other drivers can leave pod info disabled and/or ignore this field. 300 // As Kubernetes 1.15 doesn't support this field, drivers can only support one mode when 301 // deployed on such a cluster and the deployment determines which mode that is, for example 302 // via a command line parameter of the driver. 303 // +optional 304 PodInfoOnMount *bool `json:"podInfoOnMount,omitempty" protobuf:"bytes,2,opt,name=podInfoOnMount"` 305 306 // VolumeLifecycleModes defines what kind of volumes this CSI volume driver supports. 307 // The default if the list is empty is "Persistent", which is the usage 308 // defined by the CSI specification and implemented in Kubernetes via the usual 309 // PV/PVC mechanism. 310 // The other mode is "Ephemeral". In this mode, volumes are defined inline 311 // inside the pod spec with CSIVolumeSource and their lifecycle is tied to 312 // the lifecycle of that pod. A driver has to be aware of this 313 // because it is only going to get a NodePublishVolume call for such a volume. 314 // For more information about implementing this mode, see 315 // https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html 316 // A driver can support one or more of these modes and 317 // more modes may be added in the future. 318 // +optional 319 VolumeLifecycleModes []VolumeLifecycleMode `json:"volumeLifecycleModes,omitempty" protobuf:"bytes,3,opt,name=volumeLifecycleModes"` 320} 321 322// VolumeLifecycleMode is an enumeration of possible usage modes for a volume 323// provided by a CSI driver. More modes may be added in the future. 324type VolumeLifecycleMode string 325 326const ( 327 // VolumeLifecyclePersistent explicitly confirms that the driver implements 328 // the full CSI spec. It is the default when CSIDriverSpec.VolumeLifecycleModes is not 329 // set. Such volumes are managed in Kubernetes via the persistent volume 330 // claim mechanism and have a lifecycle that is independent of the pods which 331 // use them. 332 VolumeLifecyclePersistent VolumeLifecycleMode = "Persistent" 333 334 // VolumeLifecycleEphemeral indicates that the driver can be used for 335 // ephemeral inline volumes. Such volumes are specified inside the pod 336 // spec with a CSIVolumeSource and, as far as Kubernetes is concerned, have 337 // a lifecycle that is tied to the lifecycle of the pod. For example, such 338 // a volume might contain data that gets created specifically for that pod, 339 // like secrets. 340 // But how the volume actually gets created and managed is entirely up to 341 // the driver. It might also use reference counting to share the same volume 342 // instance among different pods if the CSIVolumeSource of those pods is 343 // identical. 344 VolumeLifecycleEphemeral VolumeLifecycleMode = "Ephemeral" 345) 346 347// +genclient 348// +genclient:nonNamespaced 349// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 350 351// DEPRECATED - This group version of CSINode is deprecated by storage/v1/CSINode. 352// See the release notes for more information. 353// CSINode holds information about all CSI drivers installed on a node. 354// CSI drivers do not need to create the CSINode object directly. As long as 355// they use the node-driver-registrar sidecar container, the kubelet will 356// automatically populate the CSINode object for the CSI driver as part of 357// kubelet plugin registration. 358// CSINode has the same name as a node. If the object is missing, it means either 359// there are no CSI Drivers available on the node, or the Kubelet version is low 360// enough that it doesn't create this object. 361// CSINode has an OwnerReference that points to the corresponding node object. 362type CSINode struct { 363 metav1.TypeMeta `json:",inline"` 364 365 // metadata.name must be the Kubernetes node name. 366 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 367 368 // spec is the specification of CSINode 369 Spec CSINodeSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"` 370} 371 372// CSINodeSpec holds information about the specification of all CSI drivers installed on a node 373type CSINodeSpec struct { 374 // drivers is a list of information of all CSI Drivers existing on a node. 375 // If all drivers in the list are uninstalled, this can become empty. 376 // +patchMergeKey=name 377 // +patchStrategy=merge 378 Drivers []CSINodeDriver `json:"drivers" patchStrategy:"merge" patchMergeKey:"name" protobuf:"bytes,1,rep,name=drivers"` 379} 380 381// CSINodeDriver holds information about the specification of one CSI driver installed on a node 382type CSINodeDriver struct { 383 // This is the name of the CSI driver that this object refers to. 384 // This MUST be the same name returned by the CSI GetPluginName() call for 385 // that driver. 386 Name string `json:"name" protobuf:"bytes,1,opt,name=name"` 387 388 // nodeID of the node from the driver point of view. 389 // This field enables Kubernetes to communicate with storage systems that do 390 // not share the same nomenclature for nodes. For example, Kubernetes may 391 // refer to a given node as "node1", but the storage system may refer to 392 // the same node as "nodeA". When Kubernetes issues a command to the storage 393 // system to attach a volume to a specific node, it can use this field to 394 // refer to the node name using the ID that the storage system will 395 // understand, e.g. "nodeA" instead of "node1". This field is required. 396 NodeID string `json:"nodeID" protobuf:"bytes,2,opt,name=nodeID"` 397 398 // topologyKeys is the list of keys supported by the driver. 399 // When a driver is initialized on a cluster, it provides a set of topology 400 // keys that it understands (e.g. "company.com/zone", "company.com/region"). 401 // When a driver is initialized on a node, it provides the same topology keys 402 // along with values. Kubelet will expose these topology keys as labels 403 // on its own node object. 404 // When Kubernetes does topology aware provisioning, it can use this list to 405 // determine which labels it should retrieve from the node object and pass 406 // back to the driver. 407 // It is possible for different nodes to use different topology keys. 408 // This can be empty if driver does not support topology. 409 // +optional 410 TopologyKeys []string `json:"topologyKeys" protobuf:"bytes,3,rep,name=topologyKeys"` 411 412 // allocatable represents the volume resources of a node that are available for scheduling. 413 // +optional 414 Allocatable *VolumeNodeResources `json:"allocatable,omitempty" protobuf:"bytes,4,opt,name=allocatable"` 415} 416 417// VolumeNodeResources is a set of resource limits for scheduling of volumes. 418type VolumeNodeResources struct { 419 // Maximum number of unique volumes managed by the CSI driver that can be used on a node. 420 // A volume that is both attached and mounted on a node is considered to be used once, not twice. 421 // The same rule applies for a unique volume that is shared among multiple pods on the same node. 422 // If this field is nil, then the supported number of volumes on this node is unbounded. 423 // +optional 424 Count *int32 `json:"count,omitempty" protobuf:"varint,1,opt,name=count"` 425} 426 427// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 428 429// CSINodeList is a collection of CSINode objects. 430type CSINodeList struct { 431 metav1.TypeMeta `json:",inline"` 432 433 // Standard list metadata 434 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata 435 // +optional 436 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 437 438 // items is the list of CSINode 439 Items []CSINode `json:"items" protobuf:"bytes,2,rep,name=items"` 440} 441