github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-07-26 21:17:23 +00:00
Code Issues Projects Releases Wiki Activity

cloud-provider: update docs and guidance for InstanceV2 and Zones

Browse Source 
Signed-off-by: Andrew Sy Kim <kim.andrewsy@gmail.com>
This commit is contained in:
Andrew Sy Kim 2020-11-10 00:59:40 -05:00
parent 082146a6e6
commit 80f2101da1
1 changed files with 12 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
staging/src/k8s.io/cloud-provider/cloud.go
View File

@ -51,11 +51,12 @@ type Interface interface {
Instances() (Instances, bool) Instances() (Instances, bool)
// InstancesV2 is an implementation for instances and should only be implemented by external cloud providers. // 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 // Implementing InstancesV2 is behaviorally identical to Instances but is optimized to significantly reduce
// API calls to the cloud provider when registering and syncing nodes. // API calls to the cloud provider when registering and syncing nodes. Implementation of this interface will
// Also returns true if the interface is supported, false otherwise. // disable calls to the Zones interface. Also returns true if the interface is supported, false otherwise.
// WARNING: InstancesV2 is an experimental interface and is subject to change in v1.20.
InstancesV2() (InstancesV2, bool) InstancesV2() (InstancesV2, bool)
// Zones returns a zones interface. Also returns true if the interface is supported, false otherwise. // 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) Zones() (Zones, bool)
// Clusters returns a clusters interface. Also returns true if the interface is supported, false otherwise. // Clusters returns a clusters interface. Also returns true if the interface is supported, false otherwise.
Clusters() (Clusters, bool) Clusters() (Clusters, bool)
@ -194,7 +195,7 @@ type Instances interface {
// InstancesV2 is an abstract, pluggable interface for cloud provider instances. // 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. // 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 { type InstancesV2 interface {
// InstanceExists returns true if the instance for the given node exists according to the cloud provider. // 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. // 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. // 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) InstanceShutdown(ctx context.Context, node *v1.Node) (bool, error)
// InstanceMetadata returns the instance's metadata. The values returned in InstanceMetadata are // InstanceMetadata returns the instance's metadata. The values returned in InstanceMetadata are
// translated into specific fields in the Node object on registration. // translated into specific fields and labels in the Node object on registration.
// Use the node.name or node.spec.providerID field to find the node in the cloud provider. // 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) 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. // 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 { type Zones interface {
// GetZone returns the Zone containing the current failure zone and locality region that the program is running in // 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. // 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. // 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 { type InstanceMetadata struct {
// ProviderID is a unique ID used to idenfitify an instance on the cloud provider. // 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 ProviderID set here will be set on the node's spec.providerID field.