文档中心

容器服务

ALB Ingress

通过 kubectl 创建 ALB Ingress

ALB Ingress 基于火山引擎应用型负载均衡（Application Load Balancer，ALB），提供更加丰富的七层负载均衡能力。本文主要介绍通过 YAML 文件创建 ALBInstance，并配置 ALB Ingress 的相关操作。

注意

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

背景信息

ALBInstance 是 ALB Ingress Controller 管理的 CRD 资源，ALB Ingress Controller 使用 ALBInstance 来配置和监听 ALB 实例。

说明

一个 ALBInstance 对应一个 ALB 实例，但一个 ALBInstance 可对应多个 Ingress，即 ALBInstance 与 Ingress 是一对多的对应关系。

前提条件

已连接集群，详情请参见连接集群。

已开通 ALB 产品服务。若未开通，请首先登录您的火山引擎账号，然后单击服务授权，并在弹出的页面中单击立即授权，完成跨服务授权。

（可选）配置 HTTPS 协议的 ALB Ingress 时，需要提前完成证书配置。详情请参见 ALB Ingress 配置 HTTPS 协议。

注意

如需使用证书中心的证书，请首先登录您的火山引擎账号，然后单击服务授权，并在弹出的页面中单击立即授权，完成跨服务授权。

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

创建 ALBInstance

对接已有 ALB 实例

使用如下 YAML 配置，创建 ALBInstance 并对接已有 ALB 实例。

spec字段中的详细参数说明如下所示。

字段	类型	是否必选	描述	取值示例	是否支持修改
instanceID	String	是	指定已存在的 ALB 实例 ID。	alb-2dgns526uiv41fi5***	否
listeners.protocol	String	否	监听器协议。取值： HTTP（默认值） HTTPS	HTTP	是
listeners.port	Integer	否	监听器端口。取值：取值范围：1～65535 默认值：80（HTTP）、443（HTTPS）	80	是
listeners.certificateSource	String	否	监听器默认证书的来源。取值： alb：ALB 管理的证书。 cert_center：证书中心管理的证书。说明 ALB 标准版实例仅支持使用证书中心证书。	alb	是
listeners.certificateID	String	否	监听器默认证书 ID。	cert-2wx20lm7uquww7***	是
listeners.domainExtensions.domain	String	否	HTTPS 监听器关联的扩展域名，支持泛域名。	example.com	是
listeners.domainExtensions.certificateSource	String	否	监听器扩展域名的证书来源，取值： alb：ALB 管理的证书。 cert_center：证书中心管理的证书。说明 ALB 标准版实例仅支持使用证书中心证书。	alb	是
listeners.domainExtensions.certificateID	String	否	HTTPS 监听器扩展域名的证书 ID。	cert-2wx20lo6vuww07***	是
listeners.enableHTTP2	Boolean	否	HTTP2.0 特性开关，该参数仅对 HTTPS 监听器有效。取值： true：启用 HTTP2.0 协议特性。 false：（默认值）禁用 HTTP2.0 协议特性。	false	是
listeners.enableQUIC	Boolean	否	QUIC 特性开关，该参数仅对 HTTPS 监听器有效。取值： true：启用 QUIC 协议特性。 false：（默认值）禁用 QUIC 协议特性。说明该功能是 ALB 产品的邀测功能，如需使用，请联系客户经理申请。	false	是

说明

当您选择创建 HTTPS 协议的监听器时，需要首先完成 HTTPS 证书配置，详情请参见 ALB Ingress 配置 HTTPS 协议。

新建 ALB 实例

使用如下 YAML 配置，创建 ALBInstance 并同时创建新的 ALB 实例。

spec字段中的详细参数说明如下所示。

