版本：v2.0

Advanced StatefulSet

这个控制器基于原生 StatefulSet 上增强了发布能力，比如 maxUnavailable 并行发布、原地升级等。

如果你对原生 StatefulSet 不是很了解，我们强烈建议你先阅读它的文档（在学习 Advanced StatefulSet 之前）：

注意 Advanced StatefulSet 是一个 CRD，kind 名字也是 StatefulSet，但是 apiVersion 是 apps.kruise.io/v1beta1。这个 CRD 的所有默认字段、默认行为与原生 StatefulSet 完全一致，除此之外还提供了一些 optional 字段来扩展增强的策略。

因此，用户从原生 StatefulSet 迁移到 Advanced StatefulSet，只需要把 apiVersion 修改后提交即可：

- apiVersion: apps/v1
+ apiVersion: apps.kruise.io/v1beta1
  kind: StatefulSet
  metadata:
    name: sample
  spec:
  #...

注意从 Kruise 0.7.0 开始，Advanced StatefulSet 版本升级到了 v1beta1，并与 v1alpha1 兼容。对于低于 v0.7.0 版本的 Kruise，只能使用 v1alpha1。

Pod 标识

StatefulSet Pod 具有唯一的标识，该标识包括顺序标识、稳定的网络标识和稳定的存储。该标识和 Pod 是绑定的，与该 Pod 调度到哪个节点上无关。

序号索引

FEATURE STATE: Kruise v1.7.0

对于具有 N 个副本的 StatefulSet，该 StatefulSet 中的每个 Pod 将被分配一个整数序号，该序号在此 StatefulSet 中是唯一的。默认情况下，这些 Pod 将被赋予从 0 到 N-1 的序号。StatefulSet 控制器也会添加一个包含此索引的 Pod 标签：apps.kubernetes.io/pod-index，如下：

apiVersion: v1
kind: Pod
metadata:
  labels:
    app: sample
    apps.kubernetes.io/pod-index: "0"
  name: sample-0

起始序号

FEATURE STATE: Kruise v1.7.0

Pod 起始序号默认都是从 0 开始的，此外，你也可以通过设置 .spec.ordinals.start 字段来设置 Pod 起始序号。使用该能力，你需要开启 FeatureGate StatefulSetStartOrdinal=true。

spec.ordinals.start：如果 .spec.ordinals.start 字段被设置，则 Pod 将被分配从 .spec.ordinals.start 到 .spec.ordinals.start + .spec.replicas - 1 的序号。比如：replicas=5、ordinals.start=3，Pod 序号 = [3, 7]。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
metadata:
  name: sample
spec:
  replicas: 5
  ordinals:
    start: 3
  serviceName: fake-service
  selector:
    matchLabels:
      app: sample
  template:
    metadata:
      labels:
        app: sample
    spec:
      containers:
      - name: main
        image: nginx:alpine

User Stories

起始序号能力主要是为了使 StatefulSet 更加灵活，基于该能力有状态应用可以自动化的方式在 Kubernetes 集群间迁移。如下：

Story 1

Migrating across namespaces: 许多公司使用命名空间进行隔离，考虑到用户正在将 StatefulSet 迁移到集群中的新命名空间。迁移的原因可能是组织架构变动，也可能是要求迁出共享命名空间。如下，有 replicas：5 在共享命名空间中运行：

name: my-app
namespace: shared
replicas: 5
-----------------------------------------------
[ nginx-0, nginx-1, nginx-2, nginx-3, nginx-4 ]

为了迁移两个pod，可将共享命名空间中的 my-app StatefulSet 缩减为 replicas: 3, ordinals.start: 0，app-team命名空间中的 StatefulSet 可调整为为 replicas: 2, ordinals.start: 3 ，如下：

name: my-app						name: my-app
namespace: shared					namespace: app-team
replicas: 3						    replicas: 2
ordinals.start: 0				    ordinals.start: 3
------------------------------		---------------------
[ nginx-0, nginx-1, nginx-2 ]		[ nginx-3, nginx-4 ]

Story 2

