创建监听器
功能介绍
创建监听器。
接口约束
1.负载均衡器只有四层规格的,只支持创建TCP,UDP的监听器。
2.负载均衡器只有七层规格的,只支持创建HTTP、HTTPS和QUIC的监听器。
3.负载均衡器既有四层规格也有七层规格,那么支持创建TCP、UDP、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。当请求没有匹配的转发策略时,转发到默认后端云服务器上处理。 最小长度:1 最大长度:36 |
client_ca_tls_container_ref |
否 |
String |
监听器使用的CA证书ID。当且仅当type=client时,才会使用该字段对应的证书。 监听器协议为QUIC时不支持该字段。 最小长度:1 最大长度:128 |
default_tls_container_ref |
否 |
String |
监听器使用的服务器证书ID。 使用说明:当监听器协议为HTTPS时,该字段必传,且对应的证书的type必须是server类型。 最小长度:1 最大长度:128 |
description |
否 |
String |
监听器的描述信息。 最小长度:0 最大长度:255 |
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。 最小长度:1 最大长度:36 |
name |
否 |
String |
监听器的名称。 注意:若名称为空,则在控制台的监听器列表无法选择并查看监听器详情。 最小长度:0 最大长度:255 |
project_id |
否 |
String |
监听器所在的项目ID。 最小长度:1 最大长度:32 |
protocol |
是 |
String |
监听器的监听协议。 取值:TCP、UDP、HTTP、HTTPS、TERMINATED_HTTPS、QUIC、TCPSSL。 使用说明:
required: false |
protocol_port |
否 |
Integer |
监听器的监听端口。QUIC监听器端口不能是4789,且不能和UDP监听器端口重复。传0时表示开启监听端口范围的能力,此时port_ranges为必填字段。 最小值:0 最大值:65535 |
sni_container_refs |
否 |
Array of strings |
监听器使用的SNI证书(带域名的服务器证书)ID列表。 使用说明:
数组长度:0 - 50 |
sni_match_algo |
否 |
String |
监听器使用的SNI证书泛域名匹配方式。 longest_suffix表示最长尾缀匹配,wildcard表示标准域名分级匹配。 默认为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-0。 使用说明:
|
security_policy_id |
否 |
String |
自定义安全策略的ID。 使用说明:
最小长度:1 最大长度:36 |
enable_member_retry |
否 |
Boolean |
是否开启后端服务器的重试。 取值:true 开启重试,false 不开启重试。默认:true。 使用说明:
|
keepalive_timeout |
否 |
Integer |
客户端连接空闲超时时间。在超过keepalive_timeout时长一直没有请求, 负载均衡会暂时中断当前连接,直到下一次请求时重新建立新的连接。 取值:
共享型实例的UDP监听器不支持此字段。 |
client_timeout |
否 |
Integer |
等待客户端请求超时时间,包括两种情况:
取值范围为1-300s,默认值为60s。 使用说明:仅协议为HTTP/HTTPS的监听器支持该字段。 最小值:1 最大值:300 缺省值:60 |
member_timeout |
否 |
Integer |
等待后端服务器响应超时时间。请求转发后端服务器后,在等待超时member_timeout时长没有响应,负载均衡将终止等待,并返回 HTTP504错误码。 取值:1-300s,默认为60s。 使用说明:仅支持协议为HTTP/HTTPS的监听器。 最小值:1 最大值:300 缺省值:60 |
ipgroup |
否 |
CreateListenerIpGroupOption object |
监听器对象中的控制组(ipgroup)信息,可以不传或传null或{},表示监听器不绑定访问控制组。 若需要绑定访问控制组,则ipgroup_id是必须的。 |
transparent_client_ip_enable |
否 |
Boolean |
是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。 仅作用于共享型LB的TCP/UDP监听器。 取值:
使用说明:
|
proxy_protocol_enable |
否 |
Boolean |
是否开启proxy_protocol。仅tcpssl监听器可指定,其他协议的监听器该字段不生效,proxy_protocol不开启。 |
enhance_l7policy_enable |
否 |
Boolean |
是否开启高级转发策略功能。开启高级转发策略后,支持更灵活的转发策略和转发规则设置。 取值:true开启,false不开启,默认false。 开启后支持如下场景:
说明:
开启后不支持关闭 |
quic_config |
否 |
当前监听器关联的QUIC监听器配置信息,仅protocol为HTTPS时有效。 对于TCP/UDP/HTTP/QUIC监听器,若该字段非空则报错。
说明:
客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。 如果服务端监听器开启了升级QUIC,那么就会在响应头中加入服务端支持的QUIC端口和版本信息。 客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求,若QUIC请求成功,则后续继续使用QUIC交互。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
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中的ip_list为[],且类型为白名单时,表示禁止所有ip的访问。 当关联的ipgroup中的ip_list为[],且类型为黑名单时,表示允许所有ip的访问。 最小长度:1 最大长度:36 |
enable_ipgroup |
否 |
Boolean |
访问控制组的状态。 取值:
|
type |
否 |
String |
访问控制组的类型。
|
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
quic_listener_id |
是 |
String |
监听器关联的QUIC监听器ID。指定的listener id必须已存在,且协议类型为QUIC,不能指定为null,否则与enable_quic_upgrade冲突。 |
enable_quic_upgrade |
否 |
Boolean |
QUIC升级的开启状态。 True:开启QUIC升级; Flase:关闭QUIC升级(默认)。 开启HTTPS监听器升级QUIC监听器能力。 缺省值:false |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
start_port |
否 |
Integer |
起始端口 最小值:1 最大值:65535 |
end_port |
否 |
Integer |
结束端口,需大于等于起始端口 最小值:1 最大值:65535 |
响应参数
状态码: 201
参数 |
参数类型 |
描述 |
---|---|---|
request_id |
String |
请求ID。 注:自动生成 。 |
listener |
Listener object |
监听器对象。 |
参数 |
参数类型 |
描述 |
---|---|---|
admin_state_up |
Boolean |
监听器的管理状态。只能设置为true。 不支持该字段,请勿使用。 |
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。 |
protocol |
String |
监听器的监听协议。 取值:TCP、UDP、HTTP、HTTPS、TERMINATED_HTTPS、QUIC、TCPSSL。 使用说明:
|
protocol_port |
Integer |
监听器的监听端口。QUIC监听器端口不能是4789,且不能和UDP监听器端口重复。传0时表示开启监听端口范围的能力,此时port_ranges为必填字段。 最小值:0 最大值:65535 |
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-0。 使用说明:
|
security_policy_id |
String |
自定义安全策略的ID。 使用说明:
|
enable_member_retry |
Boolean |
是否开启后端服务器的重试。 取值:true 开启重试,false 不开启重试。默认:true。 使用说明:
|
keepalive_timeout |
Integer |
客户端连接空闲超时时间。在超过keepalive_timeout时长一直没有请求, 负载均衡会暂时中断当前连接,直到下一次请求时重新建立新的连接。 取值:
共享型实例的UDP监听器不支持此字段。 |
client_timeout |
Integer |
等待客户端请求超时时间,包括两种情况:
取值范围为1-300s,默认值为60s。 使用说明:仅协议为HTTP/HTTPS的监听器支持该字段。 |
member_timeout |
Integer |
等待后端服务器响应超时时间。请求转发后端服务器后,在等待超时member_timeout时长没有响应,负载均衡将终止等待,并返回 HTTP504错误码。 取值:1-300s,默认为60s。 使用说明:仅支持协议为HTTP/HTTPS的监听器。 |
ipgroup |
ListenerIpGroup object |
listener对象中的ipgroup信息 |
transparent_client_ip_enable |
Boolean |
是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。 仅作用于共享型LB的TCP/UDP监听器。 取值:
使用说明:
|
proxy_protocol_enable |
Boolean |
是否开启proxy_protocol。仅tcpssl监听器可指定,其他协议的监听器该字段不生效,proxy_protocol不开启。 |
enhance_l7policy_enable |
Boolean |
是否开启高级转发策略功能。开启高级转发策略后,支持更灵活的转发策略和转发规则设置。 取值:true开启,false不开启,默认false。 开启后支持如下场景:
缺省值:false |
quic_config |
ListenerQuicConfig object |
当前监听器关联的QUIC监听器配置信息,仅protocol为HTTPS时有效。 对于TCP/UDP/HTTP/QUIC监听器,若该字段非空则报错。
说明:
客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。 如果服务端监听器开启了升级QUIC,那么就会在响应头中加入服务端支持的QUIC端口和版本信息。 客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求,若QUIC请求成功,则后续继续使用QUIC交互。 |
参数 |
参数类型 |
描述 |
---|---|---|
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 |
访问控制组的状态。 True:开启访问控制; Flase:关闭访问控制; 开启访问控制的监听器,允许直接删除。 |
type |
String |
访问控制组的类型。 white:白名单,只允许指定ip访问; black:黑名单,不允许指定ip访问; |
参数 |
参数类型 |
描述 |
---|---|---|
quic_listener_id |
String |
监听器关联的QUIC监听器ID。 创建时必选,更新时非必选。 指定的listener id必须已存在,且协议类型为QUIC,不能指定为null,否则与enable_quic_upgrade冲突。 |
enable_quic_upgrade |
Boolean |
QUIC升级的开启状态。 True:开启QUIC升级; Flase:关闭QUIC升级; 开启HTTPS监听器升级QUIC监听器能力 |
参数 |
参数类型 |
描述 |
---|---|---|
start_port |
Integer |
起始端口 最小值:1 最大值:65535 |
end_port |
Integer |
结束端口,需大于等于起始端口 最小值:1 最大值:65535 |
请求示例
-
示例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-0", "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 }, "request_id" : "f4c4aca8-df16-42e8-8836-33e4b8e9aa8e" }
状态码
状态码 |
描述 |
---|---|
201 |
POST操作正常返回。 |
错误码
请参见错误码。