字段	类型	是否必选	描述	取值示例	是否支持修改
instance.name	String	是	新创建 ALB 的实例名称。	alb	否
instance.edition	String	否	新创建 ALB 的实例类型，取值： Basic：基础版 Standard：标准版未填写该字段时，默认为 Basic，即基础版。	Basic	否
instance.zoneMappings.N.subnetId	String	是	子网 ID，ALB 实例在此可用区下的私网 IP 地址将从此子网网段中分配。注意允许配置多个不同的子网。多个不同的子网不允许位于同一可用区。	subnet-bp12mw1f8k3jg0***	否
instance.addressType	String	否	新创建 ALB 的网络类型。取值： public：（默认值）公网 private：私网	public	否
instance.eipSpec.isp	String	否	公网 ALB 实例的公网 IP 线路类型。默认为 BGP。更多取值，请参见 EIP 产品文档。	BGP	否
instance.eipSpec.bandwidth	Integer	否	公网 ALB 实例的公网 IP 的带宽峰值。 instance.eipSpec.billingType取值为 2 时，取值范围为 1～500，单位为 Mbps。 instance.eipSpec.billingType取值为 3 时，取值范围为 1～200，单位为 Mbps。说明如果您通过工单提升了 EIP 的带宽上限，则此处的带宽取值范围会同步提升。详情请参见 EIP 使用限制。	10	否
instance.eipSpec.billingType	Integer	否	公网 ALB 实例的公网 IP 的计费方式。取值： 2：（默认值）表示按量计费-按带宽上限计费。 3，表示按量计费-按实际流量计费。	2	否
instance.eipSpec.bandwidthPackageID	String	否	共享带宽包 ID。	-	是
instance.ipVersion	String	否	IP 版本。取值固定为 ipv4。	ipv4	否
instance.deleteProtection	String	否	ALB 实例的删除保护功能，取值： on：表示开启删除保护功能。 off：（默认值）表示禁用删除保护功能。	on	是
listeners.protocol	String	否	监听器协议。取值： HTTP（默认值） HTTPS	HTTP	是
listeners.port	Integer	否	监听器端口。取值：取值范围：1～65535 默认值：80（HTTP）、443（HTTPS）	80	是
listeners.certificateSource	String	否	监听器默认证书的来源。取值： alb：ALB 管理的证书。 cert_center：证书中心管理的证书。说明 ALB 标准版实例仅支持使用证书中心证书。	alb	是
listeners.certificateID	String	否	监听器默认证书 ID。	cert-2wx20lm7uquww7***	是
listeners.domainExtensions.domain	String	否	HTTPS 监听器关联的扩展域名，支持泛域名。	example.com	是
listeners.domainExtensions.certificateSource	String	否	监听器扩展域名的证书来源，取值： alb：ALB 管理的证书。 cert_center：证书中心管理的证书。说明 ALB 标准版实例仅支持使用证书中心证书。	alb	是
listeners.domainExtensions.certificateID	String	否	HTTPS 监听器扩展域名的证书 ID。	cert-2wx20lo6vuww07***	是
listeners.enableHTTP2	Boolean	否	HTTP2.0 特性开关，该参数仅对 HTTPS 监听器有效。取值： true：启用 HTTP2.0 协议特性。 false：（默认值）禁用 HTTP2.0 协议特性。	false	是
listeners.enableQUIC	Boolean	否	QUIC 特性开关，该参数仅对 HTTPS 监听器有效。取值： true：启用 QUIC 协议特性。 false：（默认值）禁用 QUIC 协议特性。说明该功能是 ALB 产品的邀测功能，如需使用，请联系客户经理申请。	false	是

说明

当您选择创建 HTTPS 协议的监听器时，需要首先完成 HTTPS 证书配置，详情请参见 ALB Ingress 配置 HTTPS 协议。

配置 WAF 防护

说明

如果您需要为 ALB 配置 WAF 防护功能，需要：

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

已创建 Web 应用防火墙实例，详情请参见创建 WAF 实例。

如果需要对已经创建的 ALB 实例配置 WAF 防护功能，可以到 ALB 控制台进行操作。