Migrating across clusters: 由于容量限制、基础设施限制或为了更好地隔离应用程序，采用多集群的方式可能需要在集群间移动工作负载。

Story 3

Non-Zero Based Indexing: 用户可能希望从序号 “1” 而不是序号 “0” 开始对其 StatefulSet 进行编号。使用 “1” 的编号可能更容易推理和概念化（例如：序号 “k” 是第 “k” 个副本，而不是第 “k+1” 个副本）。

扩缩容功能

PersistentVolumeClaim 保留

FEATURE STATE: Kruise v1.1.0

如果你在安装或升级 Kruise 的时候启用了 StatefulSetAutoDeletePVC feature-gate，你可以使用 .spec.persistentVolumeClaimRetentionPolicy 字段来控制在StatefulSet生命周期中是否以及何时删除它所创建的PVC。

这个功能与上游 StatefulSet (K8s >= 1.23 [alpha]) 提供的相同，可以参考上游文档。

流式扩容

FEATURE STATE: Kruise v0.10.0

为了避免在一个新 Advanced StatefulSet 创建后有大量失败的 pod 被创建出来，从 Kruise v0.10.0 版本开始引入了在 scale strategy 中的 maxUnavailable 策略。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  replicas: 100
  scaleStrategy:
    maxUnavailable: 10% # percentage or absolute number

当这个字段被设置之后，Advanced StatefulSet 会保证创建 pod 之后不可用 pod 数量不超过这个限制值。

比如说，上面这个 StatefulSet 一开始只会一次性创建 10 个 pod。在此之后，每当一个 pod 变为 running、ready 状态后，才会再创建一个新 pod 出来。

注意，这个功能只允许在 podManagementPolicy 是 Parallel 的 StatefulSet 中使用。

序号保留（跳过）

从 Advanced StatefulSet 的 v1beta1 版本开始（Kruise >= v0.7.0），支持序号保留功能。

通过在 reserveOrdinals 字段中写入需要保留的序号，Advanced StatefulSet 会自动跳过创建这些序号的 Pod。如果 Pod 已经存在，则会被删除。注意，spec.replicas 是期望运行的 Pod 数量，spec.reserveOrdinals 是要跳过的序号。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  replicas: 4
  reserveOrdinals:
  - 1

对于一个 replicas=4, reserveOrdinals=[1] 的 Advanced StatefulSet，实际运行的 Pod 序号为 [0,2,3,4]。

如果要把 Pod-3 做迁移并保留序号，则把 3 追加到 reserveOrdinals 列表中。控制器会把 Pod-3 删除并创建 Pod-5（此时运行中 Pod 为 [0,2,4,5]）。
如果只想删除 Pod-3，则把 3 追加到 reserveOrdinals 列表并同时把 replicas 减一修改为 3。控制器会把 Pod-3 删除（此时运行中 Pod 为 [0,2,4]）。

保留序号范围

FEATURE STATE: Kruise v1.8.0

在实践中我们发现会有一些大规模序号保留的场景会导致保留的序号会越来越多，因此 Kruise v1.8.0 增加了保留序号范围功能，允许用户指定序号范围进行保留。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  replicas: 4
  reserveOrdinals:
  - "2-5" # <- 代表保留从2到5的序号
  - 7

核心规则

语法格式：使用 start-end 格式表示闭区间范围，例如 2-5 表示保留序号 2、3、4、5
范围闭合性：起始值和结束值均包含在保留范围内
组合使用：可同时指定单个序号和范围
无效范围处理：
- 若 start > end（如 5-2），该范围会导致配置校验失败
- 非数字字符（如 a-b）会导致配置校验失败

指定 Pod 删除

FEATURE STATE: Kruise v1.5.5, Kruise v1.6.4, Kruise v1.7.2+

相比于手动直接删除 Pod，使用 apps.kruise.io/specified-delete: true 指定 Pod 删除方式会有 Advanced StatefulSet 的 maxUnavailable 来保护删除，并且会触发 PreparingDelete 生命周期 hook （见下文）。

