Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add more doc about end to end canary update #193

Merged
merged 1 commit into from
Jul 3, 2024
+211 −17
Merged

add more doc about end to end canary update #193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
8 changes: 3 additions & 5 deletions i18n/zh/docusaurus-plugin-content-docs-rollouts/current/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down Expand Up @@ -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 |
Expand All @@ -51,4 +49,4 @@ Kruise Rollouts 与 [Argo Rollout](https://argoproj.github.io/rollouts/) 和 [Fl

以下是一些推荐的下一步操作：

- **[安装](./installation.md)** Kruise Rollout。
- **[安装](./installation.md)** Kruise Rollout
114 changes: 107 additions & 7 deletions ...usaurus-plugin-content-docs-rollouts/current/user-manuals/api-specifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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（必填）

Expand All @@ -214,6 +297,7 @@ metadata:
spec:
strategy:
canary:
enableExtraWorkloadForCanary: true
steps:
# the first step
- traffic: 5%
Expand All @@ -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">

Expand All @@ -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。
Expand Down Expand Up @@ -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"都表示当前步骤就绪。 |
2 changes: 1 addition & 1 deletion ...lugin-content-docs-rollouts/current/user-manuals/strategy-multi-batch-update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 多批次发布

## 多批次策略流程

分批发布是一种特殊的金丝雀发布，这种金丝雀发布不需要创建额外的工作负载。分批发布一般用于远大于1个实例的应用发布中，并且通常不用流量调度配合灰度。
<center><img src={require('/static/img/rollouts/multi-batch.jpg').default} width="90%" /></center>

## 推荐配置
Expand Down
2 changes: 1 addition & 1 deletion rollouts/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
95 changes: 94 additions & 1 deletion rollouts/user-manuals/api-specifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -237,6 +319,7 @@ metadata:
spec:
strategy:
canary:
enableExtraWorkloadForCanary: true
steps:
# the first step
- traffic: 5%
Expand All @@ -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">
Expand All @@ -289,6 +378,9 @@ spec:
# the second step
- weight: 10
... ....
patchPodTemplateMetadata:
labels:
opensergo.io/canary-gray: gray
```

| Fields | Type | Defaults | Explanation |
Expand All @@ -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)
Expand Down