使用 ALBInstance 创建新的 ALB 实例时，支持使用spec.instance中的wafConfig字段配置 ALB 实例的 WAF 防护功能。启用该功能后，ALB 实例会接入 Web 应用防火墙服务进行安全防护。当未配置wafConfig字段时，容器服务不会修改 ALB 侧的配置。本小节以创建私网类型的 ALB 为例，示例和说明如下：

spec.instance中wafConfig字段的参数说明如下所示。

字段	类型	是否必选	描述	取值示例	是否支持修改
wafProtectionEnabled	String	是	配置 ALB 实例的 WAF 防护功能。取值： on：启用 WAF 防护。 off：禁用 WAF 防护。	on	是
wafInstanceID	String	否	配置 Web 应用防火墙服务实例 ID。说明当wafProtectionEnabled为on时，必须配置。	waf-1	是

配置访问日志投递

说明

如果您需要为 ALB 配置访问日志投递功能，需要：

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

已创建日志项目和日志主题，详情请参见日志项目、日志主题。

如果需要对已经创建的 ALB 实例配置访问日志投递，可以到 ALB 控制台进行操作。

使用 ALBInstance 创建新的 ALB 实例时，支持使用spec.instance中的tlsAccessLogConfig字段配置 ALB 实例的访问日志投递功能。启用启该功能后，ALB 会将实例的访问日志投递至日志服务（TLS）中。当未配置tlsAccessLogConfig字段时，容器服务不会修改 ALB 侧的配置。本小节以创建私网类型的 ALB 为例，示例和说明如下：

spec.instance中tlsAccessLogConfig字段的参数说明如下所示。

字段	类型	是否必选	描述	取值示例	是否支持修改
tlsAccessLogEnabled	String	是	ALB 实例访问日志开关。取值： on：启用访问日志投递。 off：禁用访问日志投递。	on	是
tlsTopicID	String	否	配置日志项目 ID。说明当tlsAccessLogEnabled为on时，必须配置。	76fa2b9b-73e4-4d8b-9528-a4b000***	是
tlsProjectID	String	否	配置日志主题 ID。说明当tlsAccessLogEnabled为on时，必须配置。	7bcd0f1b-be4a-4e47-b103-51a3f***	是

配置监听器访问控制（ACL）

说明

如果您需要为 ALB 的监听器配置访问控制（ACL）功能，需要：

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

已配置访问控制策略组，详情请参见访问控制。

使用 ALBInstance 对接已有 ALB 实例或创建新的 ALB 实例时，支持使用spec.listeners中的aclConfig字段配置 ALB 监听器的访问控制（ACL）功能。当未配置aclConfig字段时，容器服务不会修改 ALB 侧的配置。本小节以对接已有 ALB 实例为例，示例和说明如下：

spec.listeners中aclConfig字段的参数说明如下所示。

字段	类型	是否必选	描述	取值示例	是否支持修改
aclEnabled	String	是	监听器访问控制功能开关。取值： on：启用访问控制。 off：禁用访问控制。	on	是
aclType	String	否	访问控制模式。取值： white：白名单模式。该模式下，仅所选策略组内的 IP 地址能访问。 black：黑名单模式。该模式下，所选策略组内的 IP 地址无法访问。说明当aclStatus为on时，必须配置。	white	是
aclIDs	Array of String	否	配置访问策略组 ID。说明当aclStatus为on时，必须配置。最多允许配置 5 个策略组。每个策略组最多可以包含 300 个 IP 地址条目。每个 IP 地址条目可以是一个 IP 地址或者一个 CIDR 地址段。关于策略组的更多内容，请参见访问控制。	acl-1	是

监听器个性化配置

说明

如果您需要为 ALB 的监听器添加个性化配置，需要：

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

已创建个性化配置，详情请参见个性化配置。

使用 ALBInstance 对接已有 ALB 实例或创建新的 ALB 实例时，支持使用spec.listeners中的customizedConfig字段配置 ALB 监听器的个性化配置。当未配置customizedConfig字段时，容器服务不会修改 ALB 侧的配置。个性化配置支持创建并管理常规的 NGINX 配置策略，详情请参见个性化配置。本小节以对接已有 ALB 实例为例，示例和说明如下：