apiVersion: v1
kind: Pod
metadata:
  labels:
    # ...
    apps.kruise.io/specified-delete: true
spec:
  containers:
  - name: main
  # ...

当控制器收到上面这个 Pod 更新之后，会优先处理存在指定删除标签的 pod 的删除流程，并保证不突破 maxUnavailable 的限制。

升级功能

原地升级

Advanced StatefulSet 增加了 podUpdatePolicy 来允许用户指定重建升级还是原地升级。

ReCreate: 控制器会删除旧 Pod 和它的 PVC，然后用新版本重新创建出来。
InPlaceIfPossible: 控制器会优先尝试原地升级 Pod，如果不行再采用重建升级。具体参考下方阅读文档。
InPlaceOnly: 控制器只允许采用原地升级。因此，用户只能修改上一条中的限制字段，如果尝试修改其他字段会被 Kruise 拒绝。

请阅读该文档了解更多原地升级的细节。

我们还在原地升级中提供了 graceful period 选项，作为优雅原地升级的策略。用户如果配置了 gracePeriodSeconds 这个字段，控制器在原地升级的过程中会先把 Pod status 改为 not-ready，然后等一段时间（gracePeriodSeconds），最后再去修改 Pod spec 中的镜像版本。这样，就为 endpoints-controller 这些控制器留出了充足的时间来将 Pod 从 endpoints 端点列表中去除。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  podManagementPolicy: Parallel
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      podUpdatePolicy: InPlaceIfPossible
      inPlaceUpdateStrategy:
        gracePeriodSeconds: 10

更重要的是，如果使用 InPlaceIfPossible 或 InPlaceOnly 策略，必须要增加一个 InPlaceUpdateReady readinessGate，用来在原地升级的时候控制器将 Pod 设置为 NotReady。

一个完整的原地升级 StatefulSet 例子如下：

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
metadata:
  name: sample
spec:
  replicas: 3
  serviceName: fake-service
  selector:
    matchLabels:
      app: sample
  template:
    metadata:
      labels:
        app: sample
    spec:
      readinessGates:
      # A new condition that ensures the pod remains at NotReady state while the in-place update is happening
      - conditionType: InPlaceUpdateReady
      containers:
      - name: main
        image: nginx:alpine
  podManagementPolicy: Parallel # allow parallel updates, works together with maxUnavailable
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      # Do in-place update if possible, currently only image update is supported for in-place update
      podUpdatePolicy: InPlaceIfPossible
      # Allow parallel updates with max number of unavailable instances equals to 2
      maxUnavailable: 2

原地升级支持修改资源

FEATURE STATE: Kruise v1.8.0

如果你在安装或升级 Kruise 的时候启用了 InPlaceWorkloadVerticalScaling， Advanced StatefulSet 支持在原地升级过程中修改容器资源（CPU/Memory）。该功能允许用户直接更新以下字段而不触发 Pod 重建：

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  #...
  template:
    spec:
      containers:
      - name: <container-name>
        resources:
          requests:
            cpu: "2"       # 可修改
            memory: "2Gi"  # 可修改
          limits:
            cpu: "4"       # 可修改
            memory: "4Gi"  # 可修改

注意事项

该功能需在开启 InPlacePodVerticalScaling feature-gate 的 Kubernetes 集群中才可以使用，请确保你的集群支持该功能。详情可查看Kubernetes 文档。
Cgroupv1 限制：
- 在 Cgroupv1 环境中，禁止同时修改镜像和资源字段（如同时更新镜像和 CPU 配额）。需分步操作：
  1. 先完成资源修改的原地升级
  2. 再触发镜像更新的原地升级
- 详细说明参考社区 Issue #127356
资源类型限制：
- 仅支持修改 requests 和 limits 中的 cpu/memory 字段
- 其他资源类型（如 GPU）会触发 Pod 重建
- 修改资源时不能改变 Pod Qos，若 Pod Qos 改变会触发 Pod 重建

原地升级自动预热

FEATURE STATE: Kruise v0.10.0

