# 监听器参数配置（lsconfig） 在ELB Gateway架构中，CCE引入了ListenerConfiguration（简称lsconfig）资源，用于精细化配置和管理ELB监听器的高级参数（如安全策略、连接超时时间等）。 #### 前提条件 集群版本已支持ELB Gateway功能。 #### 约束与限制 当lsconfig引用的Secret所创建的证书同时被其他监听器引用时，删除当前监听器将保留该证书并清理其描述信息，后续系统将不再管理该证书（即更新Secret后不会自动同步更新该证书内容）。 #### 关联lsconfig的方式 根据业务流程，您可以选择以下两种方式之一来配置监听器： - **方式一：创建Gateway后调整（系统自动创建）** 直接创建Gateway。若当前监听器未关联已有的lsconfig，系统会自动生成对应的lsconfig资源。创建完成后，您可以通过编辑该lsconfig随时调整监听器配置。 - **方式二：创建Gateway前配置（手动显式关联）** 提前编写并创建指定了监听器参数的lsconfig资源，随后创建Gateway或ListenerSet。系统在创建对应的ELB监听器时，将自动应用已有lsconfig中的配置。 #### 操作步骤 #### 方法一：修改系统自动生成的lsconfig 1. 创建目标Gateway资源，系统将自动为其绑定的监听器生成默认的 lsconfig。 ``` apiVersion: gateway.networking.k8s.io/v1 kind: Gateway # 资源类型为 Gateway metadata: name: cce-gateway # Gateway 名称 namespace: default spec: gatewayClassName: cce-shared-internal # GatewayClass 名称 listeners: - name: http #监听器名称 protocol: HTTP # 协议 port: 80 # 监听端口 ``` 2. 修改lsconfig调整配置。 **通过kubectl命令行修改** 1. **查询关联的lsconfig资源名称** 您可以使用以下命令精确查询指定Gateway或ListenerSet监听器所对应的lsconfig名称： - 查询Gateway关联的lsconfig名称： ``` kubectl get lsconfig -n -l gateway.cce.io/gateway-name=,gateway.cce.io/listener-section-name= ``` - 查询ListenerSet关联的lsconfig名称： ``` kubectl get lsconfig -n -l gateway.cce.io/listenerset-name=,gateway.cce.io/listener-section-name= ``` **参数说明：** - \：Gateway或ListenerSet所在的命名空间。 - \：目标资源名称。不超过 63 个字符则直接使用原名称；超过则保留前 54 个字符（去除末尾 -_. 等分隔符），并通过连字符 - 拼接原名称的前 8 位 SHA-256 哈希值（例如：nameprefix-dc876bc7）。 - \：目标监听器的名称（即 spec.listeners\[\].name）。 **使用示例：** 查询命名空间为default、Gateway名称为cce-gateway、监听器名称为http的lsconfig： ``` kubectl get lsconfig -n default -l gateway.cce.io/gateway-name=cce-gateway,gateway.cce.io/listener-section-name=http ``` 输出结果示例： ``` NAME TARGET ACCEPTED AGE cce-gateway-http-vwpjf cce-gateway True 11s ``` 2. **修改lsconfig调整配置** 执行以下命令直接编辑对应的lsconfig，修改保存后系统将自动同步更新ELB监听器配置： ``` kubectl edit lsconfig cce-gateway-http-vwpjf -n default ``` **通过控制台修改** 1. 登录[CCE控制台](https://console.huaweicloud.com/cce2.0/?#/cce/cluster/list)，单击集群名称进入集群。 2. 选择左侧导航栏的"服务"，在右侧选择"网关 API"页签。 ![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002778546353.png "点击放大") 3. 单击网关名称进入网关详情页，单击"高级配置"修改监听器配置。 ![](https://support.huaweicloud.com/usermanual-cce/zh-cn_image_0000002748906854.png "点击放大") #### 方法二：预先创建lsconfig并关联Gateway 1. 创建lsconfig资源 编写YAML配置文件，通过spec.targetRef明确指定待关联的Gateway/ListenerSet及其监听器名称。 ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: lsconfig-http-listener namespace: default spec: targetRef: group: gateway.networking.k8s.io kind: Gateway #Gateway或ListenerSet name: my-gateway #Gateway或ListenerSet名称 sectionName: http-listener #监听器名称 listener.name keepaliveTimeout: 60 clientTimeout: 60 memberTimeout: 180 reclaimPolicy: Retain #回收策略 ``` 预先创建的lsconfig需要设置回收策略为Retain（保留），后续删除监听器后需要手动删除lsconfig。 2. 创建对应的Gateway资源。系统检测到已匹配的lsconfig后，将直接根据该配置创建并初始化ELB监听器。 ``` apiVersion: gateway.networking.k8s.io/v1 kind: Gateway # 资源类型为 Gateway metadata: name: my-gateway # Gateway 名称 namespace: default spec: gatewayClassName: cce-shared-internal # GatewayClass 名称 listeners: - name: http-listener #监听器名称 protocol: HTTP # 协议 port: 80 # 监听端口 ``` #### lsconfig配置指导 #### 配置HTTPS监听器证书 当监听器协议为HTTPS时，可通过lsconfig为其绑定具体的ELB服务端证书。 ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: lsconfig-https-listener namespace: default spec: targetRef: group: gateway.networking.k8s.io kind: ListenerSet name: app-team-listeners sectionName: https-app defaultServerCertificate: #服务器证书 secretRef: name: tls-default-cert #同命名空间的Secret名称 sniCertificates: #sni证书 - domain: "*.example.com" #域名 secretRef: name: tls-wildcard-example #同命名空间的Secret名称 clientCACertID: "ca-cert-id" # 客户端 CA 证书 ID，留空表示单向 TLS（不做客户端认证） ``` #### 配置监听器访问控制策略（黑/白名单） 通过配置访问控制列表（ACL），限制仅特定IP段可访问该监听器，或封禁特定来源IP。 ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: lsconfig-https-listener namespace: default spec: targetRef: group: gateway.networking.k8s.io kind: Gateway name: my-gateway sectionName: https-listener ipACL: enable: true #开启访问控制 type: white #白名单控制 ipGroupIDs: - "ip-group-xxxx-1" #ELB的IP地址组ID - "ip-group-xxxx-2" ``` #### 开启HTTP/2协议 为HTTPS监听器开启HTTP/2特性，以提升传输性能与并发能力。 ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: lsconfig-https-listener namespace: default spec: targetRef: group: gateway.networking.k8s.io kind: Gateway name: my-gateway sectionName: https-listener defaultServerCertificate: secretRef: name: tls-default-cert http2Enable: true #开启HTTP/2功能 ``` #### 配置转发策略优先级 默认情况下，未显式指定优先级的路由将按创建时间排序。您可以通过在lsconfig中指定routePriorities列表来手动控制HTTPRoute的匹配顺序： - **显式优先级（列表排序）**：在routePriorities中声明的HTTPRoute，其列表中的出现顺序直接决定优先级（排在第一位的拥有最高优先级），优先于未列出的路由进行匹配。 - **默认规则（未列出的路由）**：未在routePriorities中指定的HTTPRoute，将遵循Kubernetes Gateway API的标准排序规则自动计算优先级（按匹配精细度排序：优先匹配主机名更长/精确匹配的路由、匹配路径最长/精确匹配的路由、匹配Header/Query数量最多的路由，若匹配规则完全相同则按创建时间升序排列），排在显式指定的路由之后。 ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: lsconfig-https-listener namespace: default spec: targetRef: group: gateway.networking.k8s.io kind: Gateway name: my-gateway sectionName: https-listener defaultServerCertificate: secretRef: name: tls-default-cert routePriorities: - routeRef: group: gateway.networking.k8s.io kind: HTTPRoute name: priority-route-1 - routeRef: group: gateway.networking.k8s.io kind: HTTPRoute name: priority-route-2 ``` #### 配置超时时间 为监听器配置超时时间： ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: my-listener-config namespace: default spec: targetRef: group: gateway.networking.k8s.io # 目标资源 API Group kind: Gateway # 目标资源类型 name: my-gateway # 目标资源名称 sectionName: https-listener # 指定 Gateway 中的特定 Listener 名称 keepaliveTimeout: 60 # 客户端连接空闲超时（秒） clientTimeout: 60 # 客户端请求超时（秒） memberTimeout: 60 # 后端服务器响应超时（秒） ``` #### 配置HTTP/HTTPS头字段 ``` apiVersion: gateway.cce.io/v1alpha1 kind: ListenerConfiguration metadata: name: my-listener-config namespace: default spec: targetRef: group: gateway.networking.k8s.io # 目标资源 API Group kind: Gateway # 目标资源类型 name: my-gateway # 目标资源名称 sectionName: https-listener # 指定 Gateway 中的特定 Listener 名称 reclaimPolicy: Retain # 资源回收策略 insertHeaders: # 控制插入到转发请求中的 ELB 生成头字段，仅 独享型ELB 支持 xForwardedPort: true # X-Forwarded-Port：将监听器端口号写入 HTTP 头 xForwardedForPort: true # X-Forwarded-For-Port：将客户端请求端口号写入 HTTP 头 xForwardedHost: true # X-Forwarded-Host：true=以请求头Host重写 / false=透传客户端的值 xRealIP: true # X-Real-IP：true=以客户端源IP重写 / false=透传客户端的值 xForwardedProto: true # X-Forwarded-Proto：将客户端请求协议写入 HTTP 头 xForwardedTLSCertificateID: true # X-Forwarded-TLS-Certificate-ID：将 TLS 证书 ID 写入 HTTP 头 xForwardedTLSProtocol: true # X-Forwarded-TLS-Protocol：将 TLS 协议版本写入 HTTP 头 xForwardedTLSCipher: true # X-Forwarded-TLS-Cipher：将 TLS 加密套件写入 HTTP 头 xForwardedELBIP: true # X-Forwarded-ELB-IP：将弹性公网 IP 写入 HTTP 头 xForwardedELBID: true # X-Forwarded-ELB-ID：将负载均衡实例 ID 写入 HTTP 头 ``` #### ListenerConfiguration参数说明 ![](https://support.huaweicloud.com/usermanual-cce/public_sys-resources/caution_3.0-zh-cn.png) 非必填**或** 无默认值的字段，若**不填/未指定（即null或省略该字段）** ，系统均默认为**保持已有配置不变**，实际状态以ELB侧现有配置为准。只有显式传入新值（如传入空列表"\[\]"进行清空）时才会触发更新。 表1lsconfig Spec | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | targetRef | 是 | [PolicyTargetRef] object | 目标资源，Gateway或Listener引用。 | | defaultServerCertificate | 否 | [CertificateRef] object | TLS监听器默认服务端证书，SNI匹配失败或未提供SNI时使用，参考HTTPS监听器证书配置。 | | sniCertificates | 否 | Array of [SNICertificateRef] objects | SNI证书列表，按域名匹配，参考HTTPS监听器证书配置。 | | http2Enable | 否 | Boolean | 表示HTTP/2功能的开启状态。开启后，可提升客户端与ELB间的访问性能，但ELB与后端服务器间仍采用HTTP1.X协议。参考开启HTTP/2协议。 取值范围： - true：开启HTTP/2功能。 - false：关闭HTTP/2功能（默认为关闭状态）。 注意：只有当监听器的协议为HTTPS时，才支持开启或关闭HTTP/2功能。当监听器的协议为HTTP时，该字段无效，默认将其设置为false。 | | tlsCiphersPolicy | 否 | String | 系统TLS加密策略，默认tls-1-2，非TLS监听器忽略。 | | securityPolicyID | 否 | String | 自定义安全策略ID，优先级高于tlsCiphersPolicy，仅独享型ELB。 | | clientCACertID | 否 | String | 客户端CA证书ELB ID，空表示单向TLS，参考HTTPS监听器证书配置。 | | keepaliveTimeout | 否 | Integer | 客户端连接空闲超时，单位秒，参考[配置超时时间]。 | | clientTimeout | 否 | Integer | 客户端请求超时，单位秒，0表示不设置，参考[配置超时时间]。 | | memberTimeout | 否 | Integer | 后端服务器响应超时，单位秒，0表示不设置，参考[配置超时时间]。 | | ipACL | 否 | [IPACL] object | IP访问控制配置，不配置表示无ACL，仅独享型生效，参考[配置监听器访问控制策略（黑/白名单）]。 | | insertHeaders | 否 | [InsertHeaders] object | 控制哪些由ELB生成的头部信息会被插入到转发给后端的请求中。仅独享型ELB生效；共享型ELB会忽略此字段。参考[配置HTTP/HTTPS头字段]。 | | gzipEnable | 否 | Boolean | 是否启用gzip压缩，仅独享型ELB生效；共享型ELB会忽略此字段。 | | routePriorities | 否 | Array of [RoutePriority] objects | 监听器路由显式优先级排序，列表顺序决定优先级（第一位=最高），参考[配置转发策略优先级]。 | | reclaimPolicy | 否 | String | 当关联的目标资源（如Gateway、ListenerSet或其内部的Listener）被删除时lsconfig的回收策略。无论选择哪种策略，绑定的底层云资源都将被释放。 - Retain：保留lsconfig资源本身，需要显式手动删除。 - DeleteWhenOrphaned（默认）：自动级联删除lsconfig资源。 | 表2PolicyTargetRef（ListenerConfiguration与PoolConfiguration共用） | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | group | 是 | String | 目标资源API Group。 | | kind | 是 | String | 目标资源Kind，如Gateway（ListenerConfiguration）或Service（PoolConfiguration）。 | | name | 是 | String | 目标资源名称。 | | sectionName | 否 | String | 目标资源内section名称，如Gateway的Listener名称、Service的端口名称。 | 表3CertificateRef | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | certificateID | 否 | String | ELB证书ID，与secretRef互斥。 | | secretRef | 否 | [SecretRef] object | Secret证书信息。 | 表4SecretRef（CertificateRef和SNICertificateRef共用） | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | Secret名称。 | 表5SNICertificateRef | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | domain | 否 | String | SNI匹配域名，如example.com、\*.example.com。配置secretRef时必填。 | | certificateID | 否 | String | ELB证书ID，与secretRef互斥。 | | secretRef | 否 | [SecretRef] object | Secret证书信息。 | 表6IPACL | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | enable | 否 | Boolean | 是否启用IP访问控制，设置ipGroupID时默认true。 | | type | 否 | String | ACL类型，取值white（白名单）、black（黑名单），默认white。 | | ipGroupIDs | 否 | Array of strings | 预创建的ELB IP地址组ID列表。 | 表7InsertHeaders | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | xForwardedPort | 否 | Boolean | ELB可通过X-Forwarded-Port请求头字段将监听器的端口号写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedForPort | 否 | Boolean | ELB可通过X-Forwarded-For-Port请求头字段将客户端请求的端口号写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedHost | 否 | Boolean | ELB可通过X-Forwarded-Host请求头字段将客户端请求的Host传递到后端服务器。 - true：开启重写，ELB以客户端请求头的Host重写X-Forwarded-Host。 - false：关闭重写，ELB透传客户端的X-Forwarded-Host。 | | xRealIP | 否 | Boolean | ELB可通过X-Real-IP请求头字段将客户端的源IP地址传递到后端服务器。 - true：开启重写，ELB以客户端的源IP地址重写X-Real-IP。 - false：关闭重写，ELB透传客户端的X-Real-IP。 | | xForwardedProto | 否 | Boolean | ELB可通过X-Forwarded-Proto请求头字段将客户端请求协议写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedTLSCertificateID | 否 | Boolean | ELB可通过X-Forwarded-TLS-Certificate-ID请求头字段将TLS证书ID写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedTLSProtocol | 否 | Boolean | ELB可通过X-Forwarded-TLS-Protocol请求头字段将TLS协议版本写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedTLSCipher | 否 | Boolean | ELB可通过X-Forwarded-TLS-Cipher请求头字段将TLS加密套件写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedELBIP | 否 | Boolean | ELB可通过X-Forwarded-ELB-IP请求头字段将弹性公网IP写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | | xForwardedELBID | 否 | Boolean | ELB可通过X-Forwarded-ELB-ID请求头字段将负载均衡实例ID写入HTTP头传递到后端服务器。 - true：开启。 - false：关闭。 | 表8RoutePriority | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | routeRef | 是 | [RouteRef] object | 引用的Route（HTTPRoute、GRPCRoute等）。 | 表9RouteRef | 参数 | 是否必填 | 参数类型 | 描述 | |:---|:---|:---|:---| | group | 否 | String | Route API Group，默认gateway.networking.k8s.io。 | | kind | 否 | String | Route Kind，默认HTTPRoute。 | | name | 是 | String | Route名称。 |