StatefulSet

StatefulSet 代表一组具有一致身份的 Pod。

apiVersion: apps/v1

import "k8s.io/api/apps/v1"

StatefulSet

StatefulSet 代表一组具有一致身份的 Pod。身份定义为

  • 网络：一个稳定的 DNS 和主机名。
  • 存储：与请求数量相同的 VolumeClaims。

StatefulSet 保证给定的网络身份始终映射到相同的存储身份。

StatefulSetSpec

StatefulSetSpec 是 StatefulSet 的规范。

  • serviceName (string)

    serviceName 是管理此 StatefulSet 的服务的名称。此服务必须在 StatefulSet 之前存在，并负责集合的网络身份。Pod 会获取遵循模式 pod-specific-string.serviceName.default.svc.cluster.local 的 DNS/主机名，其中 "pod-specific-string" 由 StatefulSet 控制器管理。

  • selector (LabelSelector), 必需

    selector 是对 Pod 的标签查询，应与副本数匹配。它必须与 Pod 模板的标签匹配。更多信息：https://kubernetes.ac.cn/docs/concepts/overview/working-with-objects/labels/#label-selectors

  • template (PodTemplateSpec), 必需

    template 是一个对象，描述了在检测到副本不足时将创建的 Pod。StatefulSet 创建的每个 Pod 都将满足此 Template，但与其他 StatefulSet Pod 具有唯一的身份。每个 Pod 的命名格式为 <statefulsetname>-<podindex>。例如，名为 "web" 的 StatefulSet 中索引号为 "3" 的 Pod 将被命名为 "web-3"。唯一允许的 template.spec.restartPolicy 值是 "Always"。

  • replicas (int32)

    replicas 是给定 Template 的期望副本数。这些副本是同一 Template 的实例化，但单个副本也具有一致的身份。如果未指定，默认为 1。

  • updateStrategy (StatefulSetUpdateStrategy)

    updateStrategy 指示在 Template 修改后，更新 StatefulSet 中的 Pod 将采用的 StatefulSetUpdateStrategy。

    StatefulSetUpdateStrategy 指示 StatefulSet 控制器用于执行更新的策略。它包含执行指定策略所需的任何附加参数。

    • updateStrategy.type (string)

      Type 指示 StatefulSetUpdateStrategy 的类型。默认为 RollingUpdate。

    • updateStrategy.rollingUpdate (RollingUpdateStatefulSetStrategy)

      当 Type 为 RollingUpdateStatefulSetStrategyType 时，RollingUpdate 用于传递参数。

      RollingUpdateStatefulSetStrategy 用于传递 RollingUpdateStatefulSetStrategyType 的参数。

      • updateStrategy.rollingUpdate.maxUnavailable (IntOrString)

        更新期间最大不可用 Pod 数。值可以是绝对数字（例如：5）或期望 Pod 数的百分比（例如：10%）。绝对数字由百分比向上取整计算。此值不能为 0。默认为 1。此字段是 alpha 级别，仅在启用 MaxUnavailableStatefulSet 特性的服务器上生效。该字段适用于 0 到 Replicas-1 范围内的所有 Pod。这意味着如果在 0 到 Replicas-1 范围内有任何不可用的 Pod，它将被计入 MaxUnavailable。

        IntOrString 是一种可以保存 int32 或 string 的类型。在 JSON 或 YAML 的编组和解组时，它产生或消费内部类型。这使得你可以拥有一个 JSON 字段，例如可以接受名称或数字。

      • updateStrategy.rollingUpdate.partition (int32)

        Partition 指示 StatefulSet 应分区的用于更新的序号。在滚动更新期间，所有从序号 Replicas-1 到 Partition 的 Pod 都会被更新。所有从序号 Partition-1 到 0 的 Pod 保持不变。这有助于进行金丝雀部署。默认值为 0。

  • podManagementPolicy (string)

    podManagementPolicy 控制在初始扩容、替换节点上的 Pod 或缩容时如何创建 Pod。默认策略是 OrderedReady，Pod 按递增顺序创建（pod-0，然后是 pod-1 等），控制器会等待每个 Pod 准备就绪后才继续。缩容时，Pod 按相反顺序删除。另一种策略是 Parallel，它会并行创建 Pod 以匹配期望的规模而不等待，并在缩容时一次性删除所有 Pod。

  • revisionHistoryLimit (int32)

    revisionHistoryLimit 是 StatefulSet 修订历史记录中将保留的最大修订数。修订历史记录包含所有未由当前应用的 StatefulSetSpec 版本表示的修订。默认值为 10。

  • volumeClaimTemplates ([]PersistentVolumeClaim)

    Atomic: 在合并期间将被替换

    volumeClaimTemplates 是 Pod 被允许引用的 claims 列表。StatefulSet 控制器负责以一种保持 Pod 身份的方式将网络身份映射到 claims。此列表中的每个 claim 必须在 template 的一个容器中至少有一个匹配（按名称）的 volumeMount。此列表中的 claim 优先于 template 中同名的任何 volume。

  • minReadySeconds (int32)

    新创建的 Pod 在其任何容器未崩溃的情况下应处于 Ready 状态的最小秒数才被视为可用。默认为 0（Pod 一旦 Ready 就被视为可用）

  • persistentVolumeClaimRetentionPolicy (StatefulSetPersistentVolumeClaimRetentionPolicy)

    persistentVolumeClaimRetentionPolicy 描述了由 volumeClaimTemplates 创建的持久卷声明的生命周期。默认情况下，所有持久卷声明都是按需创建并保留，直到手动删除。此策略允许更改生命周期，例如在删除 StatefulSet 时删除持久卷声明，或在缩容 Pod 时删除。

    StatefulSetPersistentVolumeClaimRetentionPolicy 描述了用于从 StatefulSet VolumeClaimTemplates 创建的 PVC 的策略。

    • persistentVolumeClaimRetentionPolicy.whenDeleted (string)

      WhenDeleted 指定在 StatefulSet 删除时，由 StatefulSet VolumeClaimTemplates 创建的 PVC 会发生什么。默认策略 Retain 使 PVC 不受 StatefulSet 删除的影响。策略 Delete 使这些 PVC 被删除。

    • persistentVolumeClaimRetentionPolicy.whenScaled (string)

      WhenScaled 指定在 StatefulSet 缩容时，由 StatefulSet VolumeClaimTemplates 创建的 PVC 会发生什么。默认策略 Retain 使 PVC 不受缩容的影响。策略 Delete 会删除副本数以上多余 Pod 的关联 PVC。

  • ordinals (StatefulSetOrdinals)

    ordinals 控制 StatefulSet 中副本索引的编号。默认的 ordinals 行为为第一个副本分配索引“0”，并为每个请求的附加副本将索引加一。

    StatefulSetOrdinals 描述了此 StatefulSet 中用于副本序号分配的策略。

    • ordinals.start (int32)

      start 是表示第一个副本索引的数字。它可用于从备用索引（例如：从 1 开始索引）为副本编号，而不是默认的从 0 开始索引的名称，或用于协调副本从一个 StatefulSet 逐步移动到另一个 StatefulSet。如果设置，副本索引将在范围：[.spec.ordinals.start, .spec.ordinals.start + .spec.replicas) 内。如果未设置，默认为 0。副本索引将在范围：[0, .spec.replicas) 内。

