diff --git a/Makefile b/Makefile index 9053c254..f5fe3bb9 100644 --- a/Makefile +++ b/Makefile @@ -77,6 +77,10 @@ all: build help: ## Display this help. @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST) +include Makefile-deps.mk + +include Makefile-deps.mk + ##@ Development .PHONY: manifests @@ -285,3 +289,8 @@ toc-update: .PHONY: toc-verify toc-verify: ./hack/verify-toc.sh + +.PHONY: generate-apiref +generate-apiref: genref + cd $(PROJECT_DIR)/hack/genref/ && $(GENREF) -o $(PROJECT_DIR)/docs/reference + \ No newline at end of file diff --git a/Makefile-deps.mk b/Makefile-deps.mk new file mode 100644 index 00000000..b2cdc1d4 --- /dev/null +++ b/Makefile-deps.mk @@ -0,0 +1,28 @@ +# 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. + +PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST)))) + +ifeq (,$(shell go env GOBIN)) + GOBIN=$(shell go env GOPATH)/bin +else + GOBIN=$(shell go env GOBIN) +endif +GO_CMD ?= go + + +GENREF = $(PROJECT_DIR)/bin/genref +.PHONY: genref +genref: ## Download genref locally if necessary. + @GOBIN=$(PROJECT_DIR)/bin $(GO_CMD) install github.com/kubernetes-sigs/reference-docs/genref@v0.28.0 diff --git a/docs/reference/leaderworkerset.v1.md b/docs/reference/leaderworkerset.v1.md new file mode 100644 index 00000000..9fdb6e4d --- /dev/null +++ b/docs/reference/leaderworkerset.v1.md @@ -0,0 +1,381 @@ +--- +title: LeaderWorkerSet API +content_type: tool-reference +package: leaderworkerset.x-k8s.io/v1 +auto_generated: true +description: Generated API reference documentation for leaderworkerset.x-k8s.io/v1. +--- + + +## Resource Types + + +- [LeaderWorkerSet](#leaderworkerset-x-k8s-io-v1-LeaderWorkerSet) + + +## `LeaderWorkerSet` {#leaderworkerset-x-k8s-io-v1-LeaderWorkerSet} + + +**Appears in:** + + + +

LeaderWorkerSet is the Schema for the leaderworkersets API

+ + + + + + + + + + + + + + + + + +
FieldDescription
apiVersion
string		leaderworkerset.x-k8s.io/v1
kind
string		LeaderWorkerSet
spec [Required]
+LeaderWorkerSetSpec +		 + No description provided.
status [Required]
+LeaderWorkerSetStatus +		 + No description provided.
+ +## `LeaderWorkerSetSpec` {#leaderworkerset-x-k8s-io-v1-LeaderWorkerSetSpec} + + +**Appears in:** + +- [LeaderWorkerSet](#leaderworkerset-x-k8s-io-v1-LeaderWorkerSet) + + +

One group consists of a single leader and M workers, and the total number of pods in a group is M+1. +LeaderWorkerSet will create N replicas of leader-worker pod groups (hereinafter referred to as group).

+

Each group has a unique index between 0 and N-1. We call this the leaderIndex. +The leaderIndex is used to uniquely name the leader pod of each group in the following format: +leaderWorkerSetName-leaderIndex. This is considered as the name of the group too.

+

Each worker pod in the group has a unique workerIndex between 1 and M. The leader also +gets a workerIndex, and it is always set to 0. +Worker pods are named using the format: leaderWorkerSetName-leaderIndex-workerIndex.

+ + + + + + + + + + + + + + + + + + + + +
FieldDescription
replicas
+int32 +		 +

Number of leader-workers groups. A scale subresource is available to enable HPA. The +selector for HPA will be that of the leader pod, and so practically HPA will be looking up the +leader pod metrics. Note that the leader pod could aggregate metrics from +the rest of the group and expose them as a summary custom metric representing the whole +group. +On scale down, the leader pod as well as the workers statefulset will be deleted. +Default to 1.

+
leaderWorkerTemplate [Required]
+LeaderWorkerTemplate +		 +