如果你在安装或升级 Kruise 的时候启用了 PreDownloadImageForInPlaceUpdate feature-gate， Advanced StatefulSet 控制器会自动在所有旧版本 pod 所在 node 节点上预热你正在灰度发布的新版本镜像。这对于应用发布加速很有帮助。

默认情况下 Advanced StatefulSet 每个新镜像预热时的并发度都是 1，也就是一个个节点拉镜像。如果需要调整，你可以通过 apps.kruise.io/image-predownload-parallelism annotation 来设置并发度。

另外从 Kruise v1.1.0 开始，你可以使用 apps.kruise.io/image-predownload-min-updated-ready-pods 来控制在少量新版本 Pod 已经升级成功之后再执行镜像预热。它的值可能是绝对值数字或是百分比。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
metadata:
  annotations:
    apps.kruise.io/image-predownload-parallelism: "10"
    apps.kruise.io/image-predownload-min-updated-ready-pods: "3"

注意，为了避免大部分不必要的镜像拉取，目前只针对 replicas > 3 的 Advanced StatefulSet 做自动预热。

Partition 分批灰度

此设置用法与原生 StatefulSet 的 Partition 一致，详情可查看：kubernetes partition.

核心语义变更

Kruise 在 1.8.0 版本前，Partition 的定义遵循原生 StatefulSet 的逻辑：

旧版语义：仅更新序号 order >= partition 的 Pod

随着序号保留（reserveOrdinals）和起始序号（startOrdinal）功能的引入，我们重构了 Partition 的语义为：

新版语义：保留旧版本 Pod 的数量等于 Partition 值
即：控制器将更新优先级策略排序后的前 replicas - partition 个 Pod 到新版本

升级顺序

Advanced StatefulSet 在 spec.updateStrategy.rollingUpdate 下面新增了 unorderedUpdate 结构，提供给不按 order 顺序的升级策略。如果 unorderedUpdate 不为空，所有 Pod 的发布顺序就不一定会按照 order 顺序了。注意，unorderedUpdate 只能配合 Parallel podManagementPolicy 使用。

目前，unorderedUpdate 下面只包含 priorityStrategy 一个优先级策略。

优先级策略

这个策略定义了控制器计算 Pod 发布优先级的规则，所有需要更新的 Pod 都会通过这个优先级规则计算后排序。目前 priority 可以通过 weight(权重) 和 order(序号) 两种方式来指定。

weight: Pod 优先级是由所有 weights 列表中的 term 来计算 match selector 得出。如下：

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  updateStrategy:
    rollingUpdate:
      unorderedUpdate:
        priorityStrategy:
          weightPriority:
          - weight: 50
            matchSelector:
              matchLabels:
                test-key: foo
          - weight: 30
            matchSelector:
              matchLabels:
                test-key: bar

order: Pod 优先级是由 orderKey 的 value 决定，这里要求对应的 value 的结尾能解析为 int 值。比如 value "5" 的优先级是 5，value "sts-10" 的优先级是 10。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  updateStrategy:
    rollingUpdate:
      unorderedUpdate:
        priorityStrategy:
          orderPriority:
          - orderedKey: some-label-key

MaxUnavailable 最大不可用

Advanced StatefulSet 在 RollingUpdateStatefulSetStrategy 中新增了 maxUnavailable 策略来支持并行 Pod 发布，它会保证发布过程中最多有多少个 Pod 处于不可用状态。注意，maxUnavailable 只能配合 podManagementPolicy 为 Parallel 来使用。

这个策略的效果和 Deployment 中的类似，但是可能会导致发布过程中的 order 顺序不能严格保证。如果不配置 maxUnavailable，它的默认值为 1，也就是和原生 StatefulSet 一样只能 one by one 串行发布 Pod，即使把 podManagementPolicy 配置为 Parallel 也是这样。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  podManagementPolicy: Parallel
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 20%

比如说，一个 Advanced StatefulSet 下面有 P0 到 P4 五个 Pod，并且应用能容忍 3 个副本不可用。当我们把 StatefulSet 里的 Pod 升级版本的时候，可以通过以下步骤来做：