StatefulSetStatus

StatefulSetStatus 表示 StatefulSet 的当前状态。

  • replicas (int32), 必需

    replicas 是由 StatefulSet 控制器创建的 Pod 数。

  • readyReplicas (int32)

    readyReplicas 是为此 StatefulSet 创建的具有 Ready Condition 的 Pod 数。

  • currentReplicas (int32)

    currentReplicas 是由 StatefulSet 控制器从 currentRevision 指定的 StatefulSet 版本创建的 Pod 数。

  • updatedReplicas (int32)

    updatedReplicas 是由 StatefulSet 控制器从 updateRevision 指定的 StatefulSet 版本创建的 Pod 数。

  • availableReplicas (int32)

    此 StatefulSet 目标的可用 Pod 总数（至少 Ready 了 minReadySeconds）。

  • collisionCount (int32)

    collisionCount 是 StatefulSet 的哈希碰撞计数。StatefulSet 控制器在需要为最新的 ControllerRevision 创建名称时，使用此字段作为避免碰撞的机制。

  • conditions ([]StatefulSetCondition)

    Patch 策略：按键 type 合并

    Map：合并期间将保留键 type 的唯一值

    表示 StatefulSet 当前状态的最新可用观察结果。

    StatefulSetCondition 描述了 StatefulSet 在某个时间点的状态。

    • conditions.status (string), 必需

      Condition 的状态，为 True、False、Unknown 之一。

    • conditions.type (string), 必需

      StatefulSet Condition 的类型。

    • conditions.lastTransitionTime (Time)

      Condition 上次从一个状态转换为另一个状态的时间。

      Time 是 time.Time 的一个包装器，支持正确地编组到 YAML 和 JSON。提供了 time 包提供的许多工厂方法的包装器。

    • conditions.message (string)

      一个人类可读的消息，指示有关转换的详细信息。

    • conditions.reason (string)

      Condition 上次转换的原因。

  • currentRevision (string)

    currentRevision 如果不为空，表示用于生成序列 [0, currentReplicas) 中 Pod 的 StatefulSet 版本。

  • updateRevision (string)

    updateRevision 如果不为空，表示用于生成序列 [replicas-updatedReplicas, replicas) 中 Pod 的 StatefulSet 版本。

  • observedGeneration (int64)

    observedGeneration 是此 StatefulSet 观察到的最新一代。它对应于 StatefulSet 的 generation，后者在 API Server 修改时更新。