LeaderWorkerTemplate defines the template for leader/worker pods

+
rolloutStrategy
+RolloutStrategy +		 +

RolloutStrategy defines the strategy that will be applied to update replicas +when a revision is made to the leaderWorkerTemplate.

+
startupPolicy
+StartupPolicyType +		 +

StartupPolicy determines the startup policy for the worker statefulset.

+
+ +## `LeaderWorkerSetStatus` {#leaderworkerset-x-k8s-io-v1-LeaderWorkerSetStatus} + + +**Appears in:** + +- [LeaderWorkerSet](#leaderworkerset-x-k8s-io-v1-LeaderWorkerSet) + + +

LeaderWorkerSetStatus defines the observed state of LeaderWorkerSet

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
conditions [Required]
+[]k8s.io/apimachinery/pkg/apis/meta/v1.Condition +		 +

Conditions track the condition of the leaderworkerset.

+
readyReplicas [Required]
+int32 +		 +

ReadyReplicas track the number of groups that are in ready state (updated or not).

+
updatedReplicas [Required]
+int32 +		 +

UpdatedReplicas track the number of groups that have been updated (ready or not).

+
replicas [Required]
+int32 +		 +

Replicas track the total number of groups that have been created (updated or not, ready or not)

+
hpaPodSelector [Required]
+string +		 +

HPAPodSelector for pods that belong to the LeaderWorkerSet object, this is +needed for HPA to know what pods belong to the LeaderWorkerSet object. Here +we only select the leader pods.

+
+ +## `LeaderWorkerTemplate` {#leaderworkerset-x-k8s-io-v1-LeaderWorkerTemplate} + + +**Appears in:** + +- [LeaderWorkerSetSpec](#leaderworkerset-x-k8s-io-v1-LeaderWorkerSetSpec) + + +

Template of the leader/worker pods, the group will include at least one leader pod. +Defaults to the worker template if not specified. The idea is to allow users to create a +group with identical templates without needing to specify the template in both places. +For the leader it represents the id of the group, while for the workers it represents the +index within the group. For this reason, users should depend on the labels injected by this +API whenever possible.

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
leaderTemplate [Required]
+k8s.io/api/core/v1.PodTemplateSpec +		 +

LeaderTemplate defines the pod template for leader pods.

+
workerTemplate [Required]
+k8s.io/api/core/v1.PodTemplateSpec +		 +

WorkerTemplate defines the pod template for worker pods.

+
size
+int32 +		 +

Number of pods to create. It is the total number of pods in each group. +The minimum is 1 which represent the leader. When set to 1, the leader +pod is created for each group as well as a 0-replica StatefulSet for the workers. +Default to 1.

+
restartPolicy
+RestartPolicyType +		 +

RestartPolicy defines the restart policy when pod failures happen.

+
subGroupPolicy
+SubGroupPolicy +		 +

SubGroupPolicy describes the policy that will be applied when creating subgroups +in each replica.

+
+ +## `RestartPolicyType` {#leaderworkerset-x-k8s-io-v1-RestartPolicyType} + +(Alias of `string`) + +**Appears in:** + +- [LeaderWorkerTemplate](#leaderworkerset-x-k8s-io-v1-LeaderWorkerTemplate) + + + + + +## `RollingUpdateConfiguration` {#leaderworkerset-x-k8s-io-v1-RollingUpdateConfiguration} + + +**Appears in:** + +- [RolloutStrategy](#leaderworkerset-x-k8s-io-v1-RolloutStrategy) + + +

RollingUpdateConfiguration defines the parameters to be used for RollingUpdateStrategyType.

+ + + + + + + + + + + + + + +
FieldDescription
maxUnavailable [Required]
+k8s.io/apimachinery/pkg/util/intstr.IntOrString +		 +

The maximum number of replicas that can be unavailable during the update. +Value can be an absolute number (ex: 5) or a percentage of total replicas at the start of update (ex: 10%). +Absolute number is calculated from percentage by rounding down. +This can not be 0 if MaxSurge is 0. +By default, a fixed value of 1 is used. +Example: when this is set to 30%, the old replicas can be scaled down by 30% +immediately when the rolling update starts. Once new replicas are ready, old replicas +can be scaled down further, followed by scaling up the new replicas, ensuring +that at least 70% of original number of replicas are available at all times +during the update.

