diff --git a/staging/src/k8s.io/cloud-provider/cloud.go b/staging/src/k8s.io/cloud-provider/cloud.go index cdb2d095064..502443d61e7 100644 --- a/staging/src/k8s.io/cloud-provider/cloud.go +++ b/staging/src/k8s.io/cloud-provider/cloud.go @@ -51,11 +51,12 @@ type Interface interface { 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. - // Also returns true if the interface is supported, false otherwise. - // WARNING: InstancesV2 is an experimental interface and is subject to change in v1.20. + // 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) @@ -194,7 +195,7 @@ type Instances interface { // 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. -// WARNING: InstancesV2 is an experimental interface and is subject to change in v1.20. +// Implementation of this interface will disable calls to the Zones interface. 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. @@ -203,8 +204,10 @@ type InstancesV2 interface { // 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 in the Node object on registration. - // Use the node.name or node.spec.providerID field to find the node in the cloud provider. + // 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) } @@ -250,6 +253,8 @@ type Zone struct { } // 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. 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. @@ -274,7 +279,7 @@ type PVLabeler interface { } // InstanceMetadata contains metadata about a specific instance. -// Values returned in InstanceMetadata are translated into specific fields in Node. +// Values returned in InstanceMetadata are translated into specific fields and labels for Node. 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.