Skip to main content

API 规范

Kruise Rollouts 资源 YAML 的基本示例：

Note: v1beta1在Kruise Rollout v0.5.0 后可用

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  name: rollouts-demo
  # Rollout 资源需要与相应的工作负载在相同的命名空间中
  namespace: default
spec:
  # 发布工作负载的 Rollout，当前仅支持 Deployment、CloneSet、StatefulSet、Advanced StatefulSet、Advanced DaemonSet
  workloadRef:
    apiVersion: apps/v1
    kind: Deployment
    name: echoserver
  strategy:
    canary:
      ### 为金丝雀发布创建一个额外的工作负载， 金丝雀发布后会被删除 ###
      enableExtraWorkloadForCanary: true
      steps:
      ### 第一批h ###
      # 将 5% 的流量路由到新版本
      - traffic: 5%
        # 需要手动确认才能进入下一批
        pause: {}
        # 第一批发布的实例数量
        replicas: 1
      ### 第二批 ###
      - traffic: 50%
        replicas: 50%
        # 等待 2 小时后自动进入下一批
        pause:
          duration: 7200
      ### 第三批 ###
      - traffic: 100%
        replicas: 100%
      trafficRoutings:
      # 工作负载相关的service名
      - service: echoserver
        # 与服务相关的 Ingress 名称
        ingress:
          name: echoserver
        gracePeriodSeconds: 10

API 规范的主要部分包括 3 部分，您应该注意：

  • 绑定工作负载：告诉 Rollout 应该在哪个工作负载上工作。
  • 绑定流量配置：告诉 Rollout 应该关注哪个流量配置。
  • 在发布之前配置部署策略：告诉 Rollout 如何滚动您的工作负载和流量。

API 详细信息​

工作负载绑定 API（必填）​

告诉 Kruise Rollout 应该绑定哪个工作负载：

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  namespace: your-workload-ns
spec:
  workloadRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: your-workload-name
字段类型默认值说明
apiVersion字符串""工作负载的 API 版本
kind字符串""工作负载种类
name字符串""工作负载名称

目前，Kruise Rollout 支持 Deployment、CloneSet、StatefulSet、Advanced StatefulSet和Advanced DaemonSet。

注意：

  • 工作负载应该与 Rollout 在相同的命名空间中。

流量绑定 API（可选）​

与“工作负载绑定”不同，流量绑定是可选的。如果不设置以下规范，流量配置将保持其原始行为，例如，为所有版本的 Pod 保持负载均衡。

如果您需要为流量路由执行特殊操作，请告诉 Kruise Rollout 应该绑定哪些流量配置：

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  namespace: <your-workload-ns>
spec:
  strategy:
    canary:
      trafficRoutings:
      - service: <service-name-that-is-related-your-workload>
        ingress:
          classType: <traffic-type> # 例如：nginx | higress，默认为 "nginx"
          name: <ingress-name-that-is-related-the-service>
        gracePeriodSeconds: 10
      - service: <service-name-that-is-related-your-workload>
        gateway: # 或者选择使用 Ingress 或 GatewayAPI
          httpRouteName: <gateway-api-httpRoute-name>
        gracePeriodSeconds: 10
      - service: <service-name-that-is-related-your-workload>
        customNetworkRefs:
        - apiVersion: <your-resource-apiVersion>
          kind: <your-resource-kind>
          name: <your-resource-name>
        gracePeriodSeconds: 10
