README

CSINodeInfo and CSIDriverInfo Usage and Lifecycle

CSINodeInfo is an API object representing CSI Information at the Node level. CSINodeInfo contains a Spec and a Status, each containing Drivers represent the driver spec and status respectively. The CSIDriverInfoSpec represents the specification of the driver and is generally not changed, whereas the CSIDriverInfoStatus represents the current status of the driver and can be updated and reacted to by various components.

Who creates it and when

CSINodeInfo is created by Kubelet when the first CSI Driver is installed to the cluster and it is registered through the Kubelet device registration mechanism.

Who updates CSIDriverInfo Spec and when

The CSIDriverInfoSpec for a driver is created upon installation of the CSI Driver to the cluster and it is registered through the Kubelet device registration mechanism. The spec is populated with information about the driver through the nodeinfomanager (inside Kubelet) and will remain unchanged from then on.

Who updates Status and when

The CSIDriverInfoStatus for the driver is created upon installation of the CSI Driver to the cluster (the same time as the spec) and it is registered through the Kubelet device registration mechanism. The Status contains information about installation and the required Volume Plugin Mechanism of the driver. When the driver is installed/uninstalled through the Kubelet device registration mechanism the Available flag is flipped from true/false respectively. The migration status will also be updated when the flags for migration are set to true/false on the Kubelet for that Driver on that node.

Consumers of Status and Spec

Currently the only consumer of CSINodeInfo/CSIDriverInfo is the csi-external-provisioner. In the future, the Attach Detach Controller (ADC) will need to read this object to determine migration status on a per driver per node basis. The creation of the CSINodeInfo object could possibly race with the Attach/Detach controller as for CSI Migration the controller depend on the existence of the API object for the driver but it will not have been created yet. The ADC is expected to fail (and retry with exponential backoff) the operation if it is expecting the object and it has not yet been created.

Creation of CSINodeInfo object on Kubelet startup

For CSI Migration Alpha we expect any user who turns on the feature has both Kubelet and ADC at a version where the CSINodeInfo's are being created on Kubelet startup. We will not promote the feature to Beta (on by default) until the CSINodeInfo's are being created on Kubelet startup for a 2 version skew to prevent the case where the CSINodeInfo does not exist when the ADC depends on it. This prevents the race described above becoming a permanent bad state.

Expand ▾ Collapse ▴

Documentation

