instanceset

package
v1.2.0-alpha.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2026 License: AGPL-3.0 Imports: 55 Imported by: 2

Documentation

Overview

Package instanceset is a general-purpose workload API designed to manage role-based stateful workloads, such as databases. Think of InstanceSet as an enhanced version of StatefulSet.

While the native StatefulSet in Kubernetes handles stateful workloads effectively, additional work is required when the workload pods have specific roles (e.g., leader/follower in etcd, primary/secondary in PostgreSQL, etc.).

InstanceSet provides the following features:

1. Role-based Update Strategy (Serial/Parallel/BestEffortParallel) 2. Role-based Access Mode (ReadWrite/Readonly/None) 3. Automatic Switchover 4. Membership Reconfiguration 5. Multiple Instance Templates 6. Specified Instance Scale In 7. In-place Instance Update

Index

Constants

View Source 
const (
	WorkloadsManagedByLabelKey = "workloads.kubeblocks.io/managed-by"
	WorkloadsInstanceLabelKey  = "workloads.kubeblocks.io/instance"

	RoleLabelKey = "kubeblocks.io/role"
)
View Source 
const (
	// MaxPlainRevisionCount specified max number of plain revision stored in status.updateRevisions.
	// All revisions will be compressed if exceeding this value.
	MaxPlainRevisionCount = "MAX_PLAIN_REVISION_COUNT"

	FeatureGateIgnorePodVerticalScaling = "IGNORE_POD_VERTICAL_SCALING"
)
View Source 
const (
	EventReasonStrictInPlace = "StrictInPlace"
)

Variables

View Source 
var (
	ErrContinue error
	ErrWait     = errors.New("wait")
	ErrStop     = errors.New("stop")
)

Functions

func AddAnnotationScope 

func AddAnnotationScope(scope AnnotationScope, annotations map[string]string) map[string]string

AddAnnotationScope will add AnnotationScope defined by 'scope' to all keys in map 'annotations'.

func CalculateConcurrencyReplicas added in v0.9.1 

func CalculateConcurrencyReplicas(concurrency *intstr.IntOrString, replicas int) (int, error)

CalculateConcurrencyReplicas returns absolute value of concurrency for workload. This func can solve some corner cases about percentage-type concurrency, such as: - if concurrency > "0%" and replicas > 0, it will ensure at least 1 pod is reserved. - if concurrency < "100%" and replicas > 1, it will ensure at least 1 pod is reserved.

if concurrency is nil, concurrency will be treated as 100%.

func ComposeRolePriorityMap 

func ComposeRolePriorityMap(roles []workloads.ReplicaRole) map[string]int

ComposeRolePriorityMap generates a priority map based on roles.

func ConvertOrdinalsToSortedList added in v0.9.1 

func ConvertOrdinalsToSortedList(ordinals kbappsv1.Ordinals) ([]int32, error)

func GenerateAllInstanceNames deprecated 

func GenerateAllInstanceNames(parentName string, replicas int32, templates []InstanceTemplate, offlineInstances []string, defaultTemplateOrdinals kbappsv1.Ordinals) ([]string, error)

Deprecated: should use instancetemplate.PodNameBuilder

func GenerateInstanceNamesFromTemplate 

func GenerateInstanceNamesFromTemplate(parentName, templateName string, replicas int32, offlineInstances []string, ordinalList []int32) ([]string, error)

func GetMatchLabels added in v1.0.0 

func GetMatchLabels(name string) map[string]string

GetMatchLabels exposes getMatchLabels for external usages TODO: remove this method when no usage

func GetPodNameSetFromInstanceSetCondition 

func GetPodNameSetFromInstanceSetCondition(its *workloads.InstanceSet, conditionType workloads.ConditionType) map[string]sets.Empty

GetPodNameSetFromInstanceSetCondition get the pod name sets from the InstanceSet conditions

func GetRevisions 

func GetRevisions(revisions map[string]string) (map[string]string, error)

func MergeNodeSelectorOnceAnnotation added in v0.9.2 

func MergeNodeSelectorOnceAnnotation(its *workloads.InstanceSet, podToNodeMapping map[string]string) error

MergeNodeSelectorOnceAnnotation merges its's nodeSelectorOnce annotation in place

func NewAPIVersionReconciler added in v0.9.3 