StatefulSetList

StatefulSetList 是 StatefulSet 的集合。

操作

get 读取指定的 StatefulSet

HTTP 请求

GET /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}

参数

  • name (in path): string, 必需

    StatefulSet 的名称

  • namespace (in path): string, 必需

    namespace

  • pretty (in query): string

    pretty

响应

200 (StatefulSet): OK

401: Unauthorized

get 读取指定 StatefulSet 的状态

HTTP 请求

GET /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/status

参数

  • name (in path): string, 必需

    StatefulSet 的名称

  • namespace (in path): string, 必需

    namespace

  • pretty (in query): string

    pretty

响应

200 (StatefulSet): OK

401: Unauthorized

list 列出或监视 StatefulSet 类型的对象

HTTP 请求

GET /apis/apps/v1/namespaces/{namespace}/statefulsets

参数

响应

200 (StatefulSetList): OK

401: Unauthorized

list 列出或监视 StatefulSet 类型的对象

HTTP 请求

GET /apis/apps/v1/statefulsets

参数

响应

200 (StatefulSetList): OK

401: Unauthorized

create 创建一个 StatefulSet

HTTP 请求

POST /apis/apps/v1/namespaces/{namespace}/statefulsets

参数

响应

200 (StatefulSet): OK

201 (StatefulSet): 已创建

202 (StatefulSet): 已接受

401: Unauthorized

update 替换指定的 StatefulSet

HTTP 请求

PUT /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}

参数

响应

200 (StatefulSet): OK

201 (StatefulSet): 已创建

401: Unauthorized

update 替换指定 StatefulSet 的状态

HTTP 请求

PUT /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/status

参数

响应

200 (StatefulSet): OK

201 (StatefulSet): 已创建

401: Unauthorized

patch 部分更新指定的 StatefulSet

HTTP 请求

PATCH /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}

参数

  • name (in path): string, 必需

    StatefulSet 的名称

  • namespace (in path): string, 必需

    namespace

  • body: Patch, 必需

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

响应

200 (StatefulSet): OK

201 (StatefulSet): 已创建

401: Unauthorized

patch 部分更新指定 StatefulSet 的状态

HTTP 请求

PATCH /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}/status

参数

  • name (in path): string, 必需

    StatefulSet 的名称

  • namespace (in path): string, 必需

    namespace

  • body: Patch, 必需

  • dryRun (in query): string

    dryRun

  • fieldManager (in query): string

    fieldManager

  • fieldValidation (in query): string

    fieldValidation

  • force (in query): boolean

    force

  • pretty (in query): string

    pretty

响应

200 (StatefulSet): OK

201 (StatefulSet): 已创建

401: Unauthorized

delete 删除 StatefulSet

HTTP 请求

DELETE /apis/apps/v1/namespaces/{namespace}/statefulsets/{name}

参数

响应

200 (Status): OK

202 (Status): 已接受

401: Unauthorized

deletecollection 删除 StatefulSet 集合

HTTP 请求

DELETE /apis/apps/v1/namespaces/{namespace}/statefulsets

参数

响应

200 (Status): OK

401: Unauthorized

此页面是自动生成的。

如果你打算报告此页面的问题，请在问题描述中提及此页面是自动生成的。修复可能需要在 Kubernetes 项目的其他地方进行。

最后修改时间：2025 年 4 月 24 日 上午 9:14 PST：v1.33 的 Markdown API 参考 (b84ec30bbb)