Cluster v1alpha1
apiVersion: cluster.karmada.io/v1alpha1
import "github.com/karmada-io/karmada/pkg/apis/cluster/v1alpha1"
Cluster
Cluster 表示成员集群的预期状态和当前状态。
apiVersion: cluster.karmada.io/v1alpha1
kind: Cluster
metadata (ObjectMeta)
spec (ClusterSpec),必选
Spec 表示成员集群的规范。
status (ClusterStatus)
Status 表示成员集群的状态。
ClusterSpec
ClusterSpec 定义成员集群的预期状态。
syncMode(string),必选
SyncMode 描述集群从 Karmada 控制面同步资源的方式。
apiEndpoint (string)
成员集群的 API 端点。取值包括 hostname、hostname:port、IP 和 IP:port。
id (string)
ID 是集群的唯一标识符。它不同于 uid(.metadata.uid),通常会在注册过程中自动从成员集群收集。
收集顺序如下:
如果注册集群启用了 ClusterProperty API 并通过创建名为 cluster.clusterset.k8s.io 的 ClusterProperty 对象来定义集群 ID,则 Karmada 将在 ClusterProperty 对象中获取定义的值。有关 ClusterProperty API 的更多详情,请浏览:https://github.com/kubernetes-sigs/about-api
在注册集群上获取命名空间 kube-system 的 UID。
此 UID 有以下用途:
- 是识别 Karmada 系统中的集群的唯一标识;
- 组成多集群服务的 DNS 名称。 一般情况下,不更新此 UID ,请谨慎操作。
impersonatorSecretRef (LocalSecretReference)
ImpersonatorSecretRef 表示包含用于伪装的令牌的密钥。密钥应包含以下凭据:- secret.data.token
LocalSecretReference 是指封闭命名空间内的密钥引用。
impersonatorSecretRef.name (string),必选
Name 指被引用资源的名称。
impersonatorSecretRef.namespace (string),必选
Namespace 指所引用资源的命名空间。
insecureSkipTLSVerification (boolean)
InsecureSkipTLSVerification 表示 Karmada 控制平面不应确认其所连接的集群的服务证书的有效性,这样会导致 Karmada 控制面与成员集群之间的 HTTPS 连接不安全。默认值为 false。
provider (string)
Provider 表示成员集群的云提供商名称。
proxyHeader (map[string]string)
ProxyHeader 是代理服务器所需的 HTTP 头。其中,键为 HTTP 头键,值为HTTP 头的负载。如果 HTTP 头有多个值,所有的值使用逗号分隔(例如,k1: v1,v2,v3)。
proxyURL (string)
ProxyURL 是集群的代理URL。如果不为空,则 Karmada 控制面会使用此代理与集群通信。更多详情,请参考:https://github.com/kubernetes/client-go/issues/351
region (string)
Region 表示成员集群所在的区域。
resourceModels ([]ResourceModel)
ResourceModels 是集群中资源建模的列表。每个建模配额都可以由用户自定义。建模名称必须是 cpu、memory、storage 或 ephemeral-storage。如果用户未定义建模名称和建模配额,将使用默认模型。默认模型的等级为 0 到 8。当 grade 设置为 0 或 1 时,默认模型的 CPU 配额和内存配额为固定值。当 grade 大于或等于 2 时,每个默认模型的 CPU 配额为:[2^(grade-1), 2^grade), 2 <= grade <= 7。每个默认模型的内存配额为:[2^(grade + 2), 2^(grade + 3)), 2 <= grade <= 7。例如:
grade: 0 ranges:
- name: "cpu" min: 0 C max: 1 C
- name: "memory" min: 0 GB max: 4 GB
grade: 1 ranges:
- name: "cpu" min: 1 C max: 2 C
- name: "memory" min: 4 GB max: 16 GB
grade: 2 ranges:
- name: "cpu" min: 2 C max: 4 C
- name: "memory" min: 16 GB max: 32 GB
grade: 7 range:
- name: "cpu" min: 64 C max: 128 C
- name: "memory" min: 512 GB max: 1024 GB
如果 grade 为 8,无论设置的 Max 值为多少,该等级中 Max 值的含义都表示无限。因此,可以设置任何大于 Min 值的数字。
grade: 8 range:
- name: "cpu" min: 128 C max: MAXINT
- name: "memory" min: 1024 GB max: MAXINT
ResourceModel 描述要统计的建模。
resourceModels.grade (int32),必选
Grade 是资源建模的索引。
resourceModels.ranges ([]ResourceModelRange),必选
Ranges 描述资源配额范围。
ResourceModelRange 描述每个建模配额从 min 到 max 的详细信息。注意:默认情况下,包含 min 值,但不包含 max 值。例如,设置 min = 2,max =10,则间隔为 [2, 10)。此规则能确保所有间隔具有相同的含义。如果最后一个间隔是无限的,肯定无法实现。因此,我们将正确的间隔定义为开放间隔。对于有效的间隔,右侧的值大于左侧的值,即 max 值 必须大于 min 值。建议所有 ResourceModelRanges 的 [Min, Max) 都可以是连续的间隔。
resourceModels.ranges.max (Quantity),必选
Max 指定资源的最大数量,由资源名称表示。特别说明,对于最后一个 ResourceModelRange ,无论传递的 Max 值是什么,都表示无限。因为对于最后一项,任何大于 Min 值的 ResourceModelRange 配额都将归为最后一项。任何情况下,Max 的值都大于 Min 的值。
resourceModels.ranges.min (Quantity),必选
Min 指定资源的最小数量,由资源名称表示。注意:等级 1 的 Min 值(通常为0)始终为零,例如,[1,2)等同于[0, 2)。
resourceModels.ranges.name (string),必选
Name 是要分类的资源的名称。
secretRef (LocalSecretReference)
SecretRef 表示密钥包含访问成员集群的强制性凭据。取值包括:- secret.data.token - secret.data.caBundle
LocalSecretReference 指封闭命名空间内的密钥引用。
secretRef.name (string),必选
Name 指所引用资源的名称。
secretRef.namespace (string),必选
Namespace 指所引用资源的命名空间。
taints ([]Taint)
附加到成员集群的污点。集群的污点对任何不容忍该污点的资源都有“影响”。
此污点所在的节点对任何不容忍污点的 Pod 都有“影响”。
taints.effect (string),必选
必选。污点对不容忍该污点的 Pod 的影响。有效取值包括 NoSchedule、PreferNoSchedule 和 NoExecute。
枚举值包括:
"NoExecute"
:任何不能容忍该污点的 Pod 都会被驱逐。当前由 NodeController 强制执行。"NoSchedule"
:如果新 pod 无法容忍该污点,不允许新 pod 调度到节点上,但允许由 Kubelet 调度但不需要调度器启动的所有 pod ,并允许节点上已存在的 Pod 继续运行。由调度器强制执行。"PreferNoSchedule"
:和 TaintEffectNoSchedule 相似,不同的是调度器尽量避免将新 Pod 调度到具有该污点的节点上,除非没有其他节点可调度。由调度器强制执行。
taints.key (string),必选
必选。应用到节点上的污点的键。
taints.timeAdded (Time)
TimeAdded 表示添加污点的时间。仅适用于 NoExecute 的污点。
Time 是 time.Time 的包装器,它支持对 YAML 和 JSON 的正确编组。time 包的许多工厂方法提供了包装器。
taints.value (string)
与污点键对应的污点值。
zone (string)
Zone 表示成员集群所在的区域。Deprecated 表示 Karmada 从未使用过该字段。为了向后兼容,不会从 v1alpha1 中删除该字段,请改用 Zones。
zones ([]string)
Zones 表示成员集群的故障区域(也称为可用区域)。这些区域以切片的形式显示,这样集群便可跨多个故障区域运行。欲了解在多个区域运行 Kubernetes的更多细节,请浏览:https://kubernetes.io/docs/setup/best-practices/multiple-zones/
ClusterStatus
ClusterStatus 包含有关集群当前状态的信息,由集群控制器定期更新。
apiEnablements ([]APIEnablement)
APIEnablements 表示成员集群的 API 列表。
APIEnablement 表示 API 列表,用于公开特定群组和版本中支持的资源的名称。
apiEnablements.groupVersion (string),必选
GroupVersion 是此 APIEnablement 的群组和版本。
apiEnablements.resources ([]APIResource)
Resources 是 APIResource 的列表。
APIResource 指定资源的名称和类别。
apiEnablements.resources.kind (string),必选
Kind 是资源的类别(例如,资源 deployments 的类别是 Deployment)
apiEnablements.resources.name (string),必选
Name 表示资源的复数名称。
conditions ([]Condition)
Conditions 表示当前集群的状况(数组结构)。
Condition 包含此 API 资源当前状态某个方面的详细信息。
conditions.lastTransitionTime (Time),必选
lastTransitionTime 是状况最近一次从一种状态转换到另一种状态的时间。这种变化通常出现在下层状况发生变化的时候。如果无法了解下层状况变化,使用 API 字段更改的时间也是可以接受的。
Time 是 time.Time 的包装器,它支持对 YAML 和 JSON 的正确编组。time 包的许多工厂方法提供了包装器。
conditions.message(string),必选
message 是有关转换的详细信息(人类可读消息)。可以是空字符串。
conditions.reason(string),必选
reason 是一个程序标识符,表明状况最后一次转换的原因。特定状况类型的生产者可以定义该字段的预期值和含义,以及这些值是否可被视为有保证的 API。取值应该是一个 CamelCase 字符串。此字段不能为空。
conditions.status(string),必选
status 表示状况的状态。取值为True、False或Unknown。
conditions.type(string),必选
type 表示状况的类型,采用 CamelCase 或 foo.example.com/CamelCase 形式。
conditions.observedGeneration (int64)
observedGeneration 表示设置状况时所基于的 .metadata.generation。例如,如果 .metadata.generation 为 12,但 .status.conditions[x].observedGeneration 为 9,则状况相对于实例的当前状态已过期。
kubernetesVersion (string)
KubernetesVersion 表示成员集群的版本。
nodeSummary (NodeSummary)
NodeSummary 表示成员集群中节点状态的汇总。
NodeSummary 表示特定集群中节点状态的汇总。
nodeSummary.readyNum (int32)
ReadyNum 指集群中就绪节点的数量。
nodeSummary.totalNum (int32)
TotalNum 指集群中的节点总数。
resourceSummary (ResourceSummary)
ResourceSummary 表示成员集群中资源的汇总。
ResourceSummary 表示成员集群中资源的汇总。
resourceSummary.allocatable (map[string][Quantity](../common-definitions/quantity#quantity))
Allocatable 表示集群中可用于调度的资源,是所有节点上可分配资源的总量。
resourceSummary.allocatableModelings ([]AllocatableModeling)
AllocatableModelings 表示统计资源建模。
AllocatableModeling 表示特定资源模型等级中可分配资源的节点数。例如,AllocatableModeling[Grade: 2, Count: 10] 表示有 10 个节点属于等级为 2 的资源模型。
resourceSummary.allocatableModelings.count (int32),必选
Count 统计能使用此建模所划定的资源的节点数。
resourceSummary.allocatableModelings.grade (int32),必选
Grade 是 ResourceModel 的索引。
resourceSummary.allocated (map[string][Quantity](../common-definitions/quantity#quantity))
Allocated 表示集群中已调度的资源,是已调度到节点的所有 Pod 所需资源的总和。
resourceSummary.allocating (map[string][Quantity](../common-definitions/quantity#quantity))
Allocating 表示集群中待调度的资源,是所有等待调度的 Pod 所需资源的总和。
ClusterList
ClusterList 罗列成员集群。
apiVersion: cluster.karmada.io/v1alpha1
kind: ClusterList
metadata (ListMeta)
items ([][Cluster](../cluster-resources/cluster-v1alpha1#cluster)),必选
Items 中包含 Cluster 列表。
操作
get
:查询指定的集群
HTTP 请求
GET /apis/cluster.karmada.io/v1alpha1/clusters/{name}
参数
name(路径参数):string,必选
Cluster 名称
pretty(查询参数):string
响应
200 (Cluster): OK
get
:查询指定集群的状态
HTTP 请求
GET /apis/cluster.karmada.io/v1alpha1/clusters/{name}/status
参数
name(路径参数):string,必选
集群的名称
pretty(查询参数):string
响应
200 (Cluster): OK
list
:查询所有集群
HTTP 请求
GET /apis/cluster.karmada.io/v1alpha1/clusters
参数
allowWatchBookmarks(查询参数):boolean
continue(查询参数):string
fieldSelector(查询参数):string
labelSelector(查询参数):string
limit(查询参数):integer
pretty(查询参数):string
resourceVersion(查询参数):string
resourceVersionMatch(查询参数):string
sendInitialEvents(查询参数):boolean
timeoutSeconds(查询参数):integer
watch(查询参数):boolean
响应
200 (ClusterList): OK
create
:创建一个集群
HTTP 请求
POST /apis/cluster.karmada.io/v1alpha1/clusters
Parameters
- body: Cluster,必选
dryRun(查询参数):string
fieldManager(查询参数):string
fieldValidation(查询参数):string
pretty(查询参数):string
响应
200 (Cluster): OK
201 (Cluster): Created
202 (Cluster): Accepted
update
:更新指定的集群
HTTP 请求
PUT /apis/cluster.karmada.io/v1alpha1/clusters/{name}
参数
name(路径参数):string,必选
集群的名称
body: Cluster,必选
dryRun(查询参数):string
fieldManager(查询参数):string
fieldValidation(查询参数):string
pretty(查询参数):string
响应
200 (Cluster): OK
201 (Cluster): Created
update
:更新指定集群的状态
HTTP 请求
PUT /apis/cluster.karmada.io/v1alpha1/clusters/{name}/status
参数
name(路径参数):string,必选
集群的名称
body: Cluster,必选
dryRun(查询参数):string
fieldManager(查询参数):string
fieldValidation(查询参数):string
pretty(查询参数):string
响应
200 (Cluster): OK
201 (Cluster): Created
patch
:更新指定集群的部分信息
HTTP 请求
PATCH /apis/cluster.karmada.io/v1alpha1/clusters/{name}
参数
name(路径参数):string,必选
集群的名称
body: Patch,必选
dryRun(查询参数):string
fieldManager(查询参数):string
fieldValidation(查询参数):string
force(查询参数):boolean
pretty(查询参数):string
响应
200 (Cluster): OK
201 (Cluster): Created
patch
:更新指定集群状态的部分信息
HTTP 请求
PATCH /apis/cluster.karmada.io/v1alpha1/clusters/{name}/status
参数
name(路径参数):string,必选
集群的名称
body: Patch,必选
dryRun(查询参数):string
fieldManager(查询参数):string
fieldValidation(查询参数):string
force(查询参数):boolean
pretty(查询参数):string
响应
200 (Cluster): OK
201 (Cluster): Created
delete
:删除一个集群
HTTP 请求
DELETE /apis/cluster.karmada.io/v1alpha1/clusters/{name}
参数
name(路径参数):string,必选
Cluster 名称
body: DeleteOptions
dryRun(查询参数):string
gracePeriodSeconds(查询参数):integer
pretty(查询参数):string
propagationPolicy(查询参数):string
响应
200 (Status): OK
202 (Status): Accepted
deletecollection
:删除所有集群
HTTP 请求
DELETE /apis/cluster.karmada.io/v1alpha1/clusters
参数
- body: DeleteOptions
continue(查询参数):string
dryRun(查询参数):string
fieldSelector(查询参数):string
gracePeriodSeconds(查询参数):integer
labelSelector(查询参数):string
limit(查询参数):integer
pretty(查询参数):string
propagationPolicy(查询参数):string
resourceVersion(查询参数):string
resourceVersionMatch(查询参数):string
sendInitialEvents(查询参数):boolean
timeoutSeconds(查询参数):integer
响应
200 (Status): OK