## 1. Project Overview & Quickstart (higress-group/README_ZH)

# README_ZH

Open-source repository higress-group/README_ZH

### Repository Details
- **Repository:** [higress-group/README_ZH](https://github.com/higress-group/README_ZH)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (higress-group/higress-group.github.io)

## File: README.md

# Higress Official Website

Welcome to the official repository for the [Higress](https://higress.io) website and documentation. This project is built using [Astro](https://astro.build) and [Starlight](https://starlight.astro.build), featuring a modern, fast, and content-focused architecture.

## 🚀 Tech Stack

- **Framework**: [Astro](https://astro.build/) v5
- **Documentation Theme**: [Starlight](https://starlight.astro.build/)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/) v4
- **Language**: TypeScript

## 🛠 Getting Started

### Prerequisites

- Node.js (v18.17.1 or higher recommended)
- npm or yarn

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/higress-group/higress-group.github.io.git
   cd higress-group.github.io
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

### Development

Start the local development server:

```bash
npm run dev
```

The site will be available at `http://localhost:4321/`.

### Build

To build the production version of the site:

```bash
npm run build
```

This command runs necessary pre-build scripts (like fetching GitHub data) and generates the static site in the `dist/` directory.

### Preview

To preview the production build locally:

```bash
npm run preview
```

## 📂 Project Structure

```text
/
├── public/           # Static assets (images, robots.txt, etc.)
├── src/
│   ├── components/   # Reusable UI components (buttons, dropdowns, etc.)
│   ├── container/    # Section-level layout containers (e.g., Hero section)
│   ├── content/      # Markdown/MDX content (blog posts, documentation)
│   ├── layout/       # Page layouts
│   ├── pages/        # Astro pages and routes
│   └── styles/       # Global styles and Tailwind configuration
├── agent-doc/        # Development guidelines and conventions
├── astro.config.mjs  # Astro configuration
└── package.json      # Project dependencies and scripts
```

## 📝 Development Guidelines

Please refer to the documentation in the `agent-doc/` directory for detailed coding standards:

- [Component Conventions](./agent-doc/conventional-components.md): Guidelines for creating and structuring new components.
- [Commit Conventions](./agent-doc/conventional-commits.md): Standards for git commit messages.

## 🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request.

1. Fork the repository.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Commit your changes (`git commit -m 'feat: Add some AmazingFeature'`).
4. Push to the branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.

---

## File: docs/zh-cn/user/annotation.md

---
title: Ingress Annotaion 配置说明
keywords: Ingress
---

# Ingress Annotaion 配置说明
标准的K8s Ingress资源只能处理简单场景下的HTTP(S)流量路由，无法处理流量切分，超时重试，Header控制和跨域等问题。因此，不同的Ingress Controller利用自定义的Ingress Annotation增强Ingress能力。常见的Nginx Ingress Controller引入了100多个Annotation对Ingress在流量治理和安全防护上进行了扩展实现。目前，Higress已经全面兼容了大部分Nginx Ingress Annotation，方便用户从Nginx Ingress无缝迁移至Higress，本文主要介绍Higress关于Ingress Annotation的配置说明。

## Ingress Annotation

### 特殊说明
#### Annotation Key 前缀
以下出现的Nginx Ingress Annotation都已被Higress支持，您可以根据使用习惯继续使用Nginx Ingress的Annotation前缀`nginx.ingress.kubernetes.io`，或者使用Higress Ingress的Annotation前缀`higress.io`，两者是等价的。

#### 作用域说明
- Ingress：作用域为Ingress的Annotation的作用范围仅限当前Ingress上定义的路由规则。
- 域名：作用域为域名的Annotation，其作用范围为所有Ingress上出现的相同Host。
- 服务：作用域为服务的Annotation，其作用范围为所有Ingress上出现的相同Service。

### 流量治理
#### 灰度发布
| 注解                                                   | 作用域     | 支持度 | 说明                                     |
|------------------------------------------------------|---------|-----|----------------------------------------|
| nginx.ingress.kubernetes.io/canary                   | Ingress | 兼容  | 开启或关闭灰度发布                              |
| nginx.ingress.kubernetes.io/canary-by-header         | Ingress | 兼容  | 基于Request Header Key 流量切分              |
| nginx.ingress.kubernetes.io/canary-by-header-value   | Ingress | 兼容  | 基于Request Header Value 流量切分，Value为精确匹配 |
| nginx.ingress.kubernetes.io/canary-by-header-pattern | Ingress | 兼容  | 基于Request Header Value 流量切分，Value为正则匹配 |
| nginx.ingress.kubernetes.io/canary-by-cookie         | Ingress | 兼容  | 基于Request Cookie Key 流量切分              |
| nginx.ingress.kubernetes.io/canary-weight            | Ingress | 兼容  | 基于权重 流量切分                              |
| nginx.ingress.kubernetes.io/canary-weight-total      | Ingress | 兼容  | 权重总和                                   |

#### Fallback（容灾）
| 注解                                             | 作用域     | 支持度 | 说明                                                                                                                |
|------------------------------------------------|---------|-----|-------------------------------------------------------------------------------------------------------------------|
| nginx.ingress.kubernetes.io/default-backend    | Ingress | 兼容  | 容灾服务。当Ingress定义的服务没有可用节点时，请求会自动转发该容灾服务。                                                                           |
| nginx.ingress.kubernetes.io/custom-http-errors | Ingress | 兼容  | 该注解和`default-backend`一起工作。当后端服务返回指定HTTP响应码，原始请求会被再次转发至容灾服务。 > 注意：转发至容灾服务时，请求的Path会被重写为/，该行为与ingress-nginx保持一致 |

#### 重写
| 注解                                         | 作用域     | 支持度 | 说明                                        |
|--------------------------------------------|---------|-----|-------------------------------------------|
| nginx.ingress.kubernetes.io/rewrite-target | Ingress | 兼容  | 将Ingress定义的原path重写为指定目标，支持Group Capture.  |
| nginx.ingress.kubernetes.io/upstream-vhost | Ingress | 兼容  | 匹配Ingress定义的路由的请求在转发给后端服务时，修改头部host值为指定值。 |

#### 重定向
| 注解                                                  | 作用域     | 支持度 | 说明                            |
|-----------------------------------------------------|---------|-----|-------------------------------|
| nginx.ingress.kubernetes.io/ssl-redirect            | Ingress | 兼容  | HTTP 重定向为HTTPS                |
| nginx.ingress.kubernetes.io/force-ssl-redirect      | Ingress | 兼容  | HTTP 重定向为HTTPS                |
| nginx.ingress.kubernetes.io/permanent-redirect      | Ingress | 兼容  | 永久重定向                         |
| nginx.ingress.kubernetes.io/permanent-redirect-code | Ingress | 兼容  | 永久重定向状态码                      |
| nginx.ingress.kubernetes.io/temporal-redirect       | Ingress | 兼容  | 临时重定向                         |
| nginx.ingress.kubernetes.io/app-root                | Ingress | 兼容  | 修改应用根路径，对于访问/的请求将会被重定向为设置的新路径 |

#### 跨域
| 注解                                                 | 作用域     | 支持度 | 说明                     |
|----------------------------------------------------|---------|-----|------------------------|
| nginx.ingress.kubernetes.io/enable-cors            | Ingress | 兼容  | 开启或关闭跨域                |
| nginx.ingress.kubernetes.io/cors-allow-origin      | Ingress | 兼容  | 允许的第三方站点               |
| nginx.ingress.kubernetes.io/cors-allow-methods     | Ingress | 兼容  | 允许的请求方法，如GET、POST、PUT等 |
| nginx.ingress.kubernetes.io/cors-allow-headers     | Ingress | 兼容  | 允许的请求Header            |
| nginx.ingress.kubernetes.io/cors-expose-headers    | Ingress | 兼容  | 允许的暴露给浏览器的响应Header     |
| nginx.ingress.kubernetes.io/cors-allow-credentials | Ingress | 兼容  | 是否允许携带凭证信息             |
| nginx.ingress.kubernetes.io/cors-max-age           | Ingress | 兼容  | 预检结果的最大缓存时间            |

#### 重试
| 注解                                                      | 作用域     | 支持度 | 说明                                                                                                                                                                    |
|---------------------------------------------------------|---------|-----|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| nginx.ingress.kubernetes.io/proxy-next-upstream-tries   | Ingress | 兼容  | 请求的最大重试次数。默认3次。                                                                                                                                                       |
| nginx.ingress.kubernetes.io/proxy-next-upstream-timeout | Ingress | 兼容  | 请求重试的超时时间，单位秒。默认未配置超时时间。                                                                                                                                              |
| nginx.ingress.kubernetes.io/proxy-next-upstream         | Ingress | 兼容  | 请求重试条件，参考[http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) |


#### 后端服务使用的协议
| 注解                                           | 作用域 | 支持度              | 说明                                                |
|----------------------------------------------|-----|------------------|---------------------------------------------------|
| nginx.ingress.kubernetes.io/backend-protocol | 服务  | 部分兼容。不支持AJP和FCGI | 指定后端服务使用的协议，默认为HTTP，支持HTTP、HTTP2、HTTPS、GRPC和GRPCS |


#### 负载均衡
| 注解                                           | 作用域 | 支持度                        | 说明                                                                                                                                                                                                                                                                      |
|----------------------------------------------|-----|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| nginx.ingress.kubernetes.io/load-balance     | 服务  | 部分兼容。不支持`ewma`算法           | 后端服务的普通负载均衡算法。默认为round_robin。 合法值如下：- round_robin：基于轮询的负载均衡。- least_conn：基于最小请求数的负载均衡。- random：基于随机的负载均衡。 > 注意：Higress不支持ewma算法，若配置为ewma算法，会回退到round_robin算法。                                                                                       |
| nginx.ingress.kubernetes.io/upstream-hash-by | 服务  | 部分兼容。暂不支持Nginx变量、常量的组合使用方式 | 基于一致Hash的负载均衡算法，Higress支持以下几种形式：1. Higress支持配置部分nginx变量：- $request_uri：请求的Path（包括路径参数）作为Hash Key - $host：请求的Host作为Hash Key- $remote_addr：请求的客户端IP作为Hash Key。2. 基于请求header的一致性Hash。您只需配置为$http_headerName。3. 基于请求路径参数的一致性Hash。您只需配置为$arg_varName |


#### Cookie亲和性
| 注解                                                 | 作用  | 支持度                     | 说明                                               |
|----------------------------------------------------|-----|-------------------------|--------------------------------------------------|
| nginx.ingress.kubernetes.io/affinity               | 服务  | 兼容                      | 亲和性种类，目前只支持cookie，默认为cookie。                     |
| nginx.ingress.kubernetes.io/affinity-mode          | 服务  | 部分兼容。暂不支持`persistent`模式 | 亲和性模式，云原生网关目前只支持balanced模式，默认为balanced模式。        |
| nginx.ingress.kubernetes.io/session-cookie-name    | 服务  | 兼容                      | 配置指定Cookie的值作为Hash Key                           |
| nginx.ingress.kubernetes.io/session                |     |                         |                                                  |
| -cookie-path                                       | 服务  | 兼容                      | 当指定Cookie不存在，生成的Cookie的Path值，默认为/                |
| nginx.ingress.kubernetes.io/session-cookie-max-age | 服务  | 兼容                      | 当指定Cookie不存在，生成的Cookie的过期时间，单位为秒，默认为Session会话级别。 |
| nginx.ingress.kubernetes.io/session-cookie-expires | 服务  | 兼容                      | 当指定Cookie不存在，生成的Cookie的过期时间，单位为秒，默认为Session会话级别。 |


#### IP访问控制
| 注解                                                                                                                                                                  | 作用域     | 支持度 | 说明                                |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----|-----------------------------------|
| nginx.ingress.kubernetes.io/[whitelist-source-range](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#whitelist-source-range) | Ingress | 兼容  | 指定路由上的IP白名单，支持IP地址或CIDR地址块，以逗号分隔。 |

### 安全防护
#### 客户端与网关之前的通信加密
| 注解                                          | 作用域 | 支持度                                           | 说明                                                                                                                                                                                                                                                                                                                                                                                               |
|---------------------------------------------|-----|-----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| nginx.ingress.kubernetes.io/ssl-cipher      | 域名  | 兼容                                            | 指定tls的加密套件，可以指定多个，英文逗号分隔，仅当tls握手时采用TLSv1.0-1.2生效。默认加密套件如下：- ECDHE-ECDSA-AES128-GCM-SHA256- ECDHE-RSA-AES128-GCM-SHA256- ECDHE-ECDSA-AES128-SHA- ECDHE-RSA-AES128-SHA- AES128-GCM-SHA256- AES128-SHA- ECDHE-ECDSA-AES256-GCM-SHA384- ECDHE-RSA-AES256-GCM-SHA384- ECDHE-ECDSA-AES256-SHA- ECDHE-RSA-AES256-SHA- AES256-GCM-SHA384- AES256-SHA |
| nginx.ingress.kubernetes.io/auth-tls-secret | 域名  | 部分兼容。secret名字格式必须是：(该域名证书所在的secret的名字)-cacert | 网关使用的CA证书，用于验证MTLS握手期间，客户端提供的证书。该注解主要应用于网关需要验证客户端身份的场景。                                                                                                                                                                                                                                                                                                                                          |


#### 网关与后端服务之间通信加密
| 注解                                                | 作用域 | 支持度 | 说明                         |
|---------------------------------------------------|-----|-----|----------------------------|
| nginx.ingress.kubernetes.io/proxy-ssl-secret      | 服务  | 兼容  | 网关使用的客户端证书，用于后端服务对网关进行身份认证 |
| nginx.ingress.kubernetes.io/proxy-ssl-name        | 服务  | 兼容  | TLS握手期间使用的SNI              |
| nginx.ingress.kubernetes.io/proxy-ssl-server-name | 服务  | 兼容  | 开启或关闭TLS握手期间使用SNI          |

#### 安全认证
##### Basic
| 注解                                           | 作用域     | 支持度             | 说明                                                                                                |
|----------------------------------------------|---------|-----------------|---------------------------------------------------------------------------------------------------|
| nginx.ingress.kubernetes.io/auth-type        | Ingress | 部分兼容。暂只支持Basic。 | 认证类型                                                                                              |
| nginx.ingress.kubernetes.io/auth-secret      | Ingress | 兼容              | Secret名字，格式支持<namespace>/<name>，包含被授予能够访问该Ingress上定义的路由的访问权限的用户名和密码。                              |
| nginx.ingress.kubernetes.io/auth-secret-type | Ingress | 兼容              | Secret内容格式。- auth-file：data的key为auth；value为用户名和密码，多帐号回车分隔- auth-map：data的key为用户名；value为密码 |
| nginx.ingress.kubernetes.io/auth-realm       | Ingress | 兼容              | 保护域。相同的保护域共享用户名和密码。                                                                               |


## 备注
关于以上提到的Nginx Ingress Annotation的更多信息，请参阅官方文档（[https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#annotations](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#annotations)）。

---

## File: docs/zh-cn/user/configurations.md

---
title: Higress 参数配置
keywords: Higress
---

# Higress参数配置

TBD

---

## File: docs/zh-cn/user/dubbo.md

---
title: 实现 Dubbo 服务发现和路由
keywords: Dubbo,discovery
---

# 实现 Dubbo 服务发现和路由

Higress提供了从HTTP协议到Dubbo协议进行转换的功能，用户通过配置协议转换，可以将一个Dubbo服务以HTTP接口暴露出来，从而用HTTP请求实现对Dubbo接口的调用。本文将通过示例来介绍如何用Higress配置HTTP到Dubbo的协议转换。

## 前提条件
Higress目前支持的Dubbo框架的版本为2.x。若您使用Dubbo3.0，要求使用dubbo协议（目前暂不支持Triple协议）。

---

假设我们有如下一个Dubbo服务，并指定了该服务的version为“1.0.0”，group为“dev”，下面我们将介绍如何为该服务配置协议转换。

```java
package com.alibaba.nacos.example.dubbo.service;

public interface DemoService {
    String sayName(String name);
}
```

## 为Dubbo服务配置路由
### 方法一：通过Dubbo服务的Ip和port实现Dubbo服务发现和路由
1. 创建以下ServiceEntry资源，其中指定了Dubbo服务的Ip与端口号：
```yaml
apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: dubbo
  namespace: higress-system
spec:
  endpoints:
  # 此处更换为自己dubbo服务的ip
  - address: xxx.xxx.xxx.xxx
    ports:
      http: 20880
  hosts:
  - dubbo.static
  location: MESH_EXTERNAL
  ports:
  - name: http
    number: 20880
    protocol: HTTP
  resolution: STATIC
```
2. 创建以下VirtualService资源，为Dubbo服务创建一条名为test的路由
```yaml
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: global
  namespace: higress-system
spec:
  gateways:
  - higress-system/global
  hosts:
  - '*'
  http:
  - match:
    - ignoreUriCase: false
      uri:
        prefix: /dubbo
    name: test
    route:
    - destination:
        host: dubbo.static
        port:
          number: 20880
```
### 方法二：通过对接Nacos/Zookeeper注册中心实现Dubbo服务发现和路由
TBD
## 通过EnvoyFilter配置HTTP到Dubbo协议转换规则
在为Dubbo服务创建了路由之后，需要配置具体的协议转换规则。Higress通过Envoy的HTTP Filter实现从HTTP协议到Dubbo协议的转换，本示例通过创建如下EnvoyFilter资源来对协议转换规则进行配置。
```
/* Detailed source-code truncated for AI context efficiency. */
```
## 通过HTTP请求调用Dubbo服务
完成以上配置后，通过curl命令调用sayName方法进行验证：
```bash
curl "localhost/dubbo/hello?p=higress" 
{"result":"Service [name :demoService , port : 20880] sayName(\"higress\") : Hello,higress"}
```
## Filter配置参考
### HttpDubboTranscoder
| 字段                       | 类型                        | 说明                     | 值                                                                                                 |
| -------------------------- | --------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- |
| url_unescape_spec          | enum                        | URL unescaping policy    | 可选值： - ALL_CHARACTERS_EXCEPT_RESERVED- ALL_CHARACTERS_EXCEPT_SLASH- ALL_CHARACTERS |
| request_validation_options | RequestValidateOptions      | 请求验证选项             |                                                                                                    |
| services_mapping           | list of DubboServiceMapping | 每一项对应了一条映射规则 |                                                                                                    |
### HttpDubboTranscoder.RequestValidateOptions
| 字段                            | 类型 | 说明                                               |
| ------------------------------- | ---- | -------------------------------------------------- |
| reject_unknown_query_parameters | bool | 对于无法成功映射query parameters的请求是否直接拒绝 |
| reject_unknown_method           | bool | 对于无法映射为dubbo服务的请求是否直接拒绝          |
### HttpDubboTranscoder.DubboServiceMapping
| 字段           | 类型                       | 说明                                            | 值                                                          |
| -------------- | -------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| name           | string                     | dubbo服务名                                     | 例如："com.alibaba.nacos.example.dubbo.service.DemoService" |
| version        | string                     | dubbo服务的版本                                 | 例如："1.0.0"                                               |
| group          | string                     | dubbo服务的分组                                 | 例如："dev"                                                 |
| method_mapping | list of DubboMethodMapping | 每一项对应了指定dubbo服务中的某个方法的映射规则 |                                                             |
### HttpDubboTranscoder.DubboMethodMapping
| 字段                | 类型                    | 说明                       | 值            |
| ------------------- | ----------------------- | -------------------------- | ------------- |
| name                | string                  | 方法名                     | 例："sayName" |
| path_matcher        | PathMatcher             | 方法匹配规则               |               |
| parameter_mapping   | lis of ParameterMapping | 每一项对应一个参数映射规则 |               |
| passthrough_setting | PassthroughSetting      | 指定Header透传规则         |               |
### HttpDubboTranscoder.DubboMethodMapping.PathMatcher
| 字段                   | 类型   | 说明                                 | 值                                                                             |
| ---------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------ |
| match_pattern          | string | 方法的匹配路径｜例如："/dubbo/hello" |
| match_http_method_spec | enum   | 方法匹配的HTTP Method                | 可选值：-ALL_GET- ALL_POST- ALL_PUT- ALL_DELETE- ALL_PATCH |
### HttpDubboTranscoder.DubboMethodMapping.ParameterMapping
| 字段             | 类型   | 说明                    | 值                                                                            |
| ---------------- | ------ | ----------------------- | ----------------------------------------------------------------------------- |
| extract_key_spec | enum   | 参数提取位置            | 可选值：- ALL_QUERY_PARAMETER- ALL_HEADER- ALL_PATH- ALL_BODY |
| extract_key      | string | 参数提取的key           | 例：my_param                                                                  |
| mapping_type     | string | 参数在dubbo服务中的类型 | 例："java.lang.String"                                                        |
### HttpDubboTranscoder.DubboMethodMapping.PassthroughSetting
配置HTTP Header透传规则，被透传的Header会被放在Dubbo调用的attachment中传给dubbo服务

注：Header的透传规则，此项配置为one of类型，下面两个字段选其一
| 字段                    | 类型           | 说明                                          |
| ----------------------- | -------------- | --------------------------------------------- |
| passthrough_all_headers | bool           | 透传所有Header                                |
| passthrough_headers     | list of string | 透传指定Header，每一项指定了Header中的一个key |

---

## File: docs/zh-cn/user/kruise-rollout.md

---
title: 通过 OpenKruise Rollout 实现灰度发布
keywords: rollout,gray
---

# 通过 OpenKruise Rollout 实现灰度发布

在业务高速发展过程中，如何最大化保障功能迭代过程中业务流量无损一直是开发者比较关心的问题。通常在应用发布新功能阶段，我们会采用灰度发布的思想对新版本进行小流量验证，在符合预期之后再进行全量发布，这就是"渐进性交付"。该词最早起源于大型、复杂的工业化项目，它试图将复杂的项目进行分阶段拆解，通过持续进行小型闭环迭代降低交付成本和时间。随着云原生架构不断发展，渐进性交付被广泛应用在互联网业务应用中，开发者通过GitOps、CI/CD方式集成渐进式交付框架，让新功能交付以流水线的方式分批执行，利用A/B 测试、金丝雀发布等技术精细化控制每一批次的流量策略，充分保障应用发布的稳定性。

## 什么是Kruise Rollout
Kruise Rollout 是阿里云开源的云原生应用自动化管理套件 OpenKruise 在渐进式交付领域的新尝试，支持配合流量和实例灰度的金丝雀发布、蓝绿发布、A/B Testing 发布，以及发布过程能够基于 Prometheus Metrics 指标自动化分批与暂停，并提供旁路的无感对接、兼容已有的多种工作负载（Deployment、CloneSet、DaemonSet）。

这里，熟悉 Kubernetes 的小伙伴可以会疑惑，官方的 Deployment 工作负载不是有控制发布的策略吗？我们为什么还需要 Kruise Rollout 呢？

首先，Kubernetes 官方的 Deployment 中定义发布策略严格上不符合渐进性交付的思想，它实际是滚动发布。虽然 Deployment 对于升级而言提供了 maxUnavailable 和 maxSurge 两个参数，但是本质上来讲 Deployment 它只支持流式的一次性发布，用户并不能控制分批以及精细化的流量策略。比如用户无法严格控制新老版本之间的流量比例，只能根据实际 Pod 数量占比以及调用端的负载均衡策略；用户无法做 A/B testing 策略，例如限制公司内部员工可以访问新版本。当新版本出现问题，只能重新执行一遍滚动发布切回老版本，这样不仅回滚速度慢，而且频繁线上变更本身就具有极高的不稳定因素。

再者，Kubernetes 只提供了应用交付的 Deployment 控制器，以及针对流量的 Ingress、Service 抽象，但是如何将上述实现组合成开箱即用的渐进式交付方案，Kubernetes 并没有出标准的定义。

出于以上问题和考量，阿里云开始发起对渐进式领域的探索，结合多年来容器化、云原生的技术沉淀，推出了无侵入、可扩展、高易用的渐进式交付框架 Kruise Rollout。

## Higress & Kruise Rollout工作机制
简单介绍一下 Higress 和 Kruise Rollout 在一次应用发布过程中的工作机制。



这里，假设集群中有一个 Deployment 应用A，通过 Higress 网关对外暴露提供服务。应用A由于业务发展，需要发布新功能。
1. 用户首先在集群中添加渐进性交付策略（Rollout CRD资源），描述目标工作负载的交付策略，比如批次，每一批次的流量控制，以及关联的 Service 资源和 Ingress 资源。
2. 应用A发布新版本，用户修改集群上中目标Deployment的Pod模板中容器镜像为新版本。
3. Kruise Rollout通过hook方式参与到Deployment滚动发布流程，修改Deployment的Pause来暂停滚动发布过程。
4. 执行第一次批次发布，根据Rollout CRD资源描述的交付策略，控制新版本的Pod数量，同时为正式Ingress资源生成对应的灰度Ingress资源，并配置灰度流量策略，比如流量权重比或者根据请求内容Header进行流量分发。Higress监听到Ingress资源变化，实时动态修改路由规则，满足灰度规则的流量被分发到新版本。
5. 通过Prometheus等监控手段观察应用流量的指标信息，验证新版本是否符合预期。
  a. 如果符合预期，触发下一次批次发布，重复执行步骤4
  b. 如果不符合预期，触发回滚，新发布的Pod下线，灰度已下线的部分老版本的Pod，Ingress资源自动下线灰度规则，Higress实时修改路由规则，确保流量只访问老版本服务。

整个 Rollout 过程，自动整合Deployment、Service、Ingress一起工作，并向用户屏蔽底层资源变化。这是与现有工作负载能力的一种协同，它尽量复用工作负载的能力，又做到了非 Rollout 过程的零入侵。

## 实战
### 前提条件
1. 安装Higress，请参阅[安装部署](../ops/deploy-by-helm.md)
2. 安装Kruise Rollout
```
helm install kruise-rollout openkruise/kruise-rollout --version 0.3.0-rc.0
```
3. 安装kubectl-kruise命令行工具，请参阅[安装kubectl-kruise](https://github.com/openkruise/kruise-tools/blob/master/README.md)


### 金丝雀发布
#### 什么是金丝雀发布
金丝雀发布的思想是将少量的请求引流到新版本上，因此部署新版本服务只需极小数的机器。验证新版本符合预期后，逐步调整流量权重比例，使得流量慢慢从老版本迁移至新版本，期间可以根据设置的流量比例，对新版本服务进行扩容，同时对老版本服务进行缩容，使得底层资源得到最大化利用。

如图，某服务当前版本为v1，现在新版本v2要上线。为确保流量在服务升级过程中平稳无损，采用金丝雀发布方案，逐步将流量从老版本迁移至新版本。



#### 基于Higress & Kruise Rollout实践金丝雀发布
假设集群中有一个服务demo，通过Higress网关对外提供服务。
```
apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo
spec:
  replicas: 5
  selector:
    matchLabels:
      app: demo
  template:
    metadata:
      labels:
        app: demo
    spec:
      containers:
      - name: main
        image: registry.cn-hangzhou.aliyuncs.com/mse-ingress/version:v1
        imagePullPolicy: Always
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: demo
spec:
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: demo
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
  annotations:
    kubernetes.io/ingress.class: nginx
spec:
  rules:
  - http:
      paths:
      - backend:
          service:
            name: demo
            port:
              number: 80
        path: /version
        pathType: Exact
```

现在，服务demo需要发布新版本。在修改应用镜像之前，我们需要为服务demo定义金丝雀发布策略，以达到渐进式发布的效果。
```
apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  name: rollouts-demo
spec:
  objectRef:
    workloadRef:
      apiVersion: apps/v1
      kind: Deployment
      name: demo
  strategy:
    canary:
      steps:
      - weight: 10
        pause: {}
        replicas: 1
      - weight: 30
        pause: {}
        replicas: 2
      trafficRoutings:
      - service: demo
        type: nginx
        ingress:
          name: demo
```
- 其中workloadRef 旁路式的选择需要 Rollout 的 Workload，此处为Deployment，支持其他Workload（如CloneSet、DaemonSet）。
- 其中canary.Steps 定义了整个 Rollout 过程一共分为3批，其中第一批只灰度一个新版本 Pod，并且 routing 10% 流量到新版本 Pod，并且需要人工确认是否继续发布；第二批只灰度两个新版本Pod，并且routing 30%流量到新版本Pod，并且需要人工确认是否继续发布；最后一批，无需定义，即全量发布。
- 其中trafficRoutings指向了需要感知流量规则的资源，kruise rollout会自动更新相关资源，实时反射目标流量规则。


修改服务A的Deployment中镜像为`registry.cn-hangzhou.aliyuncs.com/mse-ingress/version:v2`，观察相关资源变化。


查看rollout资源状态，发现当前执行完第一批发布，并且出于暂停状态，需要人工确认才能继续下一批次发布。


查看pod状态，发现新版本pod只有一个，Deployment资源没有全部滚动发布。


查看Ingress的解析IP （即Higress网关对外的公网IP地址）。


测试流量，发现有10%流量访问新版本。


继续第二批次发布，查看当前Pod状态，发现新版本Pod有两个。


测试流量，观察流量分配比。


发布最后一批，完成全量发布。


测试流量，发现流量全部转发至新版本。至此，我们通过小流量的方式逐步将流量从老版本迁移至新版本。


### A/B Testing
#### 什么是A/B Testing
相比于基于权重方式的金丝雀发布，A/B测试基于用户请求的元信息将流量路由到新版本，这是一种基于请求内容匹配的灰度发布策略。只有匹配特定规则的请求才会被引流到新版本，常见的做法包括基于Http Header和Cookie。基于Http Header方式的例子，例如User-Agent的值为Android的请求 （来自安卓系统的请求）可以访问新版本，其他系统仍然访问旧版本。基于Cookie方式的例子，Cookie中通常包含具有业务语义的用户信息，例如普通用户可以访问新版本，VIP用户仍然访问旧版本。

如图，某服务当前版本为v1，现在新版本v2要上线。希望安卓用户可以尝鲜新功能，其他系统用户保持不变。


通过在监控平台观察旧版本与新版本的成功率、RT对比，当新版本整体服务预期后，即可将所有请求切换到新版本v2，最后为了节省资源，可以逐步下线到旧版本v1。


#### 基于Higress & Kruise Rollout实践A/B Testing
我们仍然利用上面的例子，服务A初始镜像为v1。现在，服务demo需要发布新版本。在修改应用镜像之前，我们需要为服务demo定义A/B Testing 策略，以达到渐进式发布的效果。
```
apiVersion: rollouts.kruise.io/v1alpha1
kind: Rollout
metadata:
  name: rollouts-header
spec:
  objectRef:
    workloadRef:
      apiVersion: apps/v1
      kind: Deployment
      name: demo
  strategy:
    canary:
      steps:
      - matches:
        - headers:
          - name: user-agent
            value: android
        pause: {}
        replicas: 1
      trafficRoutings:
      - service: demo
        ingress:
          classType: nginx
          name: demo
```
其中canary.Steps 定义了整个 Rollout 过程一共分为2批，其中第一批只灰度一个新版本 Pod，并且将带有HTTP Header user-agent: android (即安卓用户）的流量routing 到新版本 Pod，并且需要人工确认是否继续发布；最后一批，无需定义，即全量发布。


修改服务A的Deployment中镜像为`registry.cn-hangzhou.aliyuncs.com/mse-ingress/version:v2`，观察相关资源变化。


查看rollout资源状态，发现当前执行完第一批发布，并且出于暂停状态，需要人工确认才能继续下一批次发布。


查看pod状态，发现新版本pod只有一个，Deployment资源没有全部滚动发布。


测试来自安卓的流量是否路由到新版本，非安卓的流量是否路由到老版本。


发布最后一批，完成全量发布。并测试所有流量是否路由到新版本。


## 总结
相比于传统人工手动方式，Higress & Kruise Rollouts提供了无侵入、自动化运维方式让应用发布丝滑般顺畅。开发者无需关注发布过程中如何调整Deployment、Ingress、Service等资源，只需声明并管理发布策略Rollouts资源即可，原生Deployment的滚动发布会自动实现为渐进式交付，让应用发布可批次、可灰度、可回滚，助力业务快速迭代发展同时，也提高了应用发布的稳定性和效率问题。

---

## File: docs/zh-cn/user/mcp-bridge.md

---
title: Mcp Bridge 配置说明
keywords: discovery
---

# Mcp Bridge 配置说明

## McpBridge 字段说明
| 字段 | 类型 | 说明 | 示例值 | 是否必填 |
| --- | --- | --- | --- | --- |
| registries | RegistryConfig 数组 | 支持配置多个不同注册中心的服务来源 | [] | 否 |

## RegistryConfig 字段说明
| 字段 | 类型 | 说明 | 示例值 | 是否必填 |
| --- | --- | --- | --- | --- |
| type | 字符串 | 注册中心类型，可选项：nacos,nacos2,zookeeper,consul,eureka | nacos2 | 是 |
| name | 字符串 | 自定义的服务来源名称 | my-nacos | 是 |
| domain | 字符串 | 注册中心地址，可以是ip或域名 | 192.168.1.2 | 是 |
| port | 整数 | 注册中心访问端口 | 8848 | 是 |
| consulNamespace | 字符串 | 使用consul时需要填写命名空间 | my-consul-namespace | 否 |
| zkServicesPath | 字符串数组 | 使用zk时,填写服务注册的根路径,默认监听 /dubbo 和 /services，前者为dubbo 服务默认根路径，后者为SpringCloud服务默认根路径 | ["/service-provider"] | 否 |
| nacosNamespaceId | 字符串 | nacos命名空间id | d8ac64f3-xxxx-xxxx-xxxx-47a814ecf358 | 否 |
| nacosGroups | 字符串数组 | nacos服务分组列表 | ["DEFAULT_GROUP"] | 否 |
| nacosAccessKey | 字符串 | nacos需要认证时填写的ak信息 | xxxx | 否 |
| nacosSecretKey | 字符串 | nacos需要认证时填写的sk信息 | xxxx | 否 |

---

## File: docs/zh-cn/user/nacos-route.md

---
title: 配置 Ingress 转发给注册在 Nacos 的服务
keywords: ingress,higress nacos
---

# 配置 Ingress 转发给注册在 Nacos 的服务


## 配置服务来源

```yaml
apiVersion: networking.higress.io/v1
kind: McpBridge
metadata:
  name: default
  namespace: higress-system
spec:
  registries:
    # 定义一个名为 “production” 的服务来源
  - name: production
    # 注册中心类型是 Nacos 2.x，支持 gRPC 协议
    type: nacos2
    # 注册中心的访问地址，可以是域名或者IP
    domain: 192.xxx.xx.32
    # 注册中心的访问端口，Nacos 默认都是 8848
    port: 8848
    # Nacos 命名空间 ID
    nacosNamespaceId: d8ac64f3-xxxx-xxxx-xxxx-47a814ecf358
    # Nacos 服务分组
    nacosGroups:
    - DEFAULT_GROUP
    # 定义一个名为 “uat” 的服务来源
  - name: uat
    # 注册中心类型是 Nacos 1.x，只支持 HTTP 协议
    type: nacos
    # 注册中心的访问地址，可以是域名或者IP
    domain: 192.xxx.xx.31
    # 注册中心的访问端口，Nacos 默认都是 8848
    port: 8848
    # Nacos 命名空间 ID
    nacosNamespaceId: 98ac6df3-xxxx-xxxx-xxxx-ab98115dfde4
    # Nacos 服务分组
    nacosGroups:
    - DEFAULT_GROUP
```

通过[McpBridge](./mcp-bridge.md)资源配置了两个服务来源，分别取名 “production”和“uat”，需要注意的是 Higress 对接 Nacos 同时支持 HTTP 和 gRPC 两种协议，建议将 Nacos 升级到 2.x 版本，这样可以在上述配置的 type 中指定 “nacos2” 使用 gRPC 协议，从而更快速地感知到服务变化，并消耗更少的 Nacos 服务端资源。
基于 McpBridge 中的 registries 数组配置，Higress 可以轻松对接多个且不同类型的服务来源（Nacos/Zookeeper/Eureka/Consul/...），这里对于 Nacos 类型的服务来源，支持配置多个不同命名空间，从而实现不同命名空间的微服务可以共用一个网关，降低自建微服务网关的资源成本开销。


## 配置 Ingress

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/destination: service-provider.DEFAULT-GROUP.d8ac64f3-xxxx-xxxx-xxxx-47a814ecf358.nacos
  name: demo
  namespace: default
spec:
  rules:
  - http:
      paths:
      - backend:
          resource:
            apiGroup: networking.higress.io
            kind: McpBridge
            name: default
        path: /
        pathType: Prefix
```

和常见的 Ingress 在 backend 中定义 service 不同，这里基于 Ingress 的 resource backend 将上面定义服务来源的 McpBridge 进行关联。并通过注解`higress.io/destination`指定路由最终要转发到的目标服务。

对于 Nacos 来源的服务，这里的目标服务格式为：“服务名称.服务分组.命名空间ID.nacos”，注意这里需要遵循 DNS 域名格式，因此服务分组中的下划线'_'被转换成了横杠'-'。

---

## File: docs/zh-cn/user/nginx-ingress.md

---
title: Nginx Ingress 兼容说明
keywords: ingress,nginx
---

# Nginx Ingress 兼容说明

TBD

---

## File: docs/zh-cn/user/nginx-ingress-migrate.md

---
title: 从 Nginx Ingress Controller 平滑迁移
keywords: Ingress
---

# 从 Nginx Ingress Controller 平滑迁移

TBD

---

## File: docs/zh-cn/user/opensergo-gray.md

---
title: 对接 OpenSergo 实现全链路灰度
keywords: opensergo,gray
---

# 对接 OpenSergo 实现全链路灰度

文档计划推出时间：2022.02.28