spec.listeners中customizedConfig字段的参数说明如下所示。

字段	类型	是否必选	描述	取值示例	是否支持修改
customizedConfigEnabled	String	是	监听器是否绑定个性化配置。取值： on：绑定个性化配置。 off：不绑定个性化配置。	on	是
customizedCfgID	String	否	个性化配置 ID。说明当customizedConfigEnabled为on时，必须配置。	ccfg-2dbdimgq77sao3r***	是

查看 ALBInstance 名称和状态

当您在集群中创建 ALBInstance 后，可以使用如下方法确定 ALBInstance 的状态。

登录容器服务控制台。

单击左侧导航栏中的集群。

在集群列表页面，单击目标集群。

在集群管理页面的左侧导航栏中，选择工作负载 > 对象浏览器。

在对象浏览器页面的 CRD 分类下，单击 albinstance。

在 albinstance 详情页面，查看创建的 ALBInstance 资源名称。

单击操作栏中的编辑 Yaml，查看 ALBInstance 资源详情。其中status字段展示了 ALBInstance 资源的状态信息。

status字段中不同的取值含义如下表所示。

字段	类型	含义
phase	String	表示 ALBInstance 资源状态： Pending：表示关联的 ALBInstance 还未调谐完成。 Running：表示 ALBInstance 对应的配置都已经更新到服务端。 Configuring：表示 ALBInstance 处于调谐中。 Deleting：表示 ALBInstance 处于删除中。
instanceID	String	表示关联的 ALB 实例 ID。
ingress	*v1.LoadBalancerIngress	表示 ALB 的 IP 地址、监听器端口和协议。

创建 ALB Ingress

注意

配置 ALB Ingress 时，paths.pathType参数仅用作校验，具体取值（Exact、Prefix 或 Regex）无实际意义。同时，在不同 ALB 实例类型时的默认动作不同：

当为 ALB 标准版实例时，无论paths.pathType为何取值，默认为精确匹配模式。如需实现前缀匹配，请在paths.path中使用通配符*实现，例如将paths.path配置为/api/*。

当为 ALB 基础版实例时，无论paths.pathType为何取值，默认为前缀匹配模式。

基于域名转发

ALB Ingress 支持将不同的域名访问，转发到不同的后端。示例alb-ingress.yaml代码如下：

基于路径转发

ALB Ingress 支持将相同域名、不同路径的访问，转发到不同的后端。示例alb-ingress.yaml代码如下：

配置未指定 host 规则

ALB Ingress 支持配置未指定 host 规则。示例alb-ingress.yaml代码如下：

配置默认转发规则的后端服务器

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

匹配正则表达式路径

说明

【邀测·申请试用】：当 ALB 为基础版时，功能仍处于邀测阶段，如需使用，请提交申请。

ALB Ingress 支持在 path 路径上定义正则表达式路径或非正则表达式路径，如下表所示。

路径匹配方式	说明
非正则表达式	必须以正斜线/ 开头。仅允许包含字母、数字和-、_、/、.、%、?、#、&、＝等字符，且不可包括// 。
正则表达式	必须以/~开头，且/~只能出现一次。支持大小写字母、数字和.、-、_、/、＝、?、~、^、、$、:、()、[]、+、\|等字符。 /~开头表示区分大小写的正则匹配，/~ 开头表示不区分大小写的正则匹配。

说明

当您在 ALB Ingress 的 path 中使用 /~ 或 /~* 配置正则表达式路径时，VKE 传递给 ALB 时会去掉对应的 /。例如：当您撰写的路径为 /~/test/[a-z]* 时，实际转发给 ALB 的路径为 ~/test/[a-z]*。此时，类似于 /test/test 的路径即可命中该正则表达式。

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

最近更新时间：2026.08.18 17:45:53

这个页面对您有帮助吗？

有用

无用