创建监听器
功能介绍
创建监听器。
接口约束
1.负载均衡器只有四层规格的,只支持创建TCP,UDP和TLS的监听器。
2.负载均衡器只有七层规格的,只支持创建HTTP、HTTPS和QUIC的监听器。
3.负载均衡器既有四层规格也有七层规格,那么支持创建TCP、UDP、TLS、HTTP、HTTPS和QUIC的监听器。
调用方法
请参见如何调用API。
URI
POST /v3/{project_id}/elb/listeners
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
project_id |
是 |
String |
参数解释:项目ID。 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
X-Auth-Token |
是 |
String |
参数解释:IAM鉴权Token。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
listener |
是 |
CreateListenerOption object |
参数解释:监听器对象。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
admin_state_up |
否 |
Boolean |
参数解释:监听器的管理状态。 约束限制:只支持设置为true。 |
default_pool_id |
否 |
String |
参数解释:监听器默认的后端服务器组ID。当请求没有匹配的转发策略时,转发到默认后端服务器上处理。 |
client_ca_tls_container_ref |
否 |
String |
参数解释:监听器使用的CA证书ID。 约束限制:
|
default_tls_container_ref |
否 |
String |
参数解释:监听器使用的服务器证书ID。 约束限制:当监听器协议为HTTPS、TLS或QUIC时,该字段必传,且对应的证书的type必须是server类型。 |
description |
否 |
String |
参数解释:监听器的描述信息。 |
http2_enable |
否 |
Boolean |
参数解释:客户端与LB之间的HTTPS请求的HTTP2功能的开启状态。 开启后,可提升客户端与LB间的访问性能,但LB与后端服务器间仍采用HTTP1.X协议。 约束限制:
|
insert_headers |
否 |
ListenerInsertHeaders object |
可选的HTTP头插入,可以将从负载均衡器到后端服务器的路径中需要被后端服务器用到的信息写入HTTP中,随报文传递到后端服务器。例如可通过X-Forwarded-ELB-IP开关,将负载均衡器的弹性公网IP传到后端服务器。 |
loadbalancer_id |
是 |
String |
参数解释:监听器所属的负载均衡器的ID列表。 约束限制: 一个监听器只支持关联到一个LB。 |
name |
否 |
String |
参数解释:监听器的名称。 注意:若名称为空,则在控制台的监听器列表无法选择并查看监听器详情。 |
project_id |
否 |
String |
参数解释:监听器所在的项目ID。 |
protocol |
是 |
String |
参数解释:监听器的监听协议。 约束限制:
取值范围:TCP、UDP、HTTP、HTTPS、TERMINATED_HTTPS、QUIC、TLS。 |
protocol_port |
否 |
Integer |
参数解释:监听器的监听端口。 约束限制:
|
sni_container_refs |
否 |
Array of strings |
参数解释:监听器使用的SNI证书(带域名的服务器证书)ID列表。 约束限制:
|
sni_match_algo |
否 |
String |
参数解释:监听器使用的SNI证书泛域名匹配方式。 取值范围:
默认取值:wildcard。 |
tags |
否 |
Array of Tag objects |
参数解释:标签列表 |
tls_ciphers_policy |
否 |
String |
参数解释:监听器使用的安全策略。 约束限制:
取值范围:tls-1-0-inherit、tls-1-0、tls-1-1、 tls-1-2、tls-1-2-strict、tls-1-2-fs、tls-1-0-with-1-3、 tls-1-2-fs-with-1-3、 hybrid-policy-1-0、tls-1-2-strict-no-cbc,默认:tls-1-2。 |
security_policy_id |
否 |
String |
参数解释:自定义安全策略的ID。 约束限制:
|
enable_member_retry |
否 |
Boolean |
参数解释:是否开启后端服务器的重试。 约束限制:
取值范围:true 开启重试,false 不开启重试。默认:true。 |
keepalive_timeout |
否 |
Integer |
参数解释:客户端连接空闲超时时间。在超过keepalive_timeout时长一直没有请求,负载均衡会暂时中断当前连接,直到下一次请求时重新建立新的连接。 约束限制:共享型实例的UDP监听器不支持此字段。 取值范围:
|
client_timeout |
否 |
Integer |
参数解释:等待客户端请求超时时间,包括两种情况:
约束限制:仅协议为HTTP/HTTPS的监听器支持该字段。 取值范围: 1-300s。 默认取值:60s。 |
member_timeout |
否 |
Integer |
参数解释:等待后端服务器响应超时时间。请求转发后端服务器后,在等待超时member_timeout时长没有响应,负载均衡将终止等待,并返回HTTP504错误码。 约束限制:仅支持协议为HTTP/HTTPS的监听器。 取值范围:1-300s。 默认取值:60s。 |
ipgroup |
否 |
CreateListenerIpGroupOption object |
监听器对象中的控制组(ipgroup)信息,可以不传或传null或{},表示监听器不绑定访问控制组。 若需要绑定访问控制组,则ipgroup_id是必须的。 |
transparent_client_ip_enable |
否 |
Boolean |
参数解释:是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。 约束限制:
取值范围:
|
proxy_protocol_enable |
否 |
Boolean |
参数解释:是否开启proxy_protocol。 约束限制:仅TLS监听器可指定,其他协议的监听器该字段不生效,proxy_protocol不开启。 |
enhance_l7policy_enable |
否 |
Boolean |
参数解释:是否开启高级转发策略功能。开启高级转发策略后,支持更灵活的转发策略和转发规则设置。 开启后支持如下场景:
约束限制:
取值范围:true开启,false不开启,默认false。 |
quic_config |
否 |
参数解释:当前监听器关联的QUIC监听器配置信息。 约束限制:
客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。 如果服务端监听器开启了升级QUIC,那么就会在响应头中加入服务端支持的QUIC端口和版本信息。 客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求,若QUIC请求成功,则后续继续使用QUIC交互。 |
|
cps |
否 |
Integer |
参数解释:监听器新建限速。 约束限制:当该限速值大于LB的限速值时,以LB的限速值生效 取值范围:0-1000000 默认取值:0,表示不限速。 |
connection |
否 |
Integer |
参数解释:监听器并发限速 约束限制:当该限速值大于LB的限速值时,以LB的限速值生效 取值范围:0-1000000 默认取值:0,表示不限速。 |
nat64_enable |
否 |
Boolean |
参数解释: 监听器地址族转换能力开关,可以实现客户端通过访问LB的IPv4或者IPv6地址,来访问IPv4后端和IPv6后端。 约束限制: 仅对于TCP、UDP协议类型的监听器生效,与transparent_client_ip_enable,获取客户端ip功能开关互斥,开启地址族转换同时需要保证获取客户端ip功能关闭。 取值范围:
默认取值:false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
X-Forwarded-ELB-IP |
否 |
Boolean |
参数解释:X-Forwarded-ELB-IP设为true可以将ELB实例的eip地址从报文的http头中带到后端服务器。 |
X-Forwarded-Port |
否 |
Boolean |
参数解释:X-Forwarded-Port设为true可以将ELB实例的监听端口从报文的http头中带到后端服务器。 |
X-Forwarded-For-Port |
否 |
Boolean |
X-Forwarded-For-Port设为true可以将客户端的源端口从报文的http头中带到后端服务器。 |
X-Forwarded-Host |
否 |
Boolean |
参数解释:X-Forwarded-Host设为true可以将客户请求头的X-Forwarded-Host设置为请求头的Host带到后端服务器。 |
X-Forwarded-Proto |
否 |
Boolean |
参数解释:X-Forwarded-Proto设为true可以将负载均衡器实例的监听协议通过报文的http头带到后端服务器。 |
X-Real-IP |
否 |
Boolean |
参数解释:X-Real-IP设为true可以将客户端的IP通过报文的http头带到后端服务器。 |
X-Forwarded-ELB-ID |
否 |
Boolean |
参数解释:X-Forwarded-ELB-ID设为true可以将负载均衡器实例的ID通过报文的http头带到后端服务器。 |
X-Forwarded-TLS-Certificate-ID |
否 |
Boolean |
参数解释:X-Forwarded-TLS-Certificate-ID设为true可以将负载均衡器实例的证书ID通过报文的http头带到后端服务器。 |
X-Forwarded-TLS-Protocol |
否 |
Boolean |
参数解释:X-Forwarded-TLS-Protocol设为true可以将负载均衡器实例的算法协议通过报文的http头带到后端服务器。 |
X-Forwarded-TLS-Cipher |
否 |
Boolean |
参数解释:X-Forwarded-TLS-Cipher设为true可以将负载均衡器实例的算法套件通过报文的http头带到后端服务器。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
ipgroup_id |
是 |
String |
参数解释:监听器关联的访问控制组的id。 约束限制:
|
enable_ipgroup |
否 |
Boolean |
参数解释:访问控制组的状态。 取值范围:
|
type |
否 |
String |
参数解释:访问控制组的类型。 取值范围:
默认取值:white |
响应参数
状态码:201
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
参数解释:请求ID。 注:自动生成 。 |
listener |
Listener object |
参数解释:监听器对象。 |
参数 |
参数类型 |
描述 |
---|---|---|
admin_state_up |
Boolean |
参数解释:监听器的管理状态。 |
client_ca_tls_container_ref |
String |
参数解释:监听器使用的CA证书ID。 约束限制:当且仅当type=client时,才会使用该字段对应的证书。 |
connection_limit |
Integer |
参数解释:监听器的最大连接数。 取值范围:-1表示不限制。 默认取值:-1。 不支持该字段,请勿使用。 |
created_at |
String |
参数解释:监听器的创建时间。 取值范围: 格式:yyyy-MM-dd'T'HH:mm:ss'Z',如:2021-07-30T12:03:44Z |
default_pool_id |
String |
参数解释:监听器的默认后端服务器组ID。当请求没有匹配的转发策略时,转发到默认后端服务器上处理。 |
default_tls_container_ref |
String |
参数解释:监听器使用的服务器证书ID。 |
description |
String |
参数解释:监听器的描述信息。 |
http2_enable |
Boolean |
参数解释:客户端与LB之间的HTTPS请求的HTTP2功能的开启状态。 开启后,可提升客户端与LB间的访问性能,但LB与后端服务器间仍采用HTTP1.X协议。 约束限制:
|
id |
String |
参数解释:监听器ID。 |
insert_headers |
ListenerInsertHeaders object |
可选的HTTP头插入,可以将从负载均衡器到后端服务器的路径中需要被后端服务器用到的信息写入HTTP中,随报文传递到后端服务器。例如可通过X-Forwarded-ELB-IP开关,将负载均衡器的弹性公网IP传到后端服务器。 |
loadbalancers |
Array of LoadBalancerRef objects |
参数解释:监听器所属的负载均衡器的ID列表。 约束限制:一个监听器只支持关联到一个LB。 |
name |
String |
参数解释:监听器的名称。 约束限制:若名称为空,则在控制台的监听器列表无法选择并查看监听器详情。 |
project_id |
String |
参数解释:监听器所在的项目ID。 |
enterprise_project_id |
String |
参数解释:企业项目ID。 |
protocol |
String |
参数解释:监听器的监听协议。 取值范围:TCP、UDP、HTTP、HTTPS、TERMINATED_HTTPS、QUIC、TLS。 约束限制:
|
protocol_port |
Integer |
参数解释:监听器的监听端口。 约束限制:
|
sni_container_refs |
Array of strings |
参数解释:监听器使用的SNI证书(带域名的服务器证书)ID列表。 约束限制:
|
sni_match_algo |
String |
参数解释:监听器使用的SNI证书泛域名匹配方式。 取值范围:longest_suffix表示最长尾缀匹配;wildcard表示标准域名分级匹配。 默认取值:wildcard |
tags |
Array of Tag objects |
参数解释:标签列表。 |
updated_at |
String |
参数解释:监听器的更新时间。 取值范围: 格式:yyyy-MM-dd'T'HH:mm:ss'Z',如:2021-07-30T12:03:44Z |
tls_ciphers_policy |
String |
参数解释:监听器使用的安全策略。 取值范围:tls-1-0-inherit、tls-1-0、tls-1-1、 tls-1-2、tls-1-2-strict、tls-1-2-fs、tls-1-0-with-1-3、 tls-1-2-fs-with-1-3、 hybrid-policy-1-0、tls-1-2-strict-no-cbc,默认:tls-1-2。 约束限制:
|
security_policy_id |
String |
参数解释:自定义安全策略的ID。 约束限制:
|
enable_member_retry |
Boolean |
参数解释:是否开启后端服务器的重试。 约束限制:
取值范围:true 开启重试,false 不开启重试。 默认取值:true。 |
keepalive_timeout |
Integer |
参数解释:客户端连接空闲超时时间。在超过keepalive_timeout时长一直没有请求,负载均衡会暂时中断当前连接,直到下一次请求时重新建立新的连接。 约束限制:共享型实例的UDP监听器不支持此字段。 取值范围:
|
client_timeout |
Integer |
参数解释:等待客户端请求超时时间,包括两种情况:
约束限制:仅协议为HTTP/HTTPS的监听器支持该字段。 取值范围:1-300s 默认取值:60s。 |
member_timeout |
Integer |
参数解释:等待后端服务器响应超时时间。请求转发后端服务器后,在等待超时member_timeout时长没有响应,负载均衡将终止等待,并返回HTTP504错误码。 约束限制:仅支持协议为HTTP/HTTPS的监听器。 取值范围:1-300s 默认取值:60s。 |
ipgroup |
ListenerIpGroup object |
listener对象中的ipgroup信息 |
transparent_client_ip_enable |
Boolean |
参数解释:是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。 仅作用于共享型LB的TCP/UDP监听器。 约束限制:
取值范围:
|
proxy_protocol_enable |
Boolean |
参数解释:是否开启proxy_protocol。仅TLS监听器可指定,其他协议的监听器该字段不生效,proxy_protocol不开启。 |
enhance_l7policy_enable |
Boolean |
参数解释:是否开启高级转发策略功能。开启高级转发策略后,支持更灵活的转发策略和转发规则设置。 开启后支持如下场景:
约束限制:
取值范围:true开启,false不开启。 默认取值:false。 |
quic_config |
ListenerQuicConfig object |
参数解释:当前监听器关联的QUIC监听器配置信息。 约束限制:仅protocol为HTTPS时有效。对于TCP/UDP/HTTP/QUIC监听器,若该字段非空则报错。 客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。 如果服务端监听器开启了升级QUIC,那么就会在响应头中加入服务端支持的QUIC端口和版本信息。 客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求,若QUIC请求成功,则后续继续使用QUIC交互。 |
cps |
Integer |
参数解释:监听器新建限速 约束限制:当该限速值大于LB的限速值时,以LB的限速值生效 取值范围:0-1000000 默认取值:0,表示不限速 |
connection |
Integer |
参数解释:监听器并发限速 约束限制:当该限速值大于LB的限速值时,以LB的限速值生效 取值范围:0-1000000 默认取值:0,表示不限速 |
nat64_enable |
Boolean |
参数解释: 监听器地址族转换能力开关,可以实现客户端通过访问LB的IPv4或者IPv6地址,来访问IPv4后端和IPv6后端。 约束限制: 仅对于TCP、UDP协议类型的监听器生效,与transparent_client_ip_enable,获取客户端ip功能开关互斥,开启地址族转换同时需要保证获取客户端ip功能关闭。 取值范围:
默认取值:false |
参数 |
参数类型 |
描述 |
---|---|---|
X-Forwarded-ELB-IP |
Boolean |
参数解释:X-Forwarded-ELB-IP设为true可以将ELB实例的eip地址从报文的http头中带到后端服务器。 |
X-Forwarded-Port |
Boolean |
参数解释:X-Forwarded-Port设为true可以将ELB实例的监听端口从报文的http头中带到后端服务器。 |
X-Forwarded-For-Port |
Boolean |
X-Forwarded-For-Port设为true可以将客户端的源端口从报文的http头中带到后端服务器。 |
X-Forwarded-Host |
Boolean |
参数解释:X-Forwarded-Host设为true可以将客户请求头的X-Forwarded-Host设置为请求头的Host带到后端服务器。 |
X-Forwarded-Proto |
Boolean |
参数解释:X-Forwarded-Proto设为true可以将负载均衡器实例的监听协议通过报文的http头带到后端服务器。 |
X-Real-IP |
Boolean |
参数解释:X-Real-IP设为true可以将客户端的IP通过报文的http头带到后端服务器。 |
X-Forwarded-ELB-ID |
Boolean |
参数解释:X-Forwarded-ELB-ID设为true可以将负载均衡器实例的ID通过报文的http头带到后端服务器。 |
X-Forwarded-TLS-Certificate-ID |
Boolean |
参数解释:X-Forwarded-TLS-Certificate-ID设为true可以将负载均衡器实例的证书ID通过报文的http头带到后端服务器。 |
X-Forwarded-TLS-Protocol |
Boolean |
参数解释:X-Forwarded-TLS-Protocol设为true可以将负载均衡器实例的算法协议通过报文的http头带到后端服务器。 |
X-Forwarded-TLS-Cipher |
Boolean |
参数解释:X-Forwarded-TLS-Cipher设为true可以将负载均衡器实例的算法套件通过报文的http头带到后端服务器。 |
参数 |
参数类型 |
描述 |
---|---|---|
ipgroup_id |
String |
参数解释:监听器关联的访问控制组的id。 创建时必选,更新时非必选。 约束限制: 指定的ipgroup必须已存在,不能指定为null,否则与enable_ipgroup冲突。 |
enable_ipgroup |
Boolean |
参数解释:访问控制组的状态。 开启访问控制的监听器,允许直接删除。 取值范围:
|
type |
String |
参数解释:访问控制组的类型。 取值范围:
|
请求示例
-
示例1:创建protocol为TCP的监听器。
POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners { "listener" : { "protocol_port" : 80, "protocol" : "TCP", "loadbalancer_id" : "098b2f68-af1c-41a9-8efd-69958722af62", "name" : "My listener", "admin_state_up" : true, "insert_headers" : { "X-Forwarded-ELB-IP" : true } } }
-
示例2:创建protocol为HTTPS的监听器。
POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners { "listener" : { "protocol_port" : 90, "protocol" : "HTTPS", "loadbalancer_id" : "098b2f68-af1c-41a9-8efd-69958722af62", "name" : "My listener", "admin_state_up" : true, "ipgroup" : { "ipgroup_id" : "0416b6f1-877f-4a51-987e-978b3f083542", "type" : "black" }, "security_policy_id" : "8722e0e0-9cc9-4490-9660-8c9a5732fbb0", "default_tls_container_ref" : "233a325e5e3e4ce8beeb320aa714cc12" } }
响应示例
状态码:201
POST操作正常返回。
{ "listener" : { "id" : "0b11747a-b139-492f-9692-2df0b1c87193", "name" : "My listener", "protocol_port" : 80, "protocol" : "TCP", "description" : null, "default_tls_container_ref" : null, "admin_state_up" : true, "loadbalancers" : [ { "id" : "098b2f68-af1c-41a9-8efd-69958722af62" } ], "client_ca_tls_container_ref" : null, "project_id" : "99a3fff0d03c428eac3678da6a7d0f24", "sni_container_refs" : [ ], "connection_limit" : -1, "member_timeout" : null, "client_timeout" : null, "keepalive_timeout" : null, "default_pool_id" : null, "ipgroup" : null, "tls_ciphers_policy" : "tls-1-2", "tags" : [ ], "created_at" : "2019-04-02T00:12:32Z", "updated_at" : "2019-04-02T00:12:32Z", "http2_enable" : false, "enable_member_retry" : true, "insert_headers" : { "X-Forwarded-ELB-IP" : true }, "transparent_client_ip_enable" : false, "nat64_enable" : false }, "request_id" : "f4c4aca8-df16-42e8-8836-33e4b8e9aa8e" }
状态码
状态码 |
描述 |
---|---|
201 |
POST操作正常返回。 |
错误码
请参见错误码。