+
maxSurge [Required]
+k8s.io/apimachinery/pkg/util/intstr.IntOrString +		 +

The maximum number of replicas that can be scheduled above the original number of +replicas. +Value can be an absolute number (ex: 5) or a percentage of total replicas at +the start of the update (ex: 10%). +Absolute number is calculated from percentage by rounding up. +By default, a value of 0 is used. +Example: when this is set to 30%, the new replicas can be scaled up by 30% +immediately when the rolling update starts. Once old replicas have been deleted, +new replicas can be scaled up further, ensuring that total number of replicas running +at any time during the update is at most 130% of original replicas. +When rolling update completes, replicas will fall back to the original replicas.

+
+ +## `RolloutStrategy` {#leaderworkerset-x-k8s-io-v1-RolloutStrategy} + + +**Appears in:** + +- [LeaderWorkerSetSpec](#leaderworkerset-x-k8s-io-v1-LeaderWorkerSetSpec) + + +

RolloutStrategy defines the strategy that the leaderWorkerSet controller +will use to perform replica updates.

+ + + + + + + + + + + + + + +
FieldDescription
type [Required]
+RolloutStrategyType +		 +

Type defines the rollout strategy, it can only be “RollingUpdate” for now.

+
rollingUpdateConfiguration
+RollingUpdateConfiguration +		 +

RollingUpdateConfiguration defines the parameters to be used when type is RollingUpdateStrategyType.

+
+ +## `RolloutStrategyType` {#leaderworkerset-x-k8s-io-v1-RolloutStrategyType} + +(Alias of `string`) + +**Appears in:** + +- [RolloutStrategy](#leaderworkerset-x-k8s-io-v1-RolloutStrategy) + + + + + +## `StartupPolicyType` {#leaderworkerset-x-k8s-io-v1-StartupPolicyType} + +(Alias of `string`) + +**Appears in:** + +- [LeaderWorkerSetSpec](#leaderworkerset-x-k8s-io-v1-LeaderWorkerSetSpec) + + + + + +## `SubGroupPolicy` {#leaderworkerset-x-k8s-io-v1-SubGroupPolicy} + + +**Appears in:** + +- [LeaderWorkerTemplate](#leaderworkerset-x-k8s-io-v1-LeaderWorkerTemplate) + + +

SubGroupPolicy describes the policy that will be applied when creating subgroups.

+ + + + + + + + + + + +
FieldDescription
subGroupSize [Required]
+int32 +		 +

The number of pods per subgroup. This value is immutable, +and must not be greater than LeaderWorkerSet.Spec.Size. +Size must be divisible by subGroupSize in which case the +subgroups will be of equal size. Or size - 1 is divisible +by subGroupSize, in which case the leader is considered as +the extra pod, and will be part of the first subgroup.

