文档中心

容器服务

ALB Ingress

使用 Annotation 配置 ALB Ingress

ALB Ingress 支持通过注解（Annotation）实现更加丰富的 ALB 能力配置。本文主要介绍使用 Annotation 配置 ALB Ingress 的主要场景和配置方法。

注意

配置 ALB Ingress 前，请务必仔细阅读 ALB Ingress 使用注意事项。

注解的内容需要严格区分大小写。

容器服务支持对接 ALB 基础版实例和标准版实例，以满足不同规模集群的负载均衡需求。不同 ALB 类型支持配置的功能略有不同。详情请参见 ALB 实例类型概述。

如需对接 ALB 标准版实例，请将 alb-ingress-controller 组件升级至 v0.31.1 及以上版本。详情请参见升级组件。

监听器配置

选择单个监听器

说明

使用 Annotation 选择 ALB 实例的监听器前，您需要首先通过 ALBInstacne 创建或关联对应的 ALB 实例和监听器。配置方式，请参见通过 kubectl 创建 ALB Ingress。

ALB Ingress 支持通过 Annotation 选择由 ALBInstace 创建好的单个监听器，并在指定监听器下创建相应的转发规则和后端服务器组。示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/loadbalancer-port	String	选择单个监听器的监听端口，请保证监听器已经配置了对应的监听端口。	80
ingress.vke.volcengine.com/loadbalancer-protocol	String	选择单个监听器的监听协议。取值： http：使用 HTTP 协议的监听器。 https：使用 HTTPS 协议的监听器。	http

选择多个监听器

说明

使用 Annotation 选择 ALB 实例的监听器前，您需要首先通过 ALBInstacne 创建或关联对应的 ALB 实例和监听器。配置方式，请参见通过 kubectl 创建 ALB Ingress。

ALB Ingress 支持通过 Annotation 选择由 ALBInstace 创建好的多个监听器，并在指定监听器下创建相应的转发规则和后端服务器组。示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/listen-ports	Array of String	选择多监听器的协议和端口号，例如{"HTTP": 80}。支持配置多个值，多个值之间使用半角逗号,隔开。说明使用该 Annotation 选择多监听器时，选择单个监听器的ingress.vke.volcengine.com/loadbalancer-port和ingress.vke.volcengine.com/loadbalancer-protocol失效。删除该 Annitation 时，系统自动创建的转发规则会被同步删除。	无

转发规则配置

配置多域名/多路径的流量转发

注意

仅当 ALB Ingress 对接 ALB 标准版实例时，支持该配置。

注解中的{{service-name}}字段必须与spec.rules中配置的后端服务名称对应一致，例如在本例中，正确的注解为ingress.vke.volcengine.com/loadbalancer-conditions.service-demo。

注解中配置的hostConfig会和spec.rules中的host合并，例如在本例中，转发规则合并后，host为example.com或example-2.com的请求，均会转发到service-demo服务中。

注解中配置的pathConfig会和spec.rules中的path合并，例如在本例中，转发规则合并后，path为/path1或/path2的请求，均会转发到service-demo服务中。

示例alb-ingress.yaml代码如下：

配置基于 Header 的流量转发

ALB Ingress 支持通过 Annotation 配置转发规则，允许基于 HTTP 请求头中的特定信息（如 User-Agent、Content-Type 等）进行匹配，匹配成功后再执行转发动作。完整配置示例及参数说明，请参见配置基于 Header 的流量转发。

注解格式和示例，如下所示：

配置基于请求方法的流量转发

ALB Ingress 支持通过 Annotation 配置转发规则，允许基于 HTTP 请求类型（如 GET、POST 等）进行匹配，匹配成功后再执行转发动作。具体配置示例及参数说明，请参见配置基于请求方法的流量转发。

注解格式和示例，如下所示：

配置基于查询字符串的流量转发

ALB Ingress 支持通过 Annotation 配置转发规则，允许基于 URL 中查询字符串的参数和值进行匹配，匹配成功后再执行转发动作。具体配置示例及参数说明，请参见配置基于查询字符串的流量转发。

注解格式和示例，如下所示：

配置重写

ALB Ingress 支持使用 Annotation 配置重写转发动作，允许改写请求路径，向后端服务器请求新路径内容。具体配置示例及参数说明，请参见配置转发流量重写。

注解格式和示例，如下所示：

HTTP 重定向至 HTTPS 快速配置

ALB Ingress 支持使用 Annotation 快速配置 HTTP 请求重定向至 HTTPS，允许将访问 HTTP/80 监听器的请求固定重定向至 HTTPS/443，并保留原始 Host、Path 和 Query。具体配置示例及参数说明，请参见配置转发流量重定向。