字段类型默认值说明
service字符串""选择绑定工作负载的服务名称
ingress对象nil（可选）您想要绑定的Ingress对象的描述
gateway对象nil（可选）您想要绑定的Gateway API资源的描述
customNetworkRefs对象数组nil（可选）您想要绑定的[自定义网关资源]((https://openkruise.io/rollouts/developer-manuals/custom-network-provider)的描述
ingress.classType字符串"nginx"Ingress类型，如"nginx"、"higress"或其他
ingress.name字符串""绑定服务的Ingress资源的名称
gateway.httpRouteName字符串""Gateway API的HTTPRoute资源名称
gracePeriodSeconds整数3在每个步骤中等待流量路由配置生效的时间（秒）

注意：

  • 如果决定使用trafficRoutings，则ingress、gateway和customNetworkRefs不能同时为nil，且ingress、gateway和customNetworkRefs 不能同时配置在一个trafficRouting中。

除了使用trafficRoutings，也可以通过单独声明流量路由策略，并在Rollout配置中引用声明的流量路由配置。通常，在全链路灰度中会使用这种流量路由配置方式。

如下是一个独立声明流量路由策略的例子：

apiVersion: rollouts.kruise.io/v1alpha1
kind: TrafficRouting
metadata:
  name: mse-traffic
spec:
  objectRef:
  # 这里的配置和Rollout对象中canary.trafficRoutings的配置一样
  - service: spring-cloud-a
    ingress:
      classType: mse
      name: spring-cloud-a
    gracePeriodSeconds: 10
  strategy:
    matches:
    - headers:
      - type: Exact
        name: User-Agent
        value: Andriod
    requestHeaderModifier:
      set:
      - name: x-mse-tag
        value: gray

这里是在Rollout对象中引用流量路由策略的例子：

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  name: rollout-b
spec:
  workloadRef:
    apiVersion: apps/v1
    kind: Deployment
    name: spring-cloud-b
  strategy:
    canary:
      steps:
        - pause: {}
          replicas: 1
      patchPodTemplateMetadata:
        labels:
          opensergo.io/canary-gray: gray
    # 引用名为mse-traffic的流量路由配置
    trafficRoutingRef: mse-traffic

策略API（必填）​

描述您的发布策略：

apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
  namespace: your-workload-ns
spec:
  strategy:
    canary:
      enableExtraWorkloadForCanary: true
      steps:
      # the first step
      - traffic: 5%
        replicas: 1 or 10%
        pause:
          duration: {}
        matches:
        - headers:
          - type: Exact # or "RegularExpression"
            name: matched-header-name
            value: matched-header-value # value or reg-expression
      # the second step
      - traffic: 10%
        ... ....
      patchPodTemplateMetadata:
        labels:
          opensergo.io/canary-gray: gray

字段类型默认值说明
steps[x].traffic*字符串nil（可选）可选）金丝雀流量新版本Pod的百分比权重。
steps[x].replicas整数或字符串nil（可选）新版本Pod的绝对数量或百分比。如果为nil，则默认使用'weight'作为副本数。
steps[x].pause对象{}（可选）进入下一步之前需要手动确认或自动确认。
steps[x].pause.duration*整数nil（可选）自动确认之前的持续时间。如果为nil，则表示需要手动确认。
steps[x].matches[]对象[]（可选）您想要将流量引导到新版本Pod的HTTP标头匹配规则。
headers[x].type字符串"Exact"匹配键和值的规则，可以是"Exact"或"RegularExpression"。
headers[x].name字符串""匹配的HTTP标头名称。（headers[i]和headers[j]之间的And关系）
headers[x].value字符串""匹配的HTTP标头值。
enableExtraWorkloadForCanary布尔值false为金丝雀发布创建一个额外的工作负载， 金丝雀发布后会被删除
注意：
  • steps[x].replicas不能为nil。
  • steps[x].matches[i]和steps[x].matches[j]之间具有或关系；
  • steps[x].matches[y].headers[i]和steps[x].matches[y].header[j]之间具有且关系。
  • enableExtraWorkloadForCanary 在v1beta1的Rollout对象中可用， 在v1alpha1版本的Rollout对象中， 可以用Rollout的特殊annotation rollouts.kruise.io/rolling-type` 来开启类似功能，rolling-type 如果设置为"canary"（默认值)， 则相当于设置enableExtraWorkloadForCanary=true; 如果设置为partition, 这相当于设置enableExtraWorkloadForCanar=false
  • patchPodTemplateMetadata只有在enableExtraWorkloadForCanary = true的情况下才会生效。

工作负载的特殊注释（可选）​

绑定工作负载中有一些特殊的注释，用于启用特定功能。

注释值默认值说明
rollouts.kruise.io/rollout-id任意字符串""这个概念类似于发布顺序号。用于解决用户是否观察到Kruise Rollout控制器当前工作负载更改的问题。

您应该了解的Rollout状态​

kind: Rollout
status:
  phase: Healthy
  observedGeneration: 2
  canaryStatus:
    canaryReplicas: 10
    canaryReadyReplicas: 10
    canaryRevision: 76fd76f75b
    currentStepIndex: 3
    currentStepState: Completed
    observedRolloutID: "20230313093823"
    observedWorkloadGeneration: 20
    podTemplateHash: 76fd76f75b
    stableRevision: b76b6f48f
字段类型模式说明
phase字符串只读"Initial" 表示没有绑定的工作负载；"Healthy" 表示绑定的工作负载已推进；"Progressing" 表示卷出正在进行中。
observedGeneration整数只读观察到的卷出规范的生成。
canaryStatus*对象只读有关卷出进展的信息。
canaryStatus.canaryReplicas整数只读工作负载更新的副本数。
canaryStatus.canaryReadyReplicas整数只读工作负载更新的就绪副本数。
canaryStatus.podTemplateHash字符串只读工作负载更新（新版本）的哈希值。
canaryStatus.canaryRevision字符串只读由Kruise Rollout控制器计算的工作负载更新（新版本）的修订哈希值。
canaryStatus.stableRevision字符串只读进展之前记录的工作负载稳定（旧版本）的修订哈希值。
canaryStatus.observedRolloutID字符串只读对应于工作负载的rollouts.kruise.io/rollout-id注释。如果它们相等，意味着卷出控制器观察到了工作负载的更改。
canaryStatus.currentStepIndex整数只读卷出当前步骤索引。从1开始。
canaryStatus.currentStepState字符串只读和写入卷出当前步骤状态。"StepReady"和"Complete"都表示当前步骤就绪。
Last updated on by PersistentJZH