+
+ \ No newline at end of file diff --git a/hack/genref/config.yaml b/hack/genref/config.yaml new file mode 100644 index 00000000..517f4990 --- /dev/null +++ b/hack/genref/config.yaml @@ -0,0 +1,19 @@ +hiddenMemberFields: + - "TypeMeta" + - "ObjectMeta" + +apis: + - name: leaderworkerset + title: LeaderWorkerSet API + package: sigs.k8s.io/lws + path: api/leaderworkerset/v1 + +externalPackages: + - match: ^k8s\.io/(api|apimachinery/pkg/apis)/ + target: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#{{- lower .TypeIdentifier -}}-{{- arrIndex .PackageSegments -1 -}}-{{- arrIndex .PackageSegments -2 -}} + - match: ^k8s\.io/apimachinery/pkg/api/resource\.Quantity$ + target: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity + - match: ^k8s.io/component-base/config/v1alpha1. + target: https://pkg.go.dev/k8s.io/component-base/config/v1alpha1#{{- .TypeIdentifier -}} + - match: ^time\.Duration$ + target: https://pkg.go.dev/time#Duration diff --git a/hack/genref/markdown/members.tpl b/hack/genref/markdown/members.tpl new file mode 100644 index 00000000..b9702186 --- /dev/null +++ b/hack/genref/markdown/members.tpl @@ -0,0 +1,34 @@ +{{ define "members" }} + {{/* . is a apiType */}} + {{- range .GetMembers -}} + {{/* . is a apiMember */}} + {{- if not .Hidden }} +{{ .FieldName }} + {{- if not .IsOptional }} [Required]{{- end -}} +
+{{/* Link for type reference */}} + {{- with .GetType -}} + {{- if .Link -}} +{{ .DisplayName }} + {{- else -}} +{{ .DisplayName }} + {{- end -}} + {{- end }} + + + {{- if .IsInline -}} +(Members of {{ .FieldName }} are embedded into this type.) + {{- end }} + {{ if .GetComment -}} + {{ .GetComment }} + {{- else -}} + No description provided. + {{- end }} + {{- if and (eq (.GetType.Name.Name) "ObjectMeta") -}} +Refer to the Kubernetes API documentation for the fields of the metadata field. + {{- end -}} + + + {{- end }} + {{- end }} +{{ end }} diff --git a/hack/genref/markdown/pkg.tpl b/hack/genref/markdown/pkg.tpl new file mode 100644 index 00000000..9a3d7532 --- /dev/null +++ b/hack/genref/markdown/pkg.tpl @@ -0,0 +1,46 @@ +{{ define "packages" -}} + +{{- range $idx, $val := .packages -}} +{{/* Special handling for config */}} + {{- if .IsMain -}} +--- +title: {{ .Title }} +content_type: tool-reference +package: {{ .DisplayName }} +auto_generated: true +description: Generated API reference documentation for {{ if ne .GroupName "" -}} {{ .DisplayName }}{{ else -}} LeaderWorkerSet Configuration{{- end -}}. +--- +{{ .GetComment -}} + {{- end -}} +{{- end }} + +## Resource Types + +{{ range .packages -}} + {{ $isConfig := (eq .GroupName "") }} + {{- range .VisibleTypes -}} + {{- if or .IsExported (and $isConfig (eq .DisplayName "Configuration")) }} +- [{{ .DisplayName }}]({{ .Link }}) + {{- end -}} + {{- end -}} +{{- end -}} + +{{ range .packages }} + {{ if ne .GroupName "" -}} + {{/* For package with a group name, list all type definitions in it. */}} + {{- range .VisibleTypes }} + {{- if or .Referenced .IsExported -}} +{{ template "type" . }} + {{- end -}} + {{ end }} + {{ else }} + {{/* For package w/o group name, list only types referenced. */}} + {{ $isConfig := (eq .GroupName "") }} + {{- range .VisibleTypes -}} + {{- if or .Referenced $isConfig -}} +{{ template "type" . }} + {{- end -}} + {{- end }} + {{- end }} +{{- end }} +{{- end }} diff --git a/hack/genref/markdown/type.tpl b/hack/genref/markdown/type.tpl new file mode 100644 index 00000000..e8e72358 --- /dev/null +++ b/hack/genref/markdown/type.tpl @@ -0,0 +1,37 @@ +{{ define "type" }} + +## `{{ .Name.Name }}` {#{{ .Anchor }}} + +{{ if eq .Kind "Alias" -}} +(Alias of `{{ .Underlying }}`) +{{ end }} + +{{- with .References }} +**Appears in:** +{{ range . }} +{{ if or .Referenced .IsExported -}} +- [{{ .DisplayName }}]({{ .Link }}) +{{ end -}} +{{- end -}} +{{- end }} + +{{ if .GetComment -}} +{{ .GetComment }} +{{ end }} +{{ if .GetMembers -}} + + + + {{/* . is a apiType */}} + {{- if .IsExported -}} +{{/* Add apiVersion and kind rows if deemed necessary */}} + + + {{ end -}} + +{{/* The actual list of members is in the following template */}} +{{- template "members" . -}} + +
FieldDescription
apiVersion
string		{{- .APIGroup -}}
kind
string		{{- .Name.Name -}}
+{{- end -}} +{{- end -}}