func NewAPIVersionReconciler() kubebuilderx.Reconciler

func NewAssistantObjectReconciler 

func NewAssistantObjectReconciler() kubebuilderx.Reconciler

func NewDeletionReconciler 

func NewDeletionReconciler() kubebuilderx.Reconciler

func NewFixMetaReconciler 

func NewFixMetaReconciler() kubebuilderx.Reconciler

func NewReplicasAlignmentReconciler 

func NewReplicasAlignmentReconciler() kubebuilderx.Reconciler

func NewRevisionUpdateReconciler 

func NewRevisionUpdateReconciler() kubebuilderx.Reconciler

func NewStatusReconciler 

func NewStatusReconciler() kubebuilderx.Reconciler

func NewTreeLoader 

func NewTreeLoader() kubebuilderx.TreeLoader

func NewUpdatePlan 

func NewUpdatePlan(its workloads.InstanceSet, pods []*corev1.Pod, isPodUpdated func(*workloads.InstanceSet, *corev1.Pod) (bool, error)) updatePlan

func NewUpdateReconciler 

func NewUpdateReconciler() kubebuilderx.Reconciler

func NewValidationReconciler 

func NewValidationReconciler() kubebuilderx.Reconciler

func ParseAnnotationsOfScope 

func ParseAnnotationsOfScope(scope AnnotationScope, scopedAnnotations map[string]string) map[string]string

ParseAnnotationsOfScope parses all annotations with AnnotationScope defined by 'scope'. the AnnotationScope suffix of keys in result map will be trimmed.

func ParseNodeSelectorOnceAnnotation added in v0.9.2 

func ParseNodeSelectorOnceAnnotation(its *workloads.InstanceSet) (map[string]string, error)

ParseNodeSelectorOnceAnnotation will return a non-nil map

func SortPods 

func SortPods(pods []corev1.Pod, rolePriorityMap map[string]int, reverse bool)

SortPods sorts pods by their role priority e.g.: unknown -> empty -> learner -> follower1 -> follower2 -> leader, with follower1.Name > follower2.Name reverse it if reverse==true

Types

type AnnotationScope 

type AnnotationScope string

AnnotationScope defines scope that annotations belong to.

it is a common pattern to add annotations to extend the functionalities of K8s builtin resources.

e.g.: Prometheus will start to scrape metrics if a service has annotation 'prometheus.io/scrape'.

The InstanceSet has encapsulated K8s builtin resources like Service, Headless Service, Pod, ConfigMap etc. AnnotationScope specified a way to tell the InstanceSet controller which resource an annotation belongs to.

e.g.: let's say we want to add an annotation 'prometheus.io/scrape' with value 'true' to the underlying headless service. here is what we should do: add annotation 'prometheus.io/scrape' with an HeadlessServiceScope suffix to the RSM object's annotations field. 

kind: InstanceSet
metadata:
  annotations:
    prometheus.io/scrape.headless.its: true

the InstanceSet controller will figure out which objects this annotation belongs to, cut the suffix and set it to the right place: 

kind: Service
metadata:
  annotations:
    prometheus.io/scrape: true

const (
	// RootScope specifies the annotation belongs to the RSM object itself.
	// they will also be set on the encapsulated StatefulSet.
	RootScope AnnotationScope = ""

	// HeadlessServiceScope specifies the annotation belongs to the encapsulated headless Service.
	HeadlessServiceScope AnnotationScope = ".headless.its"

	// ServiceScope specifies the annotation belongs to the encapsulated Service.
	ServiceScope AnnotationScope = ".svc.its"

	// AlternativeServiceScope specifies the annotation belongs to the encapsulated alternative Services.
	AlternativeServiceScope AnnotationScope = ".alternative.its"

	// ConfigMapScope specifies the annotation belongs to the encapsulated ConfigMap.
	ConfigMapScope AnnotationScope = ".cm.its"
)

type InstanceTemplate 

type InstanceTemplate interface {
	GetName() string
	GetReplicas() int32
	GetOrdinals() kbappsv1.Ordinals
}

type PodRoleEventHandler 

type PodRoleEventHandler struct{}

func (*PodRoleEventHandler) Handle 

func (h *PodRoleEventHandler) Handle(cli client.Client, reqCtx intctrlutil.RequestCtx, recorder record.EventRecorder, event *corev1.Event) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.