Overview

    Package v1alpha1 provides alpha API for CSI API objects.

    Index

    Constants

    View Source
    const (
    	// GroupName is the group name use in this package
    	GroupName string = "csi.storage.k8s.io"
    
    	// CsiDriverResourcePlural is the plural name of the CSIDriver resource
    	CsiDriverResourcePlural string = "csidrivers"
    
    	// CsiNodeInfoResourcePlural is the plural name of the CSINode resource
    	CsiNodeInfoResourcePlural string = "csinodeinfos"
    )

    Variables

    View Source
    var (
    	// SchemeBuilder collects schemas to build.
    	SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
    	// AddToScheme is used by generated client to add this scheme to the generated client.
    	AddToScheme = SchemeBuilder.AddToScheme
    )
    View Source
    var SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha1"}

      SchemeGroupVersion is group version used to register these objects

      Functions

      func Resource

      func Resource(resource string) schema.GroupResource

        Resource takes an unqualified resource and returns a Group qualified GroupResource

        Types

        type CSIDriver

        type CSIDriver struct {
        	metav1.TypeMeta `json:",inline"`
        
        	// Standard object metadata.
        	// metadata.Name indicates the name of the CSI driver that this object
        	// refers to; it MUST be the same name returned by the CSI GetPluginName()
        	// call for that driver.
        	// More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata
        	metav1.ObjectMeta `json:"metadata,omitempty"`
        
        	// Specification of the CSI Driver.
        	Spec CSIDriverSpec `json:"spec"`
        }

          CSIDriver captures information about a Container Storage Interface (CSI) volume driver deployed on the cluster. CSIDriver objects are non-namespaced.

          func (*CSIDriver) DeepCopy

          func (in *CSIDriver) DeepCopy() *CSIDriver

            DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSIDriver.

            func (*CSIDriver) DeepCopyInto

            func (in *CSIDriver) DeepCopyInto(out *CSIDriver)

              DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

              func (*CSIDriver) DeepCopyObject

              func (in *CSIDriver) DeepCopyObject() runtime.Object

                DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

                type CSIDriverInfoSpec

                type CSIDriverInfoSpec struct {
                	// name is the name of the CSI driver that this object refers to.
                	// This MUST be the same name returned by the CSI GetPluginName() call for
                	// that driver.
                	Name string `json:"name"`
                
                	// nodeID of the node from the driver point of view.
                	// This field enables Kubernetes to communicate with storage systems that do
                	// not share the same nomenclature for nodes. For example, Kubernetes may
                	// refer to a given node as "node1", but the storage system may refer to
                	// the same node as "nodeA". When Kubernetes issues a command to the storage
                	// system to attach a volume to a specific node, it can use this field to
                	// refer to the node name using the ID that the storage system will
                	// understand, e.g. "nodeA" instead of "node1".
                	NodeID string `json:"nodeID"`
                
                	// topologyKeys is the list of keys supported by the driver.
                	// When a driver is initialized on a cluster, it provides a set of topology
                	// keys that it understands (e.g. "company.com/zone", "company.com/region").
                	// When a driver is initialized on a node it provides the same topology keys
                	// along with values that kubelet applies to the coresponding node API
                	// object as labels.
                	// When Kubernetes does topology aware provisioning, it can use this list to
                	// determine which labels it should retrieve from the node object and pass
                	// back to the driver.
                	TopologyKeys []string `json:"topologyKeys"`
                }

                  CSIDriverInfoSpec holds information about the specification of one CSI driver installed on a node

                  func (*CSIDriverInfoSpec) DeepCopy

                  func (in *CSIDriverInfoSpec) DeepCopy() *CSIDriverInfoSpec

                    DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSIDriverInfoSpec.

                    func (*CSIDriverInfoSpec) DeepCopyInto

                    func (in *CSIDriverInfoSpec) DeepCopyInto(out *CSIDriverInfoSpec)

                      DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                      type CSIDriverInfoStatus

                      type CSIDriverInfoStatus struct {
                      	// name is the name of the CSI driver that this object refers to.
                      	// This MUST be the same name returned by the CSI GetPluginName() call for
                      	// that driver.
                      	Name string `json:"name"`
                      
                      	// available is a boolean representing whether the driver has been installed
                      	// on this node or not.
                      	Available bool `json:"available"`
                      
                      	// volumePluginMechanism announces what mechanism underlies volume plugins.
                      	// It is set by Kubelet. It is used by the attach/detach controller, which
                      	// needs to know how to perform attachments. The allowed values are:
                      	// * "in-tree": the volume operation (e.g., attach/detach) ought to be
                      	//   directly performed by the attach/detach controller.
                      	// * "csi-plugin": the attach/detach controller ought to request
                      	//   the csi plugin to perform the volume operation rather than perform it directly.
                      	VolumePluginMechanism VolumePluginMechanism `json:"volumePluginMechanism"`
                      }

                        CSIDriverInfoStatus holds information about the status of one CSI driver installed on a node

                        func (*CSIDriverInfoStatus) DeepCopy

                        func (in *CSIDriverInfoStatus) DeepCopy() *CSIDriverInfoStatus

                          DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSIDriverInfoStatus.

                          func (*CSIDriverInfoStatus) DeepCopyInto

                          func (in *CSIDriverInfoStatus) DeepCopyInto(out *CSIDriverInfoStatus)

                            DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                            type CSIDriverList

                            type CSIDriverList struct {
                            	metav1.TypeMeta `json:",inline"`
                            
                            	// Standard list metadata
                            	// More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata
                            	// +optional
                            	metav1.ListMeta `json:"metadata,omitempty"`
                            
                            	// items is the list of CSIDriver
                            	Items []CSIDriver `json:"items"`
                            }

                              CSIDriverList is a collection of CSIDriver objects.

                              func (*CSIDriverList) DeepCopy

                              func (in *CSIDriverList) DeepCopy() *CSIDriverList

                                DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSIDriverList.

                                func (*CSIDriverList) DeepCopyInto

                                func (in *CSIDriverList) DeepCopyInto(out *CSIDriverList)

                                  DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                                  func (*CSIDriverList) DeepCopyObject

                                  func (in *CSIDriverList) DeepCopyObject() runtime.Object

                                    DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

                                    type CSIDriverSpec

                                    type CSIDriverSpec struct {
                                    	// attachRequired indicates this CSI volume driver requires an attach
                                    	// operation (because it implements the CSI ControllerPublishVolume()
                                    	// method), and that Kubernetes should call attach and wait for any attach
                                    	// operation to complete before proceeding to mounting.
                                    	// If value is not specified, default is false -- meaning attach will not be
                                    	// called.
                                    	// +optional
                                    	AttachRequired *bool `json:"attachRequired,omitempty"`
                                    
                                    	// If specified, podInfoRequiredOnMount indicates this CSI volume driver
                                    	// requires additional pod information (like podName, podUID, etc.) during
                                    	// mount operations.
                                    	// If value is not specified, pod information will not be passed on mount.
                                    	// If value is set to a valid version, Kubelet will pass pod information as
                                    	// VolumeAttributes in the CSI NodePublishVolume() calls.
                                    	// Supported versions:
                                    	// Version "v1" will pass the following ValueAttributes
                                    	// "csi.storage.k8s.io/pod.name": pod.Name
                                    	// "csi.storage.k8s.io/pod.namespace": pod.Namespace
                                    	// "csi.storage.k8s.io/pod.uid": string(pod.UID)
                                    	// +optional
                                    	PodInfoOnMountVersion *string `json:"podInfoOnMountVersion,omitempty"`
                                    }

                                      CSIDriverSpec is the specification of a CSIDriver.

                                      func (*CSIDriverSpec) DeepCopy

                                      func (in *CSIDriverSpec) DeepCopy() *CSIDriverSpec

                                        DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSIDriverSpec.

                                        func (*CSIDriverSpec) DeepCopyInto

                                        func (in *CSIDriverSpec) DeepCopyInto(out *CSIDriverSpec)

                                          DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                                          type CSINodeInfo

                                          type CSINodeInfo struct {
                                          	metav1.TypeMeta `json:",inline"`
                                          
                                          	// metadata.name must be the Kubernetes node name.
                                          	metav1.ObjectMeta `json:"metadata,omitempty"`
                                          
                                          	// spec is the specification of CSINodeInfo
                                          	Spec CSINodeInfoSpec `json:"spec"`
                                          
                                          	// status is the current status of CSINodeInfo
                                          	Status CSINodeInfoStatus `json:"status"`
                                          }

                                            CSINodeInfo holds information about all CSI drivers installed on a node.

                                            func (*CSINodeInfo) DeepCopy

                                            func (in *CSINodeInfo) DeepCopy() *CSINodeInfo

                                              DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSINodeInfo.

                                              func (*CSINodeInfo) DeepCopyInto

                                              func (in *CSINodeInfo) DeepCopyInto(out *CSINodeInfo)

                                                DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                                                func (*CSINodeInfo) DeepCopyObject

                                                func (in *CSINodeInfo) DeepCopyObject() runtime.Object

                                                  DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

                                                  type CSINodeInfoList

                                                  type CSINodeInfoList struct {
                                                  	metav1.TypeMeta `json:",inline"`
                                                  
                                                  	// Standard list metadata
                                                  	// More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata
                                                  	// +optional
                                                  	metav1.ListMeta `json:"metadata,omitempty"`
                                                  
                                                  	// items is the list of CSINodeInfo
                                                  	Items []CSINodeInfo `json:"items"`
                                                  }

                                                    CSINodeInfoList is a collection of CSINodeInfo objects.

                                                    func (*CSINodeInfoList) DeepCopy

                                                    func (in *CSINodeInfoList) DeepCopy() *CSINodeInfoList

                                                      DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSINodeInfoList.

                                                      func (*CSINodeInfoList) DeepCopyInto

                                                      func (in *CSINodeInfoList) DeepCopyInto(out *CSINodeInfoList)

                                                        DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                                                        func (*CSINodeInfoList) DeepCopyObject

                                                        func (in *CSINodeInfoList) DeepCopyObject() runtime.Object

                                                          DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

                                                          type CSINodeInfoSpec

                                                          type CSINodeInfoSpec struct {
                                                          	// drivers is a list of specifications of CSIDriverInfo
                                                          	// +patchMergeKey=name
                                                          	// +patchStrategy=merge
                                                          	Drivers []CSIDriverInfoSpec `json:"drivers" patchStrategy:"merge" patchMergeKey:"name"`
                                                          }

                                                            CSINodeInfoSpec holds information about the specification of all CSI drivers installed on a node

                                                            func (*CSINodeInfoSpec) DeepCopy

                                                            func (in *CSINodeInfoSpec) DeepCopy() *CSINodeInfoSpec

                                                              DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSINodeInfoSpec.

                                                              func (*CSINodeInfoSpec) DeepCopyInto

                                                              func (in *CSINodeInfoSpec) DeepCopyInto(out *CSINodeInfoSpec)

                                                                DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                                                                type CSINodeInfoStatus

                                                                type CSINodeInfoStatus struct {
                                                                	// drivers is a list of the statuses of CSIDriverInfo
                                                                	// +patchMergeKey=name
                                                                	// +patchStrategy=merge
                                                                	Drivers []CSIDriverInfoStatus `json:"drivers" patchStrategy:"merge" patchMergeKey:"name"`
                                                                }

                                                                  CSINodeInfoStatus holds information about the status of all CSI drivers installed on a node

                                                                  func (*CSINodeInfoStatus) DeepCopy

                                                                  func (in *CSINodeInfoStatus) DeepCopy() *CSINodeInfoStatus

                                                                    DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CSINodeInfoStatus.

                                                                    func (*CSINodeInfoStatus) DeepCopyInto

                                                                    func (in *CSINodeInfoStatus) DeepCopyInto(out *CSINodeInfoStatus)

                                                                      DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

                                                                      type VolumePluginMechanism

                                                                      type VolumePluginMechanism string

                                                                        VolumePluginMechanism is the type of mechanism components should use for volume operations

                                                                        const (
                                                                        	// VolumePluginMechanismInTree means components should use the in-tree plugin for volume operations
                                                                        	VolumePluginMechanismInTree VolumePluginMechanism = "in-tree"
                                                                        	// VolumePluginMechanismCSI means components should use the CSI Driver for volume operations
                                                                        	VolumePluginMechanismCSI VolumePluginMechanism = "csi"
                                                                        )