注解格式和示例，如下所示：

配置重定向

ALB Ingress 支持使用 Annotation 配置重定向转发动作，允许将将特定的访问请求重定向至指定的路径。具体配置示例及参数说明，请参见配置转发流量重定向。

注解格式和示例，如下所示：

配置流量限速

ALB Ingress 支持使用 Annotation 配置流量限速，支持对请求设置限速。具体配置示例及参数说明，请参见配置转发流量限速。

注解格式和示例，如下所示：

配置返回固定响应

ALB Ingress 支持使用 Annotation 配置返回固定响应，可以直接返回固定响应，不向后端服务器继续转发。具体配置示例及参数说明，请参见配置返回固定响应。

注解格式和示例，如下所示：

配置跨域

ALB Ingress 支持使用 Annotation 配置跨域。具体配置示例及参数说明，请参见配置转发流量跨域。

注解格式和示例，如下所示：

配置转发至多个后端服务

ALB Ingress 支持使用 Annotation 将 ALB Ingress 请求，按照指定的权重，同时转发至集群内 Pod（默认后端服务器组）和集群外 ECS 服务器组（自定义后端服务器组）。具体配置示例及参数说明，请参见配置转发至多个后端服务。

注解格式和示例，如下所示：

服务器组配置

配置调度算法

ALB Ingress 支持通过 Annotation 配置后端服务器组的调度算法，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/loadbalancer-scheduler	String	ALB 后端服务器组使用的调度算法。取值： wrr：加权轮询，权重值越高的后端服务器，被轮询到的次数（概率）越高。 wlc：加权最小连接数，在最少连接数的基础上，根据服务器的不同处理能力，为每个服务器分配不同的权重，使其能够接受相应权值数的服务请求。 sh：源地址哈希，基于源 IP 地址的一致性哈希，相同的源地址会调度到相同的后端服务器。	wrr

配置健康检查

配置 HTTP 协议的健康检查

说明

如需配置健康检查 HTTP 协议版本和端口，请将 alb-ingress-controller 组件升级至 v0.37.0 及以上版本。详情请参见升级组件。

ALB Ingress 支持通过 Annotation 为后端服务器组配置 HTTP 协议的健康检查。示例和注解说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/loadbalancer-healthcheck-enabled	String	是否开启健康检查。取值： true：开启健康检查。 false：禁用健康检查。	false
ingress.vke.volcengine.com/loadbalancer-healthcheck-protocol	String	健康检查协议，本例中选择 http。	http
ingress.vke.volcengine.com/loadbalancer-healthcheck-domain	String	健康检查域名。填写后 ALB 会将域名配置到 host 字段中。如果没有配置域名，则 host 字段为空，ALB 不会在请求中附带 host 字段，而是默认域名为后端服务器组内网 IP。	无
ingress.vke.volcengine.com/loadbalancer-healthcheck-path	String	健康检查路径，默认为/。	/
ingress.vke.volcengine.com/loadbalancer-healthcheck-method	String	健康检查的方法。取值：GET、HEAD。	GET
ingress.vke.volcengine.com/loadbalancer-healthcheck-http-version	String	健康检查 HTTP 协议版本，取值： HTTP1.0（默认值） HTTP1.1	HTTP1.0
ingress.vke.volcengine.com/loadbalancer-healthcheck-port	String	健康检查端口。 0：（默认值）使用后端服务器端口进行健康检查。 1～65535：使用指定的端口进行健康检查。	0
ingress.vke.volcengine.com/loadbalancer-healthcheck-httpcode	String	健康检查正常的状态码。取值：http_2xx、http_3xx、http_4xx、http_5xx。	http_2xx,http_3xx
ingress.vke.volcengine.com/loadbalancer-healthcheck-timeout	String	等待健康检查响应的时间。取值：1～60 单位：秒	2
ingress.vke.volcengine.com/loadbalancer-healthcheck-interval	String	执行健康检查的时间间隔。取值：1～300 单位：秒	2
ingress.vke.volcengine.com/loadbalancer-healthy-threshold	String	健康检查连续成功多少次后，将后端服务器的健康检查状态由 Fail 判定为 Success。取值：2～10 单位：次	3
ingress.vke.volcengine.com/loadbalancer-unhealthy-threshold	String	健康检查连续失败多少次后，将后端服务器的健康检查状态由 Success 判定为 Fail。取值：2～10 单位：次	3

配置 TCP 协议的健康检查

