容器服务
容器服务
文档指南
请输入
- 文档首页
容器服务容器服务 VKE用户指南网络路由（Ingress）Nginx Ingress使用 Annotation 配置 Nginx Ingress
复制全文
下载 pdf使用 Annotation 配置 Nginx Ingress
文档反馈
问问助手容器服务 Nginx ingress 提供了与社区完全兼容的注解（Annotation），能够实现更丰富的七层负载均衡能力和更多样的服务路由规则。本文介绍容器服务 Nginx ingress 中常用注解的含义和使用方法。
注意
- Nginx Ingress 功能即将下线，详情请参见 【产品公告】NGINX Ingress 停止维护公告。
- 由于不同版本集群中 Nginx ingress 的版本不同，提供的注解略有差异，请以控制台的显示为准。
- 若在下文中没有找到您需要的注解，请参考 Nginx 官方文档。
灰度发布
注解 | 说明 |
启用灰度发布功能。配置为true时，表示启用该功能。 | |
基于 Header 实现灰度发布，将请求流量分配到灰度服务入口。 | |
当请求中的 Header 值与该配置匹配时，请求流量会被分配到灰度服务入口。 | |
基于请求中的 Header 值进行流量切分，支持正则匹配。 | |
基于 Cookie 实现灰度发布，将请求流量分配到灰度服务入口。 | |
基于权重实现灰度发布，流量会根据权重占比随机路由到灰度服务入口。 | |
配置基于权重切分流量时的权重总和。 |
说明
重定向
注解 | 说明 |
当客户端的 HTTPS 被集群外部配置 Controller 是否将 TLS 链接直接发送到后端，取进行 SSL 卸载（SSL offloading）时，是否仍将 HTTP 的请求强制跳转到 HTTPS 端口。取值：
| |
是否将 www.domain.com 重定向到 domain.com，取值：
| |
配置永久重定向的目标地址。 | |
配置永久重定向的响应码。 | |
配置临时重定向的目标地址。 | |
使用 ssl-redirect 时，是否保留 URI 的尾斜杠。取值：
| |
配置要替换的源文本，同 Nginx proxy_redirect命令 的第一个参数。 | |
配置要替换的目标文本，同 Nginx proxy_redirect 命令的第二个参数。 | |
配置是否开启 HTTP 重定向，即当收到 HTTP 的请求时，强制重定向到 HTTPS 端口。
说明 当 Ingress 上有证书时，默认为 true。即开启 HTTP 重定向。 |
说明
流量复制
注解 | 说明 |
配置镜像后端的地址。 | |
默认情况下，流量复制请求的 Host 头会被设置成和mirror-target配置保持一致。可以通过该字段覆写 Host 头的内容。 | |
请求体默认会发送给镜像后端，配置该字段为off时，禁止将请求体发送给镜像后端。 |
说明
后端服务
注解 | 说明 |
指定后端服务使用的协议，支持 HTTP（默认值）、HTTP2、HTTPS、GRPC 和 GRPCS。 | |
配置默认后端资源对象的 Service 名称。 |
说明
URL 重写
在某些场景中，后端服务中公开的 URL 与 Ingress 规则中指定的路径不同。如果没有重写，任何请求都将返回 404。
注解 | 说明 |
配置 URL 重写规则。 | |
配置应用重定向的根目录。 |
说明
身份验证
支持通过在 Ingress 规则中添加附加注释来添加身份验证。
注解 | 说明 |
配置身份认证类型，支持basic和digest。 | |
配置身份认证使用的 Secret 名称。 | |
配置身份认证的 Secret 内容格式，支持如下 2 种格式：
| |
配置身份认证的提示信息。 |
外部认证
注解 | 说明 |
配置外部认证服务的 URL。 | |
配置外部认证 URL 链接的最大保持时间。 | |
是否在当前请求和外部认证请求之间共享 Nginx 变量。
| |
配置外部认证的一次连接中，允许处理的请求数。 | |
配置外部认证 URL 链接的超时时间。 | |
配置要传递给认证服务请求头的 Configmap 名称。 | |
开启认证缓存，并设置认证缓存的关键字。 | |
根据响应码设置认证缓存的有效时间。 | |
配置用于外部认证的自定义代码段。 | |
配置是否开启 GlobalExternalAuth，取值：
|
会话亲和性
注解 | 说明 |
配置会话亲和性类型，仅支持设置为cookie。 | |
配置会话亲和性模式，取值：
| |
配置蓝绿发布的会话亲和策略，取值：
|
客户端证书认证
注解 | 说明 |
配置客户端认证的 Secret 名称。该 Secret 中必须包含一个名为 ca.crt 的文件，可对此 Ingress 进行身份验证。 | |
配置客户端证书链的验证深度，默认为 1。 | |
启用客户端证书校验。 | |
配置客户端证书验证错误时的跳转页面。 | |
配置是否将证书传递到上游服务器。取值：
| |
为使用CN=前缀的请求的客户端证书的 CN 添加健全性检查。 |
后端证书认证
注解 | 说明 |
配置后端认证的 Secret 名称。该 Secret 中必须包含一个名为 ca.crt 的文件，用于验证代理服务器的证书。 | |
启用或禁用验证代理服务器证书，取值：
| |
配置代理服务器证书链的验证深度，默认为 1。 | |
配置发送到代理服务器的请求使用的加密算法。该加密算法需要能被 OpenSSL 识别。 | |
覆盖用于验证代理服务器证书的服务器名称。当与代理服务器建立连接时，该值会通过 SNI 传递。 | |
配置发给代理服务器的请求使用指定协议。 | |
与代理的 HTTPS 服务器建立连接时，允许通过 TLS 服务器的 SNI（名称指示扩展）传递服务器名称。 |
跨域访问
注解 | 说明 |
是否启用跨域访问，取值：
| |
配置允许跨域访问的域名。 | |
配置允许跨域访问的方法。 | |
配置允许跨域访问的请求头。 | |
配置允许暴露给浏览器响应的 Header。 | |
是否允许客户端携带验证信息，取值：
| |
配置请求结果缓存的最长时间。 |
超时时间
注解 | 说明 |
配置将请求发送至 Upstream server 的超时时间。 | |
配置两次写操作的最大间隔时长。 | |
配置在连接断开之前，两次从 Upstream server 接收读操作的超时时间。 | |
配置重试策略或者重试条件。 | |
配置允许将连接传递到下一个服务器的超时时间。 | |
请求的最大重试次数。 | |
配置是否启用请求缓冲功能，取值：
|
全局限速
注解 | 说明 |
配置一个窗口允许的最大请求数。 | |
配置窗口的持续时间。 | |
配置用于计数的键。 | |
配置不限速的 IP 列表和 CIDR 列表，不同的 IP 和 CIDR 用逗号分隔。 |
其他
注解 | 说明 |
每个 location 读取客户端请求体的缓存大小。 | |
在 location 指令域添加 Nginx 配置指令。 | |
根据响应码设置为错误状态，只针对当前 Ingress 关联的 location。 | |
当配置了custom-http-errors时，可以使用该注解禁用 Nginx 的 proxy-intercept-errors，但仅适用于与此 Ingress 关联的 Nginx 的 location。 | |
配置是否 Nginx 可以自动把 Link 头中指定的预加载链接推送给客户端。取值：
| |
配置单个 IP 地址的并发连接数限制。 | |
配置单个 IP 地址每秒请求频率限制。 | |
配置 Nginx 中的请求体最大限制。如果客户端请求体的大小超过了最大限制，Nginx 会返回413错误码。 | |
将 Upstream server 通过 Set-Cookie 字段设定的 Domain 属性修改为指定的值。 | |
配置在代理服务器响应的 Set-Cookie 字段。 | |
配置 Nginx 反向代理与后端通信的 HTTP 协议版本，取值为1.0或1.1。 | |
是否启用重写日志，取值：
| |
默认情况下，请求需要满足所有身份验证要求才能被允许。使用该注解允许满足任何或所有身份验证要求的请求。 | |
在 Nginx 配置的服务器定义中设置一个或多个别名。 | |
扩展配置到 Server 模块。 | |
配置 Upstream 成员列表。取值：
| |
配置 Cookie 名称。 | |
配置 Cookie 字段 Path 的值。 | |
配置 Cookie 的 Domain 属性。 | |
当会话保持的被代理服务器请求失败时，下次请求是否更改为向另一台被代理服务器转发。
| |
配置 Samesite 属性到 Cookie 上。 | |
配置在不兼容SameSite=None的浏览器中忽略SameSite=None属性。 | |
配置 Controller 是否将 TLS 链接直接发发送到后端，取值：
| |
添加自定义的流配置到 Server 块。 | |
用于一致散列的 Nginx 变量、文本值或其任何组合。 | |
用字符串值将非标准的 X-Forwarded-Prefix 标头添加到上游请求中。 | |
配置后端服务的负载均衡算法。取值为：（默认值）round_robin 和 ewma。 | |
允许修改语句proxy_set_header Host $host中的 host 值。 | |
配置路由 IP 黑名单，支持 IP 地址或 CIDR 地址块，以逗号分隔。 | |
配置路由 IP 白名单，支持 IP 地址或 CIDR 地址块，以逗号分隔。 | |
配置是否开启代理缓冲，取值：
| |
配置从代理服务器中读取响应的缓冲区的数量。默认为 4。 | |
配置从代理服务器中读取响应的缓冲的大小。默认为4k。 | |
配置临时缓冲区大小。当从代理服务器读取响应的缓冲区时，如果完整的响应数据量大于缓冲区大小，一部分响应数据可以保存在临时缓冲区里。 | |
配置 TLS 用于协商使用的加密算法组合。 | |
配置使用 SSLv3 和 TLS 协议时，服务器加密算法是否优先于客户端加密算法。取值：
| |
配置覆盖 Nginx 的默认链接头。 | |
配置是否开启访问日志，取值：
| |
配置是否开启 opentracing，取值：
| |
配置是否信任 trace spans，取值：
| |
配置是否开启 Opentelemetry，取值：
| |
配置是否信任 Opentelemetry 的 trace spans，取值：
| |
配置是否使用正则表达式形式的路径，取值：
| |
是否开启 ModSecurity，取值：
| |
配置是否开启 OWASP Core Rule Set，取值：
| |
配置从 Nginx 传递事务 ID，而不是在库中自动生成。 | |
配置自定义 ModSecurity 规则。 |
最近更新时间：2026.04.07 14:29:43
这个页面对您有帮助吗？
有用
有用
无用
无用