README

cloud-provider

This repository defines the cloud-provider interface and mechanism to initialize a cloud-provider implementation into Kubernetes. Currently multiple processes use this code although the intent is that it will eventually only be cloud controller manager.

Note: go-get or vendor this package as k8s.io/cloud-provider.

Purpose

This library is a shared dependency for processes which need to be able to integrate with cloud-provider specific functionality.

Compatibility

Cloud Providers are expected to keep the HEAD of their implementations in sync with the HEAD of this repository.

Where does it come from?

cloud-provider is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/cloud-provider. Code changes are made in that location, merged into k8s.io/kubernetes and later synced here.

Things you should NOT do

  1. Add an cloud provider specific code to this repo.
  2. Directly modify anything under vendor/k8s.io/cloud-provider in this repo. Those are driven from k8s.io/kubernetes/staging/src/k8s.io/cloud-provider.
  3. Make interface changes without first discussing them with sig-cloudprovider.
Expand ▾ Collapse ▴

Documentation

Overview

    Package cloudprovider supplies interfaces and implementations for cloud service providers.

    Index

    Constants

    View Source
    const (
    	// CloudControllerManagerPort is the default port for the cloud controller manager server.
    	// This value may be overridden by a flag at startup.
    	CloudControllerManagerPort = 10258
    )

    Variables

    View Source
    var (
    	DiskNotFound         = errors.New("disk is not found")
    	ImplementedElsewhere = errors.New("implemented by alternate to cloud provider")
    	InstanceNotFound     = errors.New("instance not found")
    	NotImplemented       = errors.New("unimplemented")
    )

    Functions

    func DefaultLoadBalancerName

    func DefaultLoadBalancerName(service *v1.Service) string

      (DEPRECATED) DefaultLoadBalancerName is the default load balancer name that is called from LoadBalancer.GetLoadBalancerName. Use this method to maintain backward compatible names for LoadBalancers that were created prior to Kubernetes v1.12. In the future, each provider should replace this method call in GetLoadBalancerName with a provider-specific implementation that is less cryptic than the Service's UUID.

      func DeprecationWarningForProvider

      func DeprecationWarningForProvider(providerName string)

      func GetInstanceProviderID

      func GetInstanceProviderID(ctx context.Context, cloud Interface, nodeName types.NodeName) (string, error)

        GetInstanceProviderID builds a ProviderID for a node in a cloud.

        func IsCloudProvider

        func IsCloudProvider(name string) bool

          IsCloudProvider returns true if name corresponds to an already registered cloud provider.

          func IsExternal

          func IsExternal(name string) bool

            Detects if the string is an external cloud provider

            func RegisterCloudProvider

            func RegisterCloudProvider(name string, cloud Factory)

              RegisterCloudProvider registers a cloudprovider.Factory by name. This is expected to happen during app startup.

              Types

              type Clusters

              type Clusters interface {
              	// ListClusters lists the names of the available clusters.
              	ListClusters(ctx context.Context) ([]string, error)
              	// Master gets back the address (either DNS name or IP address) of the master node for the cluster.
              	Master(ctx context.Context, clusterName string) (string, error)
              }

                Clusters is an abstract, pluggable interface for clusters of containers.

                type ControllerClientBuilder

                type ControllerClientBuilder interface {
                	Config(name string) (*restclient.Config, error)
                	ConfigOrDie(name string) *restclient.Config
                	Client(name string) (clientset.Interface, error)
                	ClientOrDie(name string) clientset.Interface
                }

                  ControllerClientBuilder allows you to get clients and configs for controllers Please note a copy also exists in pkg/controller/client_builder.go TODO: Make this depend on the separate controller utilities repo (issues/68947)

                  type Factory

                  type Factory func(config io.Reader) (Interface, error)

                    Factory is a function that returns a cloudprovider.Interface. The config parameter provides an io.Reader handler to the factory in order to load specific configurations. If no configuration is provided the parameter is nil.

                    type InformerUser

                    type InformerUser interface {
                    	// SetInformers sets the informer on the cloud object.
                    	SetInformers(informerFactory informers.SharedInformerFactory)
                    }

                    type InstanceMetadata

                    type InstanceMetadata struct {
                    	// ProviderID is a unique ID used to idenfitify an instance on the cloud provider.
                    	// The ProviderID set here will be set on the node's spec.providerID field.
                    	// The provider ID format can be set by the cloud provider but providers should
                    	// ensure the format does not change in any incompatible way.
                    	//
                    	// The provider ID format used by existing cloud provider has been:
                    	//    <provider-name>://<instance-id>
                    	// Existing providers setting this field should preserve the existing format
                    	// currently being set in node.spec.providerID.
                    	ProviderID string
                    	// InstanceType is the instance's type.
                    	// The InstanceType set here will be set using the following labels on the node object:
                    	//   * node.kubernetes.io/instance-type=<instance-type>
                    	//   * beta.kubernetes.io/instance-type=<instance-type> (DEPRECATED)
                    	InstanceType string
                    	// NodeAddress contains information for the instance's address.
                    	// The node addresses returned here will be set on the node's status.addresses field.
                    	NodeAddresses []v1.NodeAddress
                    
                    	// Zone is the zone that the instance is in.
                    	// The value set here is applied as the following labels on the node:
                    	//   * topology.kubernetes.io/zone=<zone>
                    	//   * failure-domain.beta.kubernetes.io/zone=<zone> (DEPRECATED)
                    	Zone string
                    	// Region is the region that the instance is in.
                    	// The value set here is applied as the following labels on the node:
                    	//   * topology.kubernetes.io/region=<region>
                    	//   * failure-domain.beta.kubernetes.io/region=<region> (DEPRECATED)
                    	Region string
                    }

                      InstanceMetadata contains metadata about a specific instance. Values returned in InstanceMetadata are translated into specific fields and labels for Node.

                      type Instances

                      type Instances interface {
                      	// NodeAddresses returns the addresses of the specified instance.
                      	NodeAddresses(ctx context.Context, name types.NodeName) ([]v1.NodeAddress, error)
                      	// NodeAddressesByProviderID returns the addresses of the specified instance.
                      	// The instance is specified using the providerID of the node. The
                      	// ProviderID is a unique identifier of the node. This will not be called
                      	// from the node whose nodeaddresses are being queried. i.e. local metadata
                      	// services cannot be used in this method to obtain nodeaddresses
                      	NodeAddressesByProviderID(ctx context.Context, providerID string) ([]v1.NodeAddress, error)
                      	// InstanceID returns the cloud provider ID of the node with the specified NodeName.
                      	// Note that if the instance does not exist, we must return ("", cloudprovider.InstanceNotFound)
                      	// cloudprovider.InstanceNotFound should NOT be returned for instances that exist but are stopped/sleeping
                      	InstanceID(ctx context.Context, nodeName types.NodeName) (string, error)
                      	// InstanceType returns the type of the specified instance.
                      	InstanceType(ctx context.Context, name types.NodeName) (string, error)
                      	// InstanceTypeByProviderID returns the type of the specified instance.
                      	InstanceTypeByProviderID(ctx context.Context, providerID string) (string, error)
                      	// AddSSHKeyToAllInstances adds an SSH public key as a legal identity for all instances
                      	// expected format for the key is standard ssh-keygen format: <protocol> <blob>
                      	AddSSHKeyToAllInstances(ctx context.Context, user string, keyData []byte) error
                      	// CurrentNodeName returns the name of the node we are currently running on
                      	// On most clouds (e.g. GCE) this is the hostname, so we provide the hostname
                      	CurrentNodeName(ctx context.Context, hostname string) (types.NodeName, error)
                      	// InstanceExistsByProviderID returns true if the instance for the given provider exists.
                      	// If false is returned with no error, the instance will be immediately deleted by the cloud controller manager.
                      	// This method should still return true for instances that exist but are stopped/sleeping.
                      	InstanceExistsByProviderID(ctx context.Context, providerID string) (bool, error)
                      	// InstanceShutdownByProviderID returns true if the instance is shutdown in cloudprovider
                      	InstanceShutdownByProviderID(ctx context.Context, providerID string) (bool, error)
                      }

                        Instances is an abstract, pluggable interface for sets of instances.

                        type InstancesV2

                        type InstancesV2 interface {
                        	// InstanceExists returns true if the instance for the given node exists according to the cloud provider.
                        	// Use the node.name or node.spec.providerID field to find the node in the cloud provider.
                        	InstanceExists(ctx context.Context, node *v1.Node) (bool, error)
                        	// InstanceShutdown returns true if the instance is shutdown according to the cloud provider.
                        	// Use the node.name or node.spec.providerID field to find the node in the cloud provider.
                        	InstanceShutdown(ctx context.Context, node *v1.Node) (bool, error)
                        	// InstanceMetadata returns the instance's metadata. The values returned in InstanceMetadata are
                        	// translated into specific fields and labels in the Node object on registration.
                        	// Implementations should always check node.spec.providerID first when trying to discover the instance
                        	// for a given node. In cases where node.spec.providerID is empty, implementations can use other
                        	// properties of the node like its name, labels and annotations.
                        	InstanceMetadata(ctx context.Context, node *v1.Node) (*InstanceMetadata, error)
                        }

                          InstancesV2 is an abstract, pluggable interface for cloud provider instances. Unlike the Instances interface, it is designed for external cloud providers and should only be used by them. Implementation of this interface will disable calls to the Zones interface.

                          type Interface

                          type Interface interface {
                          	// Initialize provides the cloud with a kubernetes client builder and may spawn goroutines
                          	// to perform housekeeping or run custom controllers specific to the cloud provider.
                          	// Any tasks started here should be cleaned up when the stop channel closes.
                          	Initialize(clientBuilder ControllerClientBuilder, stop <-chan struct{})
                          	// LoadBalancer returns a balancer interface. Also returns true if the interface is supported, false otherwise.
                          	LoadBalancer() (LoadBalancer, bool)
                          	// Instances returns an instances interface. Also returns true if the interface is supported, false otherwise.
                          	Instances() (Instances, bool)
                          	// InstancesV2 is an implementation for instances and should only be implemented by external cloud providers.
                          	// Implementing InstancesV2 is behaviorally identical to Instances but is optimized to significantly reduce
                          	// API calls to the cloud provider when registering and syncing nodes. Implementation of this interface will
                          	// disable calls to the Zones interface. Also returns true if the interface is supported, false otherwise.
                          	InstancesV2() (InstancesV2, bool)
                          	// Zones returns a zones interface. Also returns true if the interface is supported, false otherwise.
                          	// DEPRECATED: Zones is deprecated in favor of retrieving zone/region information from InstancesV2.
                          	// This interface will not be called if InstancesV2 is enabled.
                          	Zones() (Zones, bool)
                          	// Clusters returns a clusters interface.  Also returns true if the interface is supported, false otherwise.
                          	Clusters() (Clusters, bool)
                          	// Routes returns a routes interface along with whether the interface is supported.
                          	Routes() (Routes, bool)
                          	// ProviderName returns the cloud provider ID.
                          	ProviderName() string
                          	// HasClusterID returns true if a ClusterID is required and set
                          	HasClusterID() bool
                          }

                            Interface is an abstract, pluggable interface for cloud providers.

                            func GetCloudProvider

                            func GetCloudProvider(name string, config io.Reader) (Interface, error)

                              GetCloudProvider creates an instance of the named cloud provider, or nil if the name is unknown. The error return is only used if the named provider was known but failed to initialize. The config parameter specifies the io.Reader handler of the configuration file for the cloud provider, or nil for no configuration.

                              func InitCloudProvider

                              func InitCloudProvider(name string, configFilePath string) (Interface, error)

                                InitCloudProvider creates an instance of the named cloud provider.

                                type LoadBalancer

                                type LoadBalancer interface {
                                	// TODO: Break this up into different interfaces (LB, etc) when we have more than one type of service
                                	// GetLoadBalancer returns whether the specified load balancer exists, and
                                	// if so, what its status is.
                                	// Implementations must treat the *v1.Service parameter as read-only and not modify it.
                                	// Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager
                                	GetLoadBalancer(ctx context.Context, clusterName string, service *v1.Service) (status *v1.LoadBalancerStatus, exists bool, err error)
                                	// GetLoadBalancerName returns the name of the load balancer. Implementations must treat the
                                	// *v1.Service parameter as read-only and not modify it.
                                	GetLoadBalancerName(ctx context.Context, clusterName string, service *v1.Service) string
                                	// EnsureLoadBalancer creates a new load balancer 'name', or updates the existing one. Returns the status of the balancer
                                	// Implementations must treat the *v1.Service and *v1.Node
                                	// parameters as read-only and not modify them.
                                	// Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager
                                	EnsureLoadBalancer(ctx context.Context, clusterName string, service *v1.Service, nodes []*v1.Node) (*v1.LoadBalancerStatus, error)
                                	// UpdateLoadBalancer updates hosts under the specified load balancer.
                                	// Implementations must treat the *v1.Service and *v1.Node
                                	// parameters as read-only and not modify them.
                                	// Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager
                                	UpdateLoadBalancer(ctx context.Context, clusterName string, service *v1.Service, nodes []*v1.Node) error
                                	// EnsureLoadBalancerDeleted deletes the specified load balancer if it
                                	// exists, returning nil if the load balancer specified either didn't exist or
                                	// was successfully deleted.
                                	// This construction is useful because many cloud providers' load balancers
                                	// have multiple underlying components, meaning a Get could say that the LB
                                	// doesn't exist even if some part of it is still laying around.
                                	// Implementations must treat the *v1.Service parameter as read-only and not modify it.
                                	// Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager
                                	EnsureLoadBalancerDeleted(ctx context.Context, clusterName string, service *v1.Service) error
                                }

                                  LoadBalancer is an abstract, pluggable interface for load balancers.

                                  Cloud provider may chose to implement the logic for constructing/destroying specific kinds of load balancers in a controller separate from the ServiceController. If this is the case, then {Ensure,Update}LoadBalancer must return the ImplementedElsewhere error. For the given LB service, the GetLoadBalancer must return "exists=True" if there exists a LoadBalancer instance created by ServiceController. In all other cases, GetLoadBalancer must return a NotFound error. EnsureLoadBalancerDeleted must not return ImplementedElsewhere to ensure proper teardown of resources that were allocated by the ServiceController. This can happen if a user changes the type of LB via an update to the resource or when migrating from ServiceController to alternate implementation. The finalizer on the service will be added and removed by ServiceController irrespective of the ImplementedElsewhere error. Additional finalizers for LB services must be managed in the alternate implementation.

                                  type PVLabeler

                                  type PVLabeler interface {
                                  	GetLabelsForVolume(ctx context.Context, pv *v1.PersistentVolume) (map[string]string, error)
                                  }

                                    PVLabeler is an abstract, pluggable interface for fetching labels for volumes

                                    type Route

                                    type Route struct {
                                    	// Name is the name of the routing rule in the cloud-provider.
                                    	// It will be ignored in a Create (although nameHint may influence it)
                                    	Name string
                                    	// TargetNode is the NodeName of the target instance.
                                    	TargetNode types.NodeName
                                    	// DestinationCIDR is the CIDR format IP range that this routing rule
                                    	// applies to.
                                    	DestinationCIDR string
                                    	// Blackhole is set to true if this is a blackhole route
                                    	// The node controller will delete the route if it is in the managed range.
                                    	Blackhole bool
                                    }

                                      Route is a representation of an advanced routing rule.

                                      type Routes

                                      type Routes interface {
                                      	// ListRoutes lists all managed routes that belong to the specified clusterName
                                      	ListRoutes(ctx context.Context, clusterName string) ([]*Route, error)
                                      	// CreateRoute creates the described managed route
                                      	// route.Name will be ignored, although the cloud-provider may use nameHint
                                      	// to create a more user-meaningful name.
                                      	CreateRoute(ctx context.Context, clusterName string, nameHint string, route *Route) error
                                      	// DeleteRoute deletes the specified managed route
                                      	// Route should be as returned by ListRoutes
                                      	DeleteRoute(ctx context.Context, clusterName string, route *Route) error
                                      }

                                        Routes is an abstract, pluggable interface for advanced routing rules.

                                        type Zone

                                        type Zone struct {
                                        	FailureDomain string
                                        	Region        string
                                        }

                                          Zone represents the location of a particular machine.

                                          type Zones

                                          type Zones interface {
                                          	// GetZone returns the Zone containing the current failure zone and locality region that the program is running in
                                          	// In most cases, this method is called from the kubelet querying a local metadata service to acquire its zone.
                                          	// For the case of external cloud providers, use GetZoneByProviderID or GetZoneByNodeName since GetZone
                                          	// can no longer be called from the kubelets.
                                          	GetZone(ctx context.Context) (Zone, error)
                                          
                                          	// GetZoneByProviderID returns the Zone containing the current zone and locality region of the node specified by providerID
                                          	// This method is particularly used in the context of external cloud providers where node initialization must be done
                                          	// outside the kubelets.
                                          	GetZoneByProviderID(ctx context.Context, providerID string) (Zone, error)
                                          
                                          	// GetZoneByNodeName returns the Zone containing the current zone and locality region of the node specified by node name
                                          	// This method is particularly used in the context of external cloud providers where node initialization must be done
                                          	// outside the kubelets.
                                          	GetZoneByNodeName(ctx context.Context, nodeName types.NodeName) (Zone, error)
                                          }

                                            Zones is an abstract, pluggable interface for zone enumeration. DEPRECATED: Zones is deprecated in favor of retrieving zone/region information from InstancesV2. This interface will not be called if InstancesV2 is enabled.

                                            Directories

                                            Path Synopsis
                                            app
                                            Package app implements a server that runs a set of active components.
                                            Package app implements a server that runs a set of active components.
                                            controllers
                                            route
                                            Package route contains code for syncing cloud routing rules with the list of registered nodes.
                                            Package route contains code for syncing cloud routing rules with the list of registered nodes.
                                            service
                                            Package service contains code for syncing cloud load balancers with the service registry.
                                            Package service contains code for syncing cloud load balancers with the service registry.
                                            Package fake is a test-double implementation of cloudprovider Interface, LoadBalancer and Instances.
                                            Package fake is a test-double implementation of cloudprovider Interface, LoadBalancer and Instances.
                                            node
                                            service