ALB Ingress 支持通过 Annotation 为后端服务器组配置 TCP 协议的健康检查。示例和注解说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/loadbalancer-healthcheck-enabled	String	是否开启健康检查。取值： true：开启健康检查。 false：禁用健康检查。	false
ingress.vke.volcengine.com/loadbalancer-healthcheck-protocol	String	健康检查协议，本例中选择 tcp。	http
ingress.vke.volcengine.com/loadbalancer-healthcheck-timeout	String	等待健康检查响应的时间。取值：1～60 单位：秒	2
ingress.vke.volcengine.com/loadbalancer-healthcheck-interval	String	执行健康检查的时间间隔。取值：1～300 单位：秒	2
ingress.vke.volcengine.com/loadbalancer-healthy-threshold	String	健康检查连续成功多少次后，将后端服务器的健康检查状态由 Fail 判定为 Success。取值：2～10 单位：次	3
ingress.vke.volcengine.com/loadbalancer-unhealthy-threshold	String	健康检查连续失败多少次后，将后端服务器的健康检查状态由 Success 判定为 Fail。取值：2～10 单位：次	3

为指定后端服务组配置健康检查

上述基于 HTTP 和 TCP 的健康检查配置方法会为所有由 ALB Ingress 创建的后端服务器组配置相同的全局健康检查策略。当您需要为某个指定的后端服务器组（本例中为second.example.com）配置不同的健康检查策略时，可以通过以下 Annotation 实现，示例和注解说明如下：

ingress.vke.volcengine.com/loadbalancer-rules-configs注解中的参数说明如下表所示。

字段	类型	描述	默认值
host	String	匹配健康检查的转发域名。	无
path	String	匹配健康检查的转发路径。	无
healthCheck	Array of healthCheck	后端服务器组的健康检查规则。	无

healthCheck

字段	类型	描述	默认值
enabled	Boolean	启用后端服务组健康检查功能。取值： true：启用指定后端服务组健康检查功能。 false：禁用指定后端服务组健康检查功能。	无
protocol	String	健康检查协议，仅支持 http。	无
method	String	健康检查方法。取值：GET、HEAD。	HEAD
httpcode	String	健康检查正常的 HTTP 状态码。取值：http_2xx、http_3xx、http_4xx、http_5xx。	http_2xx,http_3xx
timeout	Integer	健康检查的响应超时时间。如果后端服务器在指定的时间内没有正确响应，则判定为健康检查异常。取值范围为 1～60 秒。注意响应超时时间需小于等于检查时间间隔。	2
interval	Integer	健康检查的时间间隔。取值范围：1～300 秒。	2
healthyThreshold	Integer	健康检查的健康阈值。表示连续执行指定次数的健康检查，结果均为正常的后端服务器将判定为健康检查正常。取值范围为 2～10 次。	3
unhealthyThreshold	Integer	健康检查的不健康阈值。表示连续执行指定次数的健康检查，结果均为异常的后端服务器将判定为健康检查正常。取值范围为 2～10 次。	3

配置后端服务器组通信协议

ALB Ingress 支持通过 Annotation 配置后端服务器组之间的通信协议，示例和说明如下：

注意

仅标准版 ALB 实例支持后端协议 HTTPS 和 gRPC。

gRPC 协议为 ALB 产品的邀测功能，如需使用，请联系您的客户经理。

已安装 alb-ingress-controller 组件，并升级至 v0.33.1 及以上版本。详情请参见升级组件。

该配置只允许在创建 ALB Ingress 时配置，创建完成后不支持修改。

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/loadbalancer-backend-protocol	String	后端服务器组的通信协议。取值： http：（默认值）后端通信协议为 HTTP，支持关联 HTTP 和 HTTPS 监听器。 https：后端通信协议为 HTTPS，支持关联 HTTP 和 HTTPS 监听器。 grpc：后端通信协议为 gRPC，支持关联 HTTP/2 监听器。注意当您需要配置后端通信协议为 gRPC 时，请先确认 ALB 监听器已经开启 HTTP/2 协议。该配置允许通过 ALBInstance 中的listeners.enableHTTP2字段进行配置，详情请参见通过 kubectl 创建 ALB Ingress。	http

其他

配置直通 Pod 模式

注意

直通 Pod 模式仅在 VPC-CNI 容器网络模式的集群下生效。

ALB Ingress 支持通过 Annotation 配置直通 Pod 模式，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
ingress.vke.volcengine.com/loadbalancer-pass-through	String	是否启用应用型负载均衡器直通 Pod 模式。取值： true：启用应用型负载均衡器直通 Pod 模式。 false：禁用应用型负载均衡器直通 Pod 模式。	false

最近更新时间：2026.10.12 14:31:59

这个页面对您有帮助吗？

有用

无用