Coordinated Leader Election Alpha API

Kubernetes-commit: 3999b98c8840e41acaa19d94e88f46d1fbb0c1b3

coordination/v1/types.go

@@ -20,6 +20,18 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+type CoordinatedLeaseStrategy string
+
+// CoordinatedLeaseStrategy defines the strategy for picking the leader for coordinated leader election.
+const (
+	// OldestEmulationVersion picks the oldest LeaseCandidate, where "oldest" is defined as follows
+	// 1) Select the candidate(s) with the lowest emulation version
+	// 2) If multiple candidates have the same emulation version, select the candidate(s) with the lowest binary version. (Note that binary version must be greater or equal to emulation version)
+	// 3) If multiple candidates have the same binary version, select the candidate with the oldest creationTimestamp.
+	// If a candidate does not specify the emulationVersion and binaryVersion fields, it will not be considered a candidate for the lease.
+	OldestEmulationVersion CoordinatedLeaseStrategy = "OldestEmulationVersion"
+)
+
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +k8s:prerelease-lifecycle-gen:introduced=1.14
@@ -40,10 +52,12 @@ type Lease struct {
 // LeaseSpec is a specification of a Lease.
 type LeaseSpec struct {
 	// holderIdentity contains the identity of the holder of a current lease.
+	// If Coordinated Leader Election is used, the holder identity must be
+	// equal to the elected LeaseCandidate.metadata.name field.
 	// +optional
 	HolderIdentity *string `json:"holderIdentity,omitempty" protobuf:"bytes,1,opt,name=holderIdentity"`
 	// leaseDurationSeconds is a duration that candidates for a lease need
-	// to wait to force acquire it. This is measure against time of last
+	// to wait to force acquire it. This is measured against the time of last
 	// observed renewTime.
 	// +optional
 	LeaseDurationSeconds *int32 `json:"leaseDurationSeconds,omitempty" protobuf:"varint,2,opt,name=leaseDurationSeconds"`
@@ -58,6 +72,18 @@ type LeaseSpec struct {
 	// holders.
 	// +optional
 	LeaseTransitions *int32 `json:"leaseTransitions,omitempty" protobuf:"varint,5,opt,name=leaseTransitions"`
+	// Strategy indicates the strategy for picking the leader for coordinated leader election.
+	// If the field is not specified, there is no active coordination for this lease.
+	// (Alpha) Using this field requires the CoordinatedLeaderElection feature gate to be enabled.
+	// +featureGate=CoordinatedLeaderElection
+	// +optional
+	Strategy *CoordinatedLeaseStrategy `json:"strategy,omitempty" protobuf:"bytes,6,opt,name=strategy"`
+	// PreferredHolder signals to a lease holder that the lease has a
+	// more optimal holder and should be given up.
+	// This field can only be set if Strategy is also set.
+	// +featureGate=CoordinatedLeaderElection
+	// +optional
+	PreferredHolder *string `json:"preferredHolder,omitempty" protobuf:"bytes,7,opt,name=preferredHolder"`
 }
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

coordination/v1/types_swagger_doc_generated.go

@@ -49,11 +49,13 @@ func (LeaseList) SwaggerDoc() map[string]string {
 
 var map_LeaseSpec = map[string]string{
 	"":                     "LeaseSpec is a specification of a Lease.",
-	"holderIdentity":       "holderIdentity contains the identity of the holder of a current lease.",
-	"leaseDurationSeconds": "leaseDurationSeconds is a duration that candidates for a lease need to wait to force acquire it. This is measure against time of last observed renewTime.",
+	"holderIdentity":       "holderIdentity contains the identity of the holder of a current lease. If Coordinated Leader Election is used, the holder identity must be equal to the elected LeaseCandidate.metadata.name field.",
+	"leaseDurationSeconds": "leaseDurationSeconds is a duration that candidates for a lease need to wait to force acquire it. This is measured against the time of last observed renewTime.",
 	"acquireTime":          "acquireTime is a time when the current lease was acquired.",
 	"renewTime":            "renewTime is a time when the current holder of a lease has last updated the lease.",
 	"leaseTransitions":     "leaseTransitions is the number of transitions of a lease between holders.",
+	"strategy":             "Strategy indicates the strategy for picking the leader for coordinated leader election. If the field is not specified, there is no active coordination for this lease. (Alpha) Using this field requires the CoordinatedLeaderElection feature gate to be enabled.",
+	"preferredHolder":      "PreferredHolder signals to a lease holder that the lease has a more optimal holder and should be given up. This field can only be set if Strategy is also set.",
 }
 
 func (LeaseSpec) SwaggerDoc() map[string]string {

coordination/v1alpha1/doc.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// +k8s:deepcopy-gen=package
+// +k8s:protobuf-gen=package
+// +k8s:openapi-gen=true
+// +k8s:prerelease-lifecycle-gen=true
+
+// +groupName=coordination.k8s.io
+
+package v1alpha1 // import "k8s.io/api/coordination/v1alpha1"