update more docs about end to end canary update (#193)

Signed-off-by: 守辰 <shouchen.zz@alibaba-inc.com>
openkruise · Jul 3, 2024 · 48bd3b9 · 48bd3b9
1 parent d82c427
commit 48bd3b9
Show file tree

Hide file tree

Showing 8 changed files with 211 additions and 17 deletions.
diff --git a/i18n/zh/docusaurus-plugin-content-docs-rollouts/current/introduction.md b/i18n/zh/docusaurus-plugin-content-docs-rollouts/current/introduction.md
@@ -3,9 +3,7 @@
 ## 什么是 Kruise Rollouts？
 
 Kruise Rollouts 是一个 **Bypass(旁路)** 组件，提供 **高级渐进式交付功能**
-。它的支持可以帮助您实现对应用程序的更平稳和受控的更改部署，支持金丝雀、多批次和A/B测试交付模式，同时它兼容 Gateway API 和各种
-Ingress 实现，使其更容易集成到您的现有基础设施中。总的来说，对于希望优化其部署流程的 Kubernetes 用户来说，Kruise Rollouts
-是一个有价值的工具！
+。它的支持可以帮助您实现对应用程序的更平稳和受控的更改部署，支持金丝雀、多批次和A/B测试交付模式，同时它兼容 Gateway API 和各种Ingress 实现，使其更容易集成到您的现有基础设施中。总的来说，对于希望优化其部署流程的 Kubernetes 用户来说，Kruise Rollouts是一个有价值的工具！
 
 <center><img src={require('/static/img/rollouts/intro.png').default} width="90%" /></center>
 
@@ -41,7 +39,7 @@ Kruise Rollouts 与 [Argo Rollout](https://argoproj.github.io/rollouts/) 和 [Fl
 | 核心概念    | 增强现有的工作负载                                                               | 替换您的工作负载                                 | 管理您的工作负载                                 |
 | 架构      | Bypass                                                                  | 新的工作负载类型                                 | Bypass                                   |
 | 插拔和热切换  | 是                                                                       | 否                                        | 否                                        |
-| 发布类型    | 多批次、金丝雀、A/B测试                                                           | 多批次、金丝雀、蓝绿、A/B测试                         | 金丝雀、蓝绿、A/B测试                             |
+| 发布类型    | 多批次、金丝雀、A/B测试、全链路灰度                                                           | 多批次、金丝雀、蓝绿、A/B测试                         | 金丝雀、蓝绿、A/B测试                             |
 | 工作负载类型  | Deployment、StatefulSet、CloneSet、Advanced StatefulSet、Advanced DaemonSet | Agro-Rollout                             | Deployment、DaemonSet                     | 
 | 流量类型    | Ingress、GatewayAPI、CRD（需要 Lua 脚本）                                       | Ingress、GatewayAPI、APISIX、Traefik、SMI 等等 | Ingress、GatewayAPI、APISIX、Traefik、SMI 等等 |
 | 迁移成本    | 无需迁移工作负载和Pods                                                           | 必须迁移工作负载和Pods                            | 必须迁移Pods                                 | 
@@ -51,4 +49,4 @@ Kruise Rollouts 与 [Argo Rollout](https://argoproj.github.io/rollouts/) 和 [Fl
 
 以下是一些推荐的下一步操作：
 
-- **[安装](./installation.md)** Kruise Rollout。
+- **[安装](./installation.md)** Kruise Rollout
diff --git a/...usaurus-plugin-content-docs-rollouts/current/user-manuals/api-specifications.md b/...usaurus-plugin-content-docs-rollouts/current/user-manuals/api-specifications.md
@@ -197,7 +197,90 @@ spec:
 | `ingress.name`          | 字符串 | ""      | 绑定服务的Ingress资源的名称                                                                             |
 | `gateway.httpRouteName` | 字符串 | ""      | Gateway API的[HTTPRoute](https://gateway-api.sigs.k8s.io/concepts/api-overview/#httproute)资源名称 |
 注意：
-- 如果决定使用`trafficRoutings`，则`ingress`、`gateway`和`customNetworkRefs`不能同时为nil，且`ingress`、`gateway`和`customNetworkRefs` 不能同时配置在一个trafficRouting中
+- 如果决定使用`trafficRoutings`，则`ingress`、`gateway`和`customNetworkRefs`不能同时为nil，且`ingress`、`gateway`和`customNetworkRefs` 不能同时配置在一个trafficRouting中。 
+
+除了使用`trafficRoutings`，也可以通过单独声明流量路由策略，并在Rollout配置中引用声明的流量路由配置。通常，在全链路灰度中会使用这种流量路由配置方式。 
+
+如下是一个独立声明流量路由策略的例子：
+
+```yaml
+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
+  strategy:
+    matches:
+    - headers:
+      - type: Exact
+        name: User-Agent
+        value: Andriod
+    requestHeaderModifier:
+      set:
+      - name: x-mse-tag
+        value: gray
+```
+这里是在Rollout对象中引用流量路由策略的例子：
+
+<Tabs>
+  <TabItem value="v1beta1" label="v1beta1" default>
+
+```yaml
+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
+```
+  </TabItem>
+  <TabItem value="v1alpha1" label="v1alpha1">
+
+```yaml
+apiVersion: rollouts.kruise.io/v1alpha1
+kind: Rollout
+metadata:
+  name: rollout-b
+  annotations:
+    # 引用名为mse-traffic的流量路由配置
+    rollouts.kruise.io/trafficrouting: mse-traffic
+spec:
+  objectRef:
+    workloadRef:
+      apiVersion: apps/v1
+      kind: Deployment
+      name: spring-cloud-b
+  strategy:
+    canary:
+      steps:
+        - pause: {}
+          replicas: 1
+      patchPodTemplateMetadata:
+        labels:
+          opensergo.io/canary-gray: gray
+```
+  </TabItem>
+</Tabs>
+
 
 ### 策略API（必填）
 
@@ -214,6 +297,7 @@ metadata:
 spec:
   strategy:
     canary:
+      enableExtraWorkloadForCanary: true
       steps:
       # the first step
       - traffic: 5%
@@ -228,8 +312,24 @@ spec:
       # 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      |  为金丝雀发布创建一个额外的工作负载， 金丝雀发布后会被删除  |
+
   </TabItem>
   <TabItem value="v1alpha1" label="v1alpha1">
 
@@ -254,25 +354,25 @@ spec:
               value: matched-header-value # value or reg-expression
         # the second step
       - weight: 10
+      patchPodTemplateMetadata:
+        labels:
+          opensergo.io/canary-gray: gray
           ... ....
 ```
 
-</TabItem>
-</Tabs>
 
 | 字段                        | 类型       | 默认值     | 说明                                             |
 |---------------------------|----------|---------|------------------------------------------------|
 | `steps[x].weight`         | *整数      | nil     | （可选）金丝雀流量新版本Pod的百分比权重。                         |
-| `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      |  为金丝雀发布创建一个额外的工作负载， 金丝雀发布后会被删除  |
-
+</TabItem>
+</Tabs>
 注意：
 
 - `steps[x].replicas`不能为nil。
@@ -320,4 +420,4 @@ status:
 | `canaryStatus.stableRevision`      | 字符串 | 只读    | 进展之前记录的工作负载稳定（旧版本）的修订哈希值。                                             |
 | `canaryStatus.observedRolloutID`   | 字符串 | 只读    | 对应于工作负载的`rollouts.kruise.io/rollout-id`注释。如果它们相等，意味着卷出控制器观察到了工作负载的更改。 |
 | `canaryStatus.currentStepIndex`    | 整数  | 只读    | 卷出当前步骤索引。从1开始。                                                        |
-| `canaryStatus.currentStepState`    | 字符串 | 只读和写入 | 卷出当前步骤状态。"StepReady"和"Complete"都表示当前步骤就绪。                             |
+| `canaryStatus.currentStepState`    | 字符串 | 只读和写入 | 卷出当前步骤状态。"StepReady"和"Complete"都表示当前步骤就绪。                             |
diff --git a/...lugin-content-docs-rollouts/current/user-manuals/strategy-multi-batch-update.md b/...lugin-content-docs-rollouts/current/user-manuals/strategy-multi-batch-update.md
@@ -1,7 +1,7 @@
 # 多批次发布
 
 ## 多批次策略流程
-
+分批发布是一种特殊的金丝雀发布，这种金丝雀发布不需要创建额外的工作负载。分批发布一般用于远大于1个实例的应用发布中，并且通常不用流量调度配合灰度。 
 <center><img src={require('/static/img/rollouts/multi-batch.jpg').default} width="90%" /></center>
 
 ## 推荐配置

diff --git a/rollouts/introduction.md b/rollouts/introduction.md
@@ -35,7 +35,7 @@ Kruise Rollouts vs. [Argo Rollout](https://argoproj.github.io/rollouts/) and [Fl
 | Core Concept                | Enhance your existing workloads                                         | Replace your workloads                             | manage your workloads                              |
 | Architecture                | Bypass                                                                  | A new workload type                                | Bypass                                             |
 | Plug and Play, Hot-Swapping | Yes                                                                     | No                                                 | No                                                 |
-| Release Type                | Multi-Batch, Canary, A/B Testing                                        | Multi-Batch, Canary, Blue-Green, A/B Testing       | Canary, Blue-Green, A/B Testing                    |
+| Release Type                | Multi-Batch, Canary, A/B Testing, End-to-End Canary                     | Multi-Batch, Canary, Blue-Green, A/B Testing       | Canary, Blue-Green, A/B Testing                    |
 | Workload Type               | Deployment,StatefulSet,CloneSet,Advanced StatefulSet,Advanced DaemonSet | Agro-Rollout                                       | Deployment. DaemonSet                              | 
 | Traffic Type                | Ingress, GatewayAPI, CRD (Need Lua Script)                              | Ingress, GatewayAPI, APISIX, Traefik, SMI and more | Ingress, GatewayAPI, APISIX, Traefik, SMI and more |
 | Migration Costs             | No need migrate your workloads and pods                                 | Must migrate your workloads and pods               | Must migrate your pods                             | 

diff --git a/rollouts/user-manuals/api-specifications.md b/rollouts/user-manuals/api-specifications.md
@@ -223,6 +223,88 @@ spec:
 
 **Note: if you decide to use `trafficRoutings`, one and only one of `ingress`,`gateway`,`customNetworkRefs` can be present in one trafficRouting element*
 
+Alternatively, one can also define traffic routing strategy independently. and reference declared traffic routing config in the Rollout resource. Such usage is often used in the end-to-end canary cases.
+
+Here is an example of independent traffic routing definition:
+```yaml
+apiVersion: rollouts.kruise.io/v1alpha1
+kind: TrafficRouting
+metadata:
+  name: mse-traffic
+spec:
+  objectRef:
+  # config is the same as the traffic routing element in canary.trafficRoutings
+  - service: spring-cloud-a
+    ingress:
+      classType: mse
+      name: spring-cloud-a
+  strategy:
+    matches:
+    - headers:
+      - type: Exact
+        name: User-Agent
+        value: Andriod
+    requestHeaderModifier:
+      set:
+      - name: x-mse-tag
+        value: gray
+```
+
+Here is an example to reference the traffic routing in Rollout resource:
+
+<Tabs>
+  <TabItem value="v1beta1" label="v1beta1" default>
+
+```yaml
+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
+    # refer to the traffic routing config called mse-traffic
+    trafficRoutingRef: mse-traffic
+```
+  </TabItem>
+  <TabItem value="v1alpha1" label="v1alpha1">
+
+```yaml
+apiVersion: rollouts.kruise.io/v1alpha1
+kind: Rollout
+metadata:
+  name: rollout-b
+  annotations:
+    # refer to the mse-traffic traffic routing config
+    rollouts.kruise.io/trafficrouting: mse-traffic
+spec:
+  objectRef:
+    workloadRef:
+      apiVersion: apps/v1
+      kind: Deployment
+      name: spring-cloud-b
+  strategy:
+    canary:
+      steps:
+        - pause: {}
+          replicas: 1
+      patchPodTemplateMetadata:
+        labels:
+          opensergo.io/canary-gray: gray
+```
+  </TabItem>
+</Tabs>
+
 ### Strategy API (Mandatory)
 Describe your strategy of rollout:
 
@@ -237,6 +319,7 @@ metadata:
 spec:
   strategy:
     canary:
+      enableExtraWorkloadForCanary: true
       steps:
       # the first step
       - traffic: 5%
@@ -251,18 +334,24 @@ spec:
       # the second step
       - traffic: 10%
         ... ....
+      patchPodTemplateMetadata:
+        labels:
+          opensergo.io/canary-gray: gray
 ```
 
 | Fields                    | Type                | Defaults  | Explanation                                                                                                    |
 |---------------------------|---------------------|-----------|----------------------------------------------------------------------------------------------------------------|
+| `enableExtraWorkloadForCanary` | boolean          | false     | Whether to create extra workload for canary update,  the extra workload be deleted after rollout completions; if it is set to false, multi-batch update strategy will be used for workload | 
 | `steps[x].traffic`         | *string            | nil       | (optional) Percent weight of canary traffic for new-version Pods.                                              |
 | `steps[x].replicas`       | *integer or *string | nil       | Absolute number or Percent of new-version Pods.                                                                 |
 | `steps[x].pause`          | object              | {}        | (optional) Manual confirmation or auto confirmation before enter the next step.                                |
 | `steps[x].pause.duration` | *integer            | nil       | (optional) Duration time before auto confirmation. if nil, means need manual confirmation.                     |
 | `steps[x].matches`        | []object            | []        | (optional) The HTTP header match rules you want to traffic to new-version Pods.                                |
+| `steps[x].requestHeaderModifier`        | object            | []        | (optional)  overwrites the request with the given header (name, value)                             |
 | `headers[x].type`         | string              | "Exact"   | "Exact" or "RegularExpression" rule to match key and value                                                     |
 | `headers[x].name`         | string              | ""        | Matched HTTP header name. (And-Relationship between headers[i] and headers[j])                                  |
 | `headers[x].value`        | string              | ""        | Matched HTTP header value.                                                                                     |
+| `patchPodTemplateMetadata` | object    | nil       | (optional) Add extra pod meta data by patch podTemplate of the canary workload                                 |
 
   </TabItem>
   <TabItem value="v1alpha1" label="v1alpha1">
@@ -289,6 +378,9 @@ spec:
       # the second step
       - weight: 10
         ... ....
+      patchPodTemplateMetadata:
+        labels:
+          opensergo.io/canary-gray: gray
 ```
 
 | Fields                    | Type                | Defaults  | Explanation                                                                                                    |
@@ -301,14 +393,15 @@ spec:
 | `headers[x].type`         | string              | "Exact"   | "Exact" or "RegularExpression" rule to match key and value                                                     |
 | `headers[x].name`         | string              | ""        | Matched HTTP header name. (And-Relationship between headers[i] and headers[j])                                  |
 | `headers[x].value`        | string              | ""        | Matched HTTP header value.                                                                                     |
-| `enableExtraWorkloadForCanary` | boolean          | false     | Whether to create extra Deployment for canary update, if it is set to true, the extra Deployment will be deleted after rollout completions; if it is set to false, multi-batch update strategy will be used for Deployment | 
+| `patchPodTemplateMetadata` | object    | nil       | (optional) Add extra pod meta data by patch podTemplate of the canary workload                                 |
   </TabItem>
 </Tabs>
 
 Note:
 - `steps[x].replicas` can not be nil.
 - `steps[x].matches[i] and steps[x].matches[j]` have **Or**-relationship.
 - `steps[x].matches[y].headers[i] and steps[x].matches[y].header[j]` have **And**-relationship. 
+- `steps[x].patchPodTemplateMetadata` can be set only if enableExtraWorkloadForCanary=true
 - `enableExtraWorkloadForCanary` is available in v1beta Rollout resource; In v1alpha1 Rollout resource, one can use the annotation of Rollout `rollouts.kruise.io/rolling-type`="canary" to enable `enableExtraWorkloadForCanary`
 
 ### Special Annotations of Workload (Optional)