1/* 2Copyright 2014 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 cloudprovider 18 19import ( 20 "context" 21 "errors" 22 "fmt" 23 "strings" 24 25 "k8s.io/api/core/v1" 26 "k8s.io/apimachinery/pkg/types" 27 "k8s.io/client-go/informers" 28 clientset "k8s.io/client-go/kubernetes" 29 restclient "k8s.io/client-go/rest" 30) 31 32// ControllerClientBuilder allows you to get clients and configs for controllers 33// Please note a copy also exists in pkg/controller/client_builder.go 34// TODO: Make this depend on the separate controller utilities repo (issues/68947) 35type ControllerClientBuilder interface { 36 Config(name string) (*restclient.Config, error) 37 ConfigOrDie(name string) *restclient.Config 38 Client(name string) (clientset.Interface, error) 39 ClientOrDie(name string) clientset.Interface 40} 41 42// Interface is an abstract, pluggable interface for cloud providers. 43type Interface interface { 44 // Initialize provides the cloud with a kubernetes client builder and may spawn goroutines 45 // to perform housekeeping or run custom controllers specific to the cloud provider. 46 // Any tasks started here should be cleaned up when the stop channel closes. 47 Initialize(clientBuilder ControllerClientBuilder, stop <-chan struct{}) 48 // LoadBalancer returns a balancer interface. Also returns true if the interface is supported, false otherwise. 49 LoadBalancer() (LoadBalancer, bool) 50 // Instances returns an instances interface. Also returns true if the interface is supported, false otherwise. 51 Instances() (Instances, bool) 52 // InstancesV2 is an implementation for instances and should only be implemented by external cloud providers. 53 // Implementing InstancesV2 is behaviorally identical to Instances but is optimized to significantly reduce 54 // API calls to the cloud provider when registering and syncing nodes. Implementation of this interface will 55 // disable calls to the Zones interface. Also returns true if the interface is supported, false otherwise. 56 InstancesV2() (InstancesV2, bool) 57 // Zones returns a zones interface. Also returns true if the interface is supported, false otherwise. 58 // DEPRECATED: Zones is deprecated in favor of retrieving zone/region information from InstancesV2. 59 // This interface will not be called if InstancesV2 is enabled. 60 Zones() (Zones, bool) 61 // Clusters returns a clusters interface. Also returns true if the interface is supported, false otherwise. 62 Clusters() (Clusters, bool) 63 // Routes returns a routes interface along with whether the interface is supported. 64 Routes() (Routes, bool) 65 // ProviderName returns the cloud provider ID. 66 ProviderName() string 67 // HasClusterID returns true if a ClusterID is required and set 68 HasClusterID() bool 69} 70 71type InformerUser interface { 72 // SetInformers sets the informer on the cloud object. 73 SetInformers(informerFactory informers.SharedInformerFactory) 74} 75 76// Clusters is an abstract, pluggable interface for clusters of containers. 77type Clusters interface { 78 // ListClusters lists the names of the available clusters. 79 ListClusters(ctx context.Context) ([]string, error) 80 // Master gets back the address (either DNS name or IP address) of the master node for the cluster. 81 Master(ctx context.Context, clusterName string) (string, error) 82} 83 84// (DEPRECATED) DefaultLoadBalancerName is the default load balancer name that is called from 85// LoadBalancer.GetLoadBalancerName. Use this method to maintain backward compatible names for 86// LoadBalancers that were created prior to Kubernetes v1.12. In the future, each provider should 87// replace this method call in GetLoadBalancerName with a provider-specific implementation that 88// is less cryptic than the Service's UUID. 89func DefaultLoadBalancerName(service *v1.Service) string { 90 //GCE requires that the name of a load balancer starts with a lower case letter. 91 ret := "a" + string(service.UID) 92 ret = strings.Replace(ret, "-", "", -1) 93 //AWS requires that the name of a load balancer is shorter than 32 bytes. 94 if len(ret) > 32 { 95 ret = ret[:32] 96 } 97 return ret 98} 99 100// GetInstanceProviderID builds a ProviderID for a node in a cloud. 101func GetInstanceProviderID(ctx context.Context, cloud Interface, nodeName types.NodeName) (string, error) { 102 instances, ok := cloud.Instances() 103 if !ok { 104 return "", fmt.Errorf("failed to get instances from cloud provider") 105 } 106 instanceID, err := instances.InstanceID(ctx, nodeName) 107 if err != nil { 108 if err == NotImplemented { 109 return "", err 110 } 111 112 return "", fmt.Errorf("failed to get instance ID from cloud provider: %v", err) 113 } 114 return cloud.ProviderName() + "://" + instanceID, nil 115} 116 117// LoadBalancer is an abstract, pluggable interface for load balancers. 118// 119// Cloud provider may chose to implement the logic for 120// constructing/destroying specific kinds of load balancers in a 121// controller separate from the ServiceController. If this is the case, 122// then {Ensure,Update}LoadBalancer must return the ImplementedElsewhere error. 123// For the given LB service, the GetLoadBalancer must return "exists=True" if 124// there exists a LoadBalancer instance created by ServiceController. 125// In all other cases, GetLoadBalancer must return a NotFound error. 126// EnsureLoadBalancerDeleted must not return ImplementedElsewhere to ensure 127// proper teardown of resources that were allocated by the ServiceController. 128// This can happen if a user changes the type of LB via an update to the resource 129// or when migrating from ServiceController to alternate implementation. 130// The finalizer on the service will be added and removed by ServiceController 131// irrespective of the ImplementedElsewhere error. Additional finalizers for 132// LB services must be managed in the alternate implementation. 133type LoadBalancer interface { 134 // TODO: Break this up into different interfaces (LB, etc) when we have more than one type of service 135 // GetLoadBalancer returns whether the specified load balancer exists, and 136 // if so, what its status is. 137 // Implementations must treat the *v1.Service parameter as read-only and not modify it. 138 // Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager 139 GetLoadBalancer(ctx context.Context, clusterName string, service *v1.Service) (status *v1.LoadBalancerStatus, exists bool, err error) 140 // GetLoadBalancerName returns the name of the load balancer. Implementations must treat the 141 // *v1.Service parameter as read-only and not modify it. 142 GetLoadBalancerName(ctx context.Context, clusterName string, service *v1.Service) string 143 // EnsureLoadBalancer creates a new load balancer 'name', or updates the existing one. Returns the status of the balancer 144 // Implementations must treat the *v1.Service and *v1.Node 145 // parameters as read-only and not modify them. 146 // Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager 147 EnsureLoadBalancer(ctx context.Context, clusterName string, service *v1.Service, nodes []*v1.Node) (*v1.LoadBalancerStatus, error) 148 // UpdateLoadBalancer updates hosts under the specified load balancer. 149 // Implementations must treat the *v1.Service and *v1.Node 150 // parameters as read-only and not modify them. 151 // Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager 152 UpdateLoadBalancer(ctx context.Context, clusterName string, service *v1.Service, nodes []*v1.Node) error 153 // EnsureLoadBalancerDeleted deletes the specified load balancer if it 154 // exists, returning nil if the load balancer specified either didn't exist or 155 // was successfully deleted. 156 // This construction is useful because many cloud providers' load balancers 157 // have multiple underlying components, meaning a Get could say that the LB 158 // doesn't exist even if some part of it is still laying around. 159 // Implementations must treat the *v1.Service parameter as read-only and not modify it. 160 // Parameter 'clusterName' is the name of the cluster as presented to kube-controller-manager 161 EnsureLoadBalancerDeleted(ctx context.Context, clusterName string, service *v1.Service) error 162} 163 164// Instances is an abstract, pluggable interface for sets of instances. 165type Instances interface { 166 // NodeAddresses returns the addresses of the specified instance. 167 NodeAddresses(ctx context.Context, name types.NodeName) ([]v1.NodeAddress, error) 168 // NodeAddressesByProviderID returns the addresses of the specified instance. 169 // The instance is specified using the providerID of the node. The 170 // ProviderID is a unique identifier of the node. This will not be called 171 // from the node whose nodeaddresses are being queried. i.e. local metadata 172 // services cannot be used in this method to obtain nodeaddresses 173 NodeAddressesByProviderID(ctx context.Context, providerID string) ([]v1.NodeAddress, error) 174 // InstanceID returns the cloud provider ID of the node with the specified NodeName. 175 // Note that if the instance does not exist, we must return ("", cloudprovider.InstanceNotFound) 176 // cloudprovider.InstanceNotFound should NOT be returned for instances that exist but are stopped/sleeping 177 InstanceID(ctx context.Context, nodeName types.NodeName) (string, error) 178 // InstanceType returns the type of the specified instance. 179 InstanceType(ctx context.Context, name types.NodeName) (string, error) 180 // InstanceTypeByProviderID returns the type of the specified instance. 181 InstanceTypeByProviderID(ctx context.Context, providerID string) (string, error) 182 // AddSSHKeyToAllInstances adds an SSH public key as a legal identity for all instances 183 // expected format for the key is standard ssh-keygen format: <protocol> <blob> 184 AddSSHKeyToAllInstances(ctx context.Context, user string, keyData []byte) error 185 // CurrentNodeName returns the name of the node we are currently running on 186 // On most clouds (e.g. GCE) this is the hostname, so we provide the hostname 187 CurrentNodeName(ctx context.Context, hostname string) (types.NodeName, error) 188 // InstanceExistsByProviderID returns true if the instance for the given provider exists. 189 // If false is returned with no error, the instance will be immediately deleted by the cloud controller manager. 190 // This method should still return true for instances that exist but are stopped/sleeping. 191 InstanceExistsByProviderID(ctx context.Context, providerID string) (bool, error) 192 // InstanceShutdownByProviderID returns true if the instance is shutdown in cloudprovider 193 InstanceShutdownByProviderID(ctx context.Context, providerID string) (bool, error) 194} 195 196// InstancesV2 is an abstract, pluggable interface for cloud provider instances. 197// Unlike the Instances interface, it is designed for external cloud providers and should only be used by them. 198// Implementation of this interface will disable calls to the Zones interface. 199type InstancesV2 interface { 200 // InstanceExists returns true if the instance for the given node exists according to the cloud provider. 201 // Use the node.name or node.spec.providerID field to find the node in the cloud provider. 202 InstanceExists(ctx context.Context, node *v1.Node) (bool, error) 203 // InstanceShutdown returns true if the instance is shutdown according to the cloud provider. 204 // Use the node.name or node.spec.providerID field to find the node in the cloud provider. 205 InstanceShutdown(ctx context.Context, node *v1.Node) (bool, error) 206 // InstanceMetadata returns the instance's metadata. The values returned in InstanceMetadata are 207 // translated into specific fields and labels in the Node object on registration. 208 // Implementations should always check node.spec.providerID first when trying to discover the instance 209 // for a given node. In cases where node.spec.providerID is empty, implementations can use other 210 // properties of the node like its name, labels and annotations. 211 InstanceMetadata(ctx context.Context, node *v1.Node) (*InstanceMetadata, error) 212} 213 214// Route is a representation of an advanced routing rule. 215type Route struct { 216 // Name is the name of the routing rule in the cloud-provider. 217 // It will be ignored in a Create (although nameHint may influence it) 218 Name string 219 // TargetNode is the NodeName of the target instance. 220 TargetNode types.NodeName 221 // DestinationCIDR is the CIDR format IP range that this routing rule 222 // applies to. 223 DestinationCIDR string 224 // Blackhole is set to true if this is a blackhole route 225 // The node controller will delete the route if it is in the managed range. 226 Blackhole bool 227} 228 229// Routes is an abstract, pluggable interface for advanced routing rules. 230type Routes interface { 231 // ListRoutes lists all managed routes that belong to the specified clusterName 232 ListRoutes(ctx context.Context, clusterName string) ([]*Route, error) 233 // CreateRoute creates the described managed route 234 // route.Name will be ignored, although the cloud-provider may use nameHint 235 // to create a more user-meaningful name. 236 CreateRoute(ctx context.Context, clusterName string, nameHint string, route *Route) error 237 // DeleteRoute deletes the specified managed route 238 // Route should be as returned by ListRoutes 239 DeleteRoute(ctx context.Context, clusterName string, route *Route) error 240} 241 242var ( 243 DiskNotFound = errors.New("disk is not found") 244 ImplementedElsewhere = errors.New("implemented by alternate to cloud provider") 245 InstanceNotFound = errors.New("instance not found") 246 NotImplemented = errors.New("unimplemented") 247) 248 249// Zone represents the location of a particular machine. 250type Zone struct { 251 FailureDomain string 252 Region string 253} 254 255// Zones is an abstract, pluggable interface for zone enumeration. 256// DEPRECATED: Zones is deprecated in favor of retrieving zone/region information from InstancesV2. 257// This interface will not be called if InstancesV2 is enabled. 258type Zones interface { 259 // GetZone returns the Zone containing the current failure zone and locality region that the program is running in 260 // In most cases, this method is called from the kubelet querying a local metadata service to acquire its zone. 261 // For the case of external cloud providers, use GetZoneByProviderID or GetZoneByNodeName since GetZone 262 // can no longer be called from the kubelets. 263 GetZone(ctx context.Context) (Zone, error) 264 265 // GetZoneByProviderID returns the Zone containing the current zone and locality region of the node specified by providerID 266 // This method is particularly used in the context of external cloud providers where node initialization must be done 267 // outside the kubelets. 268 GetZoneByProviderID(ctx context.Context, providerID string) (Zone, error) 269 270 // GetZoneByNodeName returns the Zone containing the current zone and locality region of the node specified by node name 271 // This method is particularly used in the context of external cloud providers where node initialization must be done 272 // outside the kubelets. 273 GetZoneByNodeName(ctx context.Context, nodeName types.NodeName) (Zone, error) 274} 275 276// PVLabeler is an abstract, pluggable interface for fetching labels for volumes 277type PVLabeler interface { 278 GetLabelsForVolume(ctx context.Context, pv *v1.PersistentVolume) (map[string]string, error) 279} 280 281// InstanceMetadata contains metadata about a specific instance. 282// Values returned in InstanceMetadata are translated into specific fields and labels for Node. 283type InstanceMetadata struct { 284 // ProviderID is a unique ID used to idenfitify an instance on the cloud provider. 285 // The ProviderID set here will be set on the node's spec.providerID field. 286 // The provider ID format can be set by the cloud provider but providers should 287 // ensure the format does not change in any incompatible way. 288 // 289 // The provider ID format used by existing cloud provider has been: 290 // <provider-name>://<instance-id> 291 // Existing providers setting this field should preserve the existing format 292 // currently being set in node.spec.providerID. 293 ProviderID string 294 // InstanceType is the instance's type. 295 // The InstanceType set here will be set using the following labels on the node object: 296 // * node.kubernetes.io/instance-type=<instance-type> 297 // * beta.kubernetes.io/instance-type=<instance-type> (DEPRECATED) 298 InstanceType string 299 // NodeAddress contains information for the instance's address. 300 // The node addresses returned here will be set on the node's status.addresses field. 301 NodeAddresses []v1.NodeAddress 302 303 // Zone is the zone that the instance is in. 304 // The value set here is applied as the following labels on the node: 305 // * topology.kubernetes.io/zone=<zone> 306 // * failure-domain.beta.kubernetes.io/zone=<zone> (DEPRECATED) 307 Zone string 308 // Region is the region that the instance is in. 309 // The value set here is applied as the following labels on the node: 310 // * topology.kubernetes.io/region=<region> 311 // * failure-domain.beta.kubernetes.io/region=<region> (DEPRECATED) 312 Region string 313} 314