1/*
2Copyright 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
17
18// This file was autogenerated by go-to-protobuf. Do not edit it manually!
19
20syntax = "proto2";
21
22package k8s.io.api.storage.v1;
23
24import "k8s.io/api/core/v1/generated.proto";
25import "k8s.io/apimachinery/pkg/api/resource/generated.proto";
26import "k8s.io/apimachinery/pkg/apis/meta/v1/generated.proto";
27import "k8s.io/apimachinery/pkg/runtime/generated.proto";
28import "k8s.io/apimachinery/pkg/runtime/schema/generated.proto";
29
30// Package-wide variables from generator "generated".
31option go_package = "k8s.io/api/storage/v1";
32
33// CSIDriver captures information about a Container Storage Interface (CSI)
34// volume driver deployed on the cluster.
35// Kubernetes attach detach controller uses this object to determine whether attach is required.
36// Kubelet uses this object to determine whether pod information needs to be passed on mount.
37// CSIDriver objects are non-namespaced.
38message CSIDriver {
39 // Standard object metadata.
40 // metadata.Name indicates the name of the CSI driver that this object
41 // refers to; it MUST be the same name returned by the CSI GetPluginName()
42 // call for that driver.
43 // The driver name must be 63 characters or less, beginning and ending with
44 // an alphanumeric character ([a-z0-9A-Z]) with dashes (-), dots (.), and
45 // alphanumerics between.
46 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
47 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
48
49 // spec represents the specification of the CSI Driver.
50 optional CSIDriverSpec spec = 2;
51}
52
53// CSIDriverList is a collection of CSIDriver objects.
54message CSIDriverList {
55 // Standard list metadata
56 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
57 // +optional
58 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
59
60 // items is the list of CSIDriver
61 repeated CSIDriver items = 2;
62}
63
64// CSIDriverSpec is the specification of a CSIDriver.
65message CSIDriverSpec {
66 // attachRequired indicates this CSI volume driver requires an attach
67 // operation (because it implements the CSI ControllerPublishVolume()
68 // method), and that the Kubernetes attach detach controller should call
69 // the attach volume interface which checks the volumeattachment status
70 // and waits until the volume is attached before proceeding to mounting.
71 // The CSI external-attacher coordinates with CSI volume driver and updates
72 // the volumeattachment status when the attach operation is complete.
73 // If the CSIDriverRegistry feature gate is enabled and the value is
74 // specified to false, the attach operation will be skipped.
75 // Otherwise the attach operation will be called.
76 //
77 // This field is immutable.
78 //
79 // +optional
80 optional bool attachRequired = 1;
81
82 // podInfoOnMount indicates this CSI volume driver requires additional pod information (like podName, podUID, etc.)
83 // during mount operations, if set to true.
84 // If set to false, pod information will not be passed on mount.
85 // Default is false.
86 //
87 // The CSI driver specifies podInfoOnMount as part of driver deployment.
88 // If true, Kubelet will pass pod information as VolumeContext in the CSI NodePublishVolume() calls.
89 // The CSI driver is responsible for parsing and validating the information passed in as VolumeContext.
90 //
91 // The following VolumeContext will be passed if podInfoOnMount is set to true.
92 // This list might grow, but the prefix will be used.
93 // "csi.storage.k8s.io/pod.name": pod.Name
94 // "csi.storage.k8s.io/pod.namespace": pod.Namespace
95 // "csi.storage.k8s.io/pod.uid": string(pod.UID)
96 // "csi.storage.k8s.io/ephemeral": "true" if the volume is an ephemeral inline volume
97 // defined by a CSIVolumeSource, otherwise "false"
98 //
99 // "csi.storage.k8s.io/ephemeral" is a new feature in Kubernetes 1.16. It is only
100 // required for drivers which support both the "Persistent" and "Ephemeral" VolumeLifecycleMode.
101 // Other drivers can leave pod info disabled and/or ignore this field.
102 // As Kubernetes 1.15 doesn't support this field, drivers can only support one mode when
103 // deployed on such a cluster and the deployment determines which mode that is, for example
104 // via a command line parameter of the driver.
105 //
106 // This field was immutable in Kubernetes < 1.29 and now is mutable.
107 //
108 // +optional
109 optional bool podInfoOnMount = 2;
110
111 // volumeLifecycleModes defines what kind of volumes this CSI volume driver supports.
112 // The default if the list is empty is "Persistent", which is the usage defined by the
113 // CSI specification and implemented in Kubernetes via the usual PV/PVC mechanism.
114 //
115 // The other mode is "Ephemeral". In this mode, volumes are defined inline inside the pod spec
116 // with CSIVolumeSource and their lifecycle is tied to the lifecycle of that pod.
117 // A driver has to be aware of this because it is only going to get a NodePublishVolume call for such a volume.
118 //
119 // For more information about implementing this mode, see
120 // https://kubernetes-csi.github.io/docs/ephemeral-local-volumes.html
121 // A driver can support one or more of these modes and more modes may be added in the future.
122 //
123 // This field is beta.
124 // This field is immutable.
125 //
126 // +optional
127 // +listType=set
128 repeated string volumeLifecycleModes = 3;
129
130 // storageCapacity indicates that the CSI volume driver wants pod scheduling to consider the storage
131 // capacity that the driver deployment will report by creating
132 // CSIStorageCapacity objects with capacity information, if set to true.
133 //
134 // The check can be enabled immediately when deploying a driver.
135 // In that case, provisioning new volumes with late binding
136 // will pause until the driver deployment has published
137 // some suitable CSIStorageCapacity object.
138 //
139 // Alternatively, the driver can be deployed with the field
140 // unset or false and it can be flipped later when storage
141 // capacity information has been published.
142 //
143 // This field was immutable in Kubernetes <= 1.22 and now is mutable.
144 //
145 // +optional
146 // +featureGate=CSIStorageCapacity
147 optional bool storageCapacity = 4;
148
149 // fsGroupPolicy defines if the underlying volume supports changing ownership and
150 // permission of the volume before being mounted.
151 // Refer to the specific FSGroupPolicy values for additional details.
152 //
153 // This field was immutable in Kubernetes < 1.29 and now is mutable.
154 //
155 // Defaults to ReadWriteOnceWithFSType, which will examine each volume
156 // to determine if Kubernetes should modify ownership and permissions of the volume.
157 // With the default policy the defined fsGroup will only be applied
158 // if a fstype is defined and the volume's access mode contains ReadWriteOnce.
159 //
160 // +optional
161 optional string fsGroupPolicy = 5;
162
163 // tokenRequests indicates the CSI driver needs pods' service account
164 // tokens it is mounting volume for to do necessary authentication. Kubelet
165 // will pass the tokens in VolumeContext in the CSI NodePublishVolume calls.
166 // The CSI driver should parse and validate the following VolumeContext:
167 // "csi.storage.k8s.io/serviceAccount.tokens": {
168 // "<audience>": {
169 // "token": <token>,
170 // "expirationTimestamp": <expiration timestamp in RFC3339>,
171 // },
172 // ...
173 // }
174 //
175 // Note: Audience in each TokenRequest should be different and at
176 // most one token is empty string. To receive a new token after expiry,
177 // RequiresRepublish can be used to trigger NodePublishVolume periodically.
178 //
179 // +optional
180 // +listType=atomic
181 repeated TokenRequest tokenRequests = 6;
182
183 // requiresRepublish indicates the CSI driver wants `NodePublishVolume`
184 // being periodically called to reflect any possible change in the mounted
185 // volume. This field defaults to false.
186 //
187 // Note: After a successful initial NodePublishVolume call, subsequent calls
188 // to NodePublishVolume should only update the contents of the volume. New
189 // mount points will not be seen by a running container.
190 //
191 // +optional
192 optional bool requiresRepublish = 7;
193
194 // seLinuxMount specifies if the CSI driver supports "-o context"
195 // mount option.
196 //
197 // When "true", the CSI driver must ensure that all volumes provided by this CSI
198 // driver can be mounted separately with different `-o context` options. This is
199 // typical for storage backends that provide volumes as filesystems on block
200 // devices or as independent shared volumes.
201 // Kubernetes will call NodeStage / NodePublish with "-o context=xyz" mount
202 // option when mounting a ReadWriteOncePod volume used in Pod that has
203 // explicitly set SELinux context. In the future, it may be expanded to other
204 // volume AccessModes. In any case, Kubernetes will ensure that the volume is
205 // mounted only with a single SELinux context.
206 //
207 // When "false", Kubernetes won't pass any special SELinux mount options to the driver.
208 // This is typical for volumes that represent subdirectories of a bigger shared filesystem.
209 //
210 // Default is "false".
211 //
212 // +featureGate=SELinuxMountReadWriteOncePod
213 // +optional
214 optional bool seLinuxMount = 8;
215}
216
217// CSINode holds information about all CSI drivers installed on a node.
218// CSI drivers do not need to create the CSINode object directly. As long as
219// they use the node-driver-registrar sidecar container, the kubelet will
220// automatically populate the CSINode object for the CSI driver as part of
221// kubelet plugin registration.
222// CSINode has the same name as a node. If the object is missing, it means either
223// there are no CSI Drivers available on the node, or the Kubelet version is low
224// enough that it doesn't create this object.
225// CSINode has an OwnerReference that points to the corresponding node object.
226message CSINode {
227 // Standard object's metadata.
228 // metadata.name must be the Kubernetes node name.
229 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
230
231 // spec is the specification of CSINode
232 optional CSINodeSpec spec = 2;
233}
234
235// CSINodeDriver holds information about the specification of one CSI driver installed on a node
236message CSINodeDriver {
237 // name represents the name of the CSI driver that this object refers to.
238 // This MUST be the same name returned by the CSI GetPluginName() call for
239 // that driver.
240 optional string name = 1;
241
242 // nodeID of the node from the driver point of view.
243 // This field enables Kubernetes to communicate with storage systems that do
244 // not share the same nomenclature for nodes. For example, Kubernetes may
245 // refer to a given node as "node1", but the storage system may refer to
246 // the same node as "nodeA". When Kubernetes issues a command to the storage
247 // system to attach a volume to a specific node, it can use this field to
248 // refer to the node name using the ID that the storage system will
249 // understand, e.g. "nodeA" instead of "node1". This field is required.
250 optional string nodeID = 2;
251
252 // topologyKeys is the list of keys supported by the driver.
253 // When a driver is initialized on a cluster, it provides a set of topology
254 // keys that it understands (e.g. "company.com/zone", "company.com/region").
255 // When a driver is initialized on a node, it provides the same topology keys
256 // along with values. Kubelet will expose these topology keys as labels
257 // on its own node object.
258 // When Kubernetes does topology aware provisioning, it can use this list to
259 // determine which labels it should retrieve from the node object and pass
260 // back to the driver.
261 // It is possible for different nodes to use different topology keys.
262 // This can be empty if driver does not support topology.
263 // +optional
264 // +listType=atomic
265 repeated string topologyKeys = 3;
266
267 // allocatable represents the volume resources of a node that are available for scheduling.
268 // This field is beta.
269 // +optional
270 optional VolumeNodeResources allocatable = 4;
271}
272
273// CSINodeList is a collection of CSINode objects.
274message CSINodeList {
275 // Standard list metadata
276 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
277 // +optional
278 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
279
280 // items is the list of CSINode
281 repeated CSINode items = 2;
282}
283
284// CSINodeSpec holds information about the specification of all CSI drivers installed on a node
285message CSINodeSpec {
286 // drivers is a list of information of all CSI Drivers existing on a node.
287 // If all drivers in the list are uninstalled, this can become empty.
288 // +patchMergeKey=name
289 // +patchStrategy=merge
290 // +listType=map
291 // +listMapKey=name
292 repeated CSINodeDriver drivers = 1;
293}
294
295// CSIStorageCapacity stores the result of one CSI GetCapacity call.
296// For a given StorageClass, this describes the available capacity in a
297// particular topology segment. This can be used when considering where to
298// instantiate new PersistentVolumes.
299//
300// For example this can express things like:
301// - StorageClass "standard" has "1234 GiB" available in "topology.kubernetes.io/zone=us-east1"
302// - StorageClass "localssd" has "10 GiB" available in "kubernetes.io/hostname=knode-abc123"
303//
304// The following three cases all imply that no capacity is available for
305// a certain combination:
306// - no object exists with suitable topology and storage class name
307// - such an object exists, but the capacity is unset
308// - such an object exists, but the capacity is zero
309//
310// The producer of these objects can decide which approach is more suitable.
311//
312// They are consumed by the kube-scheduler when a CSI driver opts into
313// capacity-aware scheduling with CSIDriverSpec.StorageCapacity. The scheduler
314// compares the MaximumVolumeSize against the requested size of pending volumes
315// to filter out unsuitable nodes. If MaximumVolumeSize is unset, it falls back
316// to a comparison against the less precise Capacity. If that is also unset,
317// the scheduler assumes that capacity is insufficient and tries some other
318// node.
319message CSIStorageCapacity {
320 // Standard object's metadata.
321 // The name has no particular meaning. It must be a DNS subdomain (dots allowed, 253 characters).
322 // To ensure that there are no conflicts with other CSI drivers on the cluster,
323 // the recommendation is to use csisc-<uuid>, a generated name, or a reverse-domain name
324 // which ends with the unique CSI driver name.
325 //
326 // Objects are namespaced.
327 //
328 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
329 // +optional
330 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
331
332 // nodeTopology defines which nodes have access to the storage
333 // for which capacity was reported. If not set, the storage is
334 // not accessible from any node in the cluster. If empty, the
335 // storage is accessible from all nodes. This field is
336 // immutable.
337 //
338 // +optional
339 optional k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelector nodeTopology = 2;
340
341 // storageClassName represents the name of the StorageClass that the reported capacity applies to.
342 // It must meet the same requirements as the name of a StorageClass
343 // object (non-empty, DNS subdomain). If that object no longer exists,
344 // the CSIStorageCapacity object is obsolete and should be removed by its
345 // creator.
346 // This field is immutable.
347 optional string storageClassName = 3;
348
349 // capacity is the value reported by the CSI driver in its GetCapacityResponse
350 // for a GetCapacityRequest with topology and parameters that match the
351 // previous fields.
352 //
353 // The semantic is currently (CSI spec 1.2) defined as:
354 // The available capacity, in bytes, of the storage that can be used
355 // to provision volumes. If not set, that information is currently
356 // unavailable.
357 //
358 // +optional
359 optional k8s.io.apimachinery.pkg.api.resource.Quantity capacity = 4;
360
361 // maximumVolumeSize is the value reported by the CSI driver in its GetCapacityResponse
362 // for a GetCapacityRequest with topology and parameters that match the
363 // previous fields.
364 //
365 // This is defined since CSI spec 1.4.0 as the largest size
366 // that may be used in a
367 // CreateVolumeRequest.capacity_range.required_bytes field to
368 // create a volume with the same parameters as those in
369 // GetCapacityRequest. The corresponding value in the Kubernetes
370 // API is ResourceRequirements.Requests in a volume claim.
371 //
372 // +optional
373 optional k8s.io.apimachinery.pkg.api.resource.Quantity maximumVolumeSize = 5;
374}
375
376// CSIStorageCapacityList is a collection of CSIStorageCapacity objects.
377message CSIStorageCapacityList {
378 // Standard list metadata
379 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
380 // +optional
381 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
382
383 // items is the list of CSIStorageCapacity objects.
384 repeated CSIStorageCapacity items = 2;
385}
386
387// StorageClass describes the parameters for a class of storage for
388// which PersistentVolumes can be dynamically provisioned.
389//
390// StorageClasses are non-namespaced; the name of the storage class
391// according to etcd is in ObjectMeta.Name.
392message StorageClass {
393 // Standard object's metadata.
394 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
395 // +optional
396 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
397
398 // provisioner indicates the type of the provisioner.
399 optional string provisioner = 2;
400
401 // parameters holds the parameters for the provisioner that should
402 // create volumes of this storage class.
403 // +optional
404 map<string, string> parameters = 3;
405
406 // reclaimPolicy controls the reclaimPolicy for dynamically provisioned PersistentVolumes of this storage class.
407 // Defaults to Delete.
408 // +optional
409 optional string reclaimPolicy = 4;
410
411 // mountOptions controls the mountOptions for dynamically provisioned PersistentVolumes of this storage class.
412 // e.g. ["ro", "soft"]. Not validated -
413 // mount of the PVs will simply fail if one is invalid.
414 // +optional
415 // +listType=atomic
416 repeated string mountOptions = 5;
417
418 // allowVolumeExpansion shows whether the storage class allow volume expand.
419 // +optional
420 optional bool allowVolumeExpansion = 6;
421
422 // volumeBindingMode indicates how PersistentVolumeClaims should be
423 // provisioned and bound. When unset, VolumeBindingImmediate is used.
424 // This field is only honored by servers that enable the VolumeScheduling feature.
425 // +optional
426 optional string volumeBindingMode = 7;
427
428 // allowedTopologies restrict the node topologies where volumes can be dynamically provisioned.
429 // Each volume plugin defines its own supported topology specifications.
430 // An empty TopologySelectorTerm list means there is no topology restriction.
431 // This field is only honored by servers that enable the VolumeScheduling feature.
432 // +optional
433 // +listType=atomic
434 repeated k8s.io.api.core.v1.TopologySelectorTerm allowedTopologies = 8;
435}
436
437// StorageClassList is a collection of storage classes.
438message StorageClassList {
439 // Standard list metadata
440 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
441 // +optional
442 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
443
444 // items is the list of StorageClasses
445 repeated StorageClass items = 2;
446}
447
448// TokenRequest contains parameters of a service account token.
449message TokenRequest {
450 // audience is the intended audience of the token in "TokenRequestSpec".
451 // It will default to the audiences of kube apiserver.
452 optional string audience = 1;
453
454 // expirationSeconds is the duration of validity of the token in "TokenRequestSpec".
455 // It has the same default value of "ExpirationSeconds" in "TokenRequestSpec".
456 //
457 // +optional
458 optional int64 expirationSeconds = 2;
459}
460
461// VolumeAttachment captures the intent to attach or detach the specified volume
462// to/from the specified node.
463//
464// VolumeAttachment objects are non-namespaced.
465message VolumeAttachment {
466 // Standard object metadata.
467 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
468 // +optional
469 optional k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta metadata = 1;
470
471 // spec represents specification of the desired attach/detach volume behavior.
472 // Populated by the Kubernetes system.
473 optional VolumeAttachmentSpec spec = 2;
474
475 // status represents status of the VolumeAttachment request.
476 // Populated by the entity completing the attach or detach
477 // operation, i.e. the external-attacher.
478 // +optional
479 optional VolumeAttachmentStatus status = 3;
480}
481
482// VolumeAttachmentList is a collection of VolumeAttachment objects.
483message VolumeAttachmentList {
484 // Standard list metadata
485 // More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
486 // +optional
487 optional k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta metadata = 1;
488
489 // items is the list of VolumeAttachments
490 repeated VolumeAttachment items = 2;
491}
492
493// VolumeAttachmentSource represents a volume that should be attached.
494// Right now only PersistenVolumes can be attached via external attacher,
495// in future we may allow also inline volumes in pods.
496// Exactly one member can be set.
497message VolumeAttachmentSource {
498 // persistentVolumeName represents the name of the persistent volume to attach.
499 // +optional
500 optional string persistentVolumeName = 1;
501
502 // inlineVolumeSpec contains all the information necessary to attach
503 // a persistent volume defined by a pod's inline VolumeSource. This field
504 // is populated only for the CSIMigration feature. It contains
505 // translated fields from a pod's inline VolumeSource to a
506 // PersistentVolumeSpec. This field is beta-level and is only
507 // honored by servers that enabled the CSIMigration feature.
508 // +optional
509 optional k8s.io.api.core.v1.PersistentVolumeSpec inlineVolumeSpec = 2;
510}
511
512// VolumeAttachmentSpec is the specification of a VolumeAttachment request.
513message VolumeAttachmentSpec {
514 // attacher indicates the name of the volume driver that MUST handle this
515 // request. This is the name returned by GetPluginName().
516 optional string attacher = 1;
517
518 // source represents the volume that should be attached.
519 optional VolumeAttachmentSource source = 2;
520
521 // nodeName represents the node that the volume should be attached to.
522 optional string nodeName = 3;
523}
524
525// VolumeAttachmentStatus is the status of a VolumeAttachment request.
526message VolumeAttachmentStatus {
527 // attached indicates the volume is successfully attached.
528 // This field must only be set by the entity completing the attach
529 // operation, i.e. the external-attacher.
530 optional bool attached = 1;
531
532 // attachmentMetadata is populated with any
533 // information returned by the attach operation, upon successful attach, that must be passed
534 // into subsequent WaitForAttach or Mount calls.
535 // This field must only be set by the entity completing the attach
536 // operation, i.e. the external-attacher.
537 // +optional
538 map<string, string> attachmentMetadata = 2;
539
540 // attachError represents the last error encountered during attach operation, if any.
541 // This field must only be set by the entity completing the attach
542 // operation, i.e. the external-attacher.
543 // +optional
544 optional VolumeError attachError = 3;
545
546 // detachError represents the last error encountered during detach operation, if any.
547 // This field must only be set by the entity completing the detach
548 // operation, i.e. the external-attacher.
549 // +optional
550 optional VolumeError detachError = 4;
551}
552
553// VolumeError captures an error encountered during a volume operation.
554message VolumeError {
555 // time represents the time the error was encountered.
556 // +optional
557 optional k8s.io.apimachinery.pkg.apis.meta.v1.Time time = 1;
558
559 // message represents the error encountered during Attach or Detach operation.
560 // This string may be logged, so it should not contain sensitive
561 // information.
562 // +optional
563 optional string message = 2;
564}
565
566// VolumeNodeResources is a set of resource limits for scheduling of volumes.
567message VolumeNodeResources {
568 // count indicates the maximum number of unique volumes managed by the CSI driver that can be used on a node.
569 // A volume that is both attached and mounted on a node is considered to be used once, not twice.
570 // The same rule applies for a unique volume that is shared among multiple pods on the same node.
571 // If this field is not specified, then the supported number of volumes on this node is unbounded.
572 // +optional
573 optional int32 count = 1;
574}
575
View as plain text