设置 maxUnavailable=3
(可选) 如果需要灰度升级，设置 partition=4。Partition 默认的意思是 order 大于等于这个数值的 Pod 才会更新，在这里就只会更新 P4，即使我们设置了 maxUnavailable=3。
在 P4 升级完成后，把 partition 调整为 0。此时，控制器会同时升级 P1、P2、P3 三个 Pod。注意，如果是原生 StatefulSet，只能串行升级 P3、P2、P1。
一旦这三个 Pod 中有一个升级完成了，控制器会立即开始升级 P0。

发布暂停

用户可以通过设置 paused 为 true 暂停发布，不过控制器还是会做 replicas 数量管理：

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  updateStrategy:
    rollingUpdate:
      paused: true

PersistentVolumeClaim 更新策略

FEATURE STATE: Kruise v1.8.0

在 Kruise v1.8.0 之前，对 .spec.volumeClaimTemplates 的更新仅会影响新创建的 PVC，而不会作用于已存在的 PVC。这种行为限制了对存量 PVC 的动态调整能力。

Kruise v1.8.0 之后，如果你在安装或升级 Kruise 的时候启用了 StatefulSetAutoResizePVCGate feature-gate，你可以使用 .spec.volumeClaimUpdateStrategy 字段来控制 PVC 的更新策略。

apiVersion: apps.kruise.io/v1beta1
kind: StatefulSet
spec:
  # ...
  volumeClaimUpdateStrategy:
    # 可选值有 OnPodRollingUpdate 和 OnDelete
    #   OnPodRollingUpdate ：controller 会在 pod 升级过程中自动扩容 pvc
    #   OnDelete ：controller 只会在 pvc 删除后使用新的 volume claim template 重建 pvc
    #             即 kruise 1.7 版本之前默认的 pvc 更新策略。
    type: OnPodRollingUpdate 

校验规则（OnPodRollingUpdate 模式）

当启用 OnPodRollingUpdate 时，Kruise Webhook 会对.spec.volumeClaimTemplates 变更进行强制校验：

不可修改 .spec.volumeClaimTemplates 的 PVC 数量
只允许对支持扩展的 StorageClass 进行 PVC 容量扩容
允许缩小对应卷模版的 .spec.resources.requests.storage 字段值，但不会对现有 PVC 执行实际缩容操作（仅更新模板配置）

注意事项

StorageClass 需支持动态扩展才能生效 PVC 扩容操作
修改 PVC 模板前请确保集群已启用 StatefulSetAutoResizePVCGate FeatureGate
OnDelete 策略下需手动删除 PVC 才能触发新模板 PVC 的应用

生命周期钩子

FEATURE STATE: Kruise v0.8.0

与 CloneSet 提供的生命周期钩子能力相似。

Pod 标识​

序号索引​

起始序号​

User Stories​

Story 1​

Story 2​

Story 3​

扩缩容功能​

PersistentVolumeClaim 保留​

流式扩容​

序号保留（跳过）​

保留序号范围​

核心规则​

指定 Pod 删除​

升级功能​

原地升级​

原地升级支持修改资源​

注意事项​

原地升级自动预热​

Partition 分批灰度​

核心语义变更​

升级顺序​

优先级策略​

MaxUnavailable 最大不可用​

发布暂停​

PersistentVolumeClaim 更新策略​

校验规则（OnPodRollingUpdate 模式）​

注意事项​

生命周期钩子​

Pod 标识

序号索引

起始序号

User Stories

Story 1

Story 2

Story 3

扩缩容功能

PersistentVolumeClaim 保留

流式扩容

序号保留（跳过）

保留序号范围

核心规则

指定 Pod 删除

升级功能

原地升级

原地升级支持修改资源

注意事项

原地升级自动预热

Partition 分批灰度

核心语义变更

升级顺序

优先级策略

MaxUnavailable 最大不可用

发布暂停

PersistentVolumeClaim 更新策略

校验规则（OnPodRollingUpdate 模式）

注意事项

生命周期钩子