Adding a Listener¶

Function¶

This API is used to add a listener to a load balancer.

Constraints¶

The protocol used by the listener can be TCP, UDP, HTTP, or HTTPS.

For load balancing at Layer 4, the protocol can only be TCP or UDP.
For load balancing at Layer 7, the protocol can only be HTTP or HTTPS.
For load balancing both at Layer 4 and Layer 7, TCP, UDP, HTTP, and HTTPS are supported.

URI¶

POST /v3/{project_id}/elb/listeners

**Table 1** Path Parameters¶
Parameter	Mandatory	Type	Description
project_id	Yes	String	Specifies the project ID.

Request Parameters¶

**Table 2** Request header parameters¶
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Specifies the token used for IAM authentication.

**Table 3** Request body parameters¶
Parameter	Mandatory	Type	Description
listener	Yes	CreateListenerOption object	Specifies the listener.

**Table 4** CreateListenerOption¶
Parameter	Mandatory	Type	Description
admin_state_up	No	Boolean	Specifies the administrative status of the listener. The value can only be true. This parameter is unsupported. Please do not use it.
default_pool_id	No	String	Specifies the ID of the default backend server group. If there is no matched forwarding policy, requests will be forwarded to the default backend server for processing. Minimum: 1 Maximum: 36
client_ca_tls_container_ref	No	String	Specifies the ID of the CA certificate used by the listener. This parameter is available only when type is set to client. Minimum: 1 Maximum: 128
default_tls_container_ref	No	String	Specifies the ID of the server certificate used by the listener. This parameter is available only when the listener's protocol is HTTPS and type is set to server. Minimum: 1 Maximum: 128
description	No	String	Provides supplementary information about the listener. Minimum: 0 Maximum: 255
http2_enable	No	Boolean	Specifies whether to use HTTP/2 if you want the clients to use HTTP/2 to communicate with the load balancer. However, connections between the load balancer and backend servers still use HTTP/1.x by default. This parameter is available only for HTTPS listeners. If you configure this parameter for listeners with other protocols, it will not take effect.
insert_headers	No	ListenerInsertHeaders object	Specifies the HTTP header fields that can transmit required information to backend servers. For example, the X-Forwarded-ELB-IP header field can transmit the EIP of the load balancer to backend servers.
loadbalancer_id	Yes	String	Specifies the ID of the load balancer that the listener is added to. Note: A listener can be added to only one load balancer. Minimum: 1 Maximum: 36
name	No	String	Specifies the listener name. Minimum: 0 Maximum: 255
project_id	No	String	Specifies the project ID. Minimum: 1 Maximum: 32
protocol	Yes	String	Specifies the protocol used by the listener. The value can be TCP, HTTP, UDP, HTTPS or TERMINATED_HTTPS. Note: Protocol used by HTTPS listeners added to a shared load balancer can only be set to TERMINATED_HTTPS. If HTTPS is passed, the value will be automatically changed to TERMINATED_HTTPS. Protocol used by HTTPS listeners added to a dedicated load balancer can only be set to HTTPS. If TERMINATED_HTTPS is passed, the value will be automatically changed to HTTPS.
protocol_port	Yes	Integer	Specifies the protocol used by the listener. Minimum: 1 Maximum: 65535
sni_container_refs	No	Array of strings	Specifies the IDs of SNI certificates (server certificates with domain names) used by the listener. Note: The domain names of all SNI certificates must be unique. The total number of domain names of all SNI certificates cannot exceed 30. Array Length: 0 - 30
sni_match_algo	No	String	Specifies how wildcard domain name matches with the SNI certificates used by the listener. longest_suffix indicates longest suffix match. wildcard indicates wildcard match. The default value is wildcard.
tags	No	Array of Tag objects	Lists the tags.
tls_ciphers_policy	No	String	Specifies the security policy used by the listener. Values: 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, and tls-1-0 (default). Note: This parameter will take effect only for HTTPS listeners added to a dedicated load balancer. If both security_policy_id and tls_ciphers_policy are specified, only security_policy_id will take effect. The priority of the encryption suite from high to low is: ecc suite, rsa suite, tls 1.3 suite (supporting both ecc and rsa).
security_policy_id	No	String	Specifies the ID of the custom security policy. Note: This parameter will take effect only for HTTPS listeners added to a dedicated load balancer. If both security_policy_id and tls_ciphers_policy are specified, only security_policy_id will take effect. The priority of the encryption suite from high to low is: ecc suite, rsa suite, tls 1.3 suite (supporting both ecc and rsa). Minimum: 1 Maximum: 36
enable_member_retry	No	Boolean	Specifies whether to enable health check retries for backend servers. The value can be true (enable health check retries) or false (disable health check retries). The default value is true. Note: If a shared load balancer is associated, this parameter is available only when protocol is set to HTTP or TERMINATED_HTTPS. If a dedicated load balancer is associated, this parameter is available only when protocol is set to HTTP or HTTPS.
keepalive_timeout	No	Integer	Specifies the idle timeout duration, in seconds. If there are no requests reaching the load balancer after the idle timeout duration elapses, the load balancer will disconnect the connection with the client and establish a new connection when there is a new request. For TCP listeners, the value ranges from 10 to 4000, and the default value is 300. For HTTP and HTTPS listeners, the value ranges from 1 to 4000, and the default value is 60. For UDP listeners, this parameter does not take effect.
client_timeout	No	Integer	Specifies the timeout duration for waiting for a response from a client, in seconds. There are two situations: If the client fails to send a request header to the load balancer within the timeout duration, the request will be interrupted. If the interval between two consecutive request bodies reaching the load balancer is greater than the timeout duration, the connection will be disconnected. The value ranges from 1 to 300, and the default value is 60. This parameter is available only for HTTP and HTTPS listeners. Minimum: 1 Maximum: 300 Default: 60
member_timeout	No	Integer	Specifies the timeout duration for waiting for a response from a backend server, in seconds. If the backend server fails to respond after the timeout duration elapses, the load balancer will stop waiting and return HTTP 504 Gateway Timeout to the client. The value ranges from 1 to 300, and the default value is 60. This parameter is available only for HTTP and HTTPS listeners. Minimum: 1 Maximum: 300 Default: 60
ipgroup	No	CreateListenerIpGroupOption object	Specifies the IP address group associated with the listener.
transparent_client_ip_enable	No	Boolean	Specifies whether to pass source IP addresses of the clients to backend servers. TCP or UDP listeners of shared load balancers: The value can be true or false, and the default value is false if this parameter is not passed. HTTP or HTTPS listeners of shared load balancers: The value can only be true, and the default value is true if this parameter is not passed. All listeners of dedicated load balancers: The value can only be true, and the default value is true if this parameter is not passed. Note: If this function is enabled, the load balancer communicates with backend servers using their real IP addresses. Ensure that security group rules and access control policies are correctly configured. If this function is enabled, a server cannot serve as both a backend server and a client. If this function is enabled, backend server specifications cannot be changed.
enhance_l7policy_enable	No	Boolean	Specifies whether to enable advanced forwarding. If advanced forwarding is enabled, more flexible forwarding policies and rules are supported. The value can be true (enable advanced forwarding) or false (disable advanced forwarding), and the default value is false. The following scenarios are supported: action can be set to REDIRECT_TO_URL (requests will be redirected to another URL) or Fixed_RESPONSE (a fixed response body will be returned to clients). Parameters priority, redirect_url_config, and fixed_response_config can be specified in a forwarding policy. Parameter type can be set to METHOD, HEADER, QUERY_STRING, or SOURCE_IP for a forwarding rule. If type is set to HOST_NAME for a forwarding rule, the value parameter of the forwarding rule supports wildcard asterisks (``). The conditions* parameter can be specified for forwarding rules. Note Value false can't be used after this parameter was set to true.

**Table 5** ListenerInsertHeaders¶
Parameter	Mandatory	Type	Description
X-Forwarded-ELB-IP	No	Boolean	Specifies whether to transparently transmit the load balancer EIP to backend servers. If X-Forwarded-ELB-IP is set to true, the load balancer EIP will be stored in the HTTP header and passed to backend servers. Default: false
X-Forwarded-Port	No	Boolean	Specifies whether to transparently transmit the listening port of the load balancer to backend servers. If X-Forwarded-Port is set to true, the listening port of the load balancer will be stored in the HTTP header and passed to backend servers. Default: false
X-Forwarded-For-Port	No	Boolean	Specifies whether to transparently transmit the source port of the client to backend servers. If X-Forwarded-For-Port is set to true, the source port of the client will be stored in the HTTP header and passed to backend servers. Default: false
X-Forwarded-Host	No	Boolean	Specifies whether to rewrite the X-Forwarded-Host header. If X-Forwarded-Host is set to true, X-Forwarded-Host in the request header from the clients can be set to Host in the request header sent from the load balancer to backend servers. Default: true

**Table 6** Tag¶
Parameter	Mandatory	Type	Description
key	No	String	Specifies the tag key. Minimum: 1 Maximum: 36
value	No	String	Specifies the tag value. Minimum: 0 Maximum: 43

**Table 7** CreateListenerIpGroupOption¶
Parameter	Mandatory	Type	Description
ipgroup_id	Yes	String	Specifies the ID of the IP address group associated with the listener. If ip_list is set to an empty array [] and type to whitelist, no IP addresses are allowed to access the listener. If ip_list is set to an empty array [] and type to blacklist, any IP address is allowed to access the listener. Minimum: 1 Maximum: 36
enable_ipgroup	No	Boolean	Specifies whether to enable access control. true (default): Access control will be enabled. false: Access control will be disabled.
type	No	String	Specifies how access to the listener is controlled. white (default): A whitelist will be configured. Only IP addresses in the whitelist can access the listener. black: A blacklist will be configured. IP addresses in the blacklist are not allowed to access the listener.

Response Parameters¶

Status code: 201

**Table 8** Response body parameters¶
Parameter	Type	Description
request_id	String	Specifies the request ID. The value is automatically generated.
listener	Listener object	Specifies the listener.

**Table 9** Listener¶
Parameter	Type	Description
admin_state_up	Boolean	Specifies the administrative status of the listener. The value can only be true. This parameter is unsupported. Please do not use it.
client_ca_tls_container_ref	String	Specifies the ID of the CA certificate used by the listener. This parameter is available only when type is set to client.
connection_limit	Integer	Specifies the maximum number of connections that the load balancer can establish with backend servers. The value -1 indicates that the number of connections is not limited. This parameter is unsupported. Please do not use it.
created_at	String	Specifies the time when the listener was created, in the format of yyyy-MM-dd''T''HH:mm:ss''Z'', for example, 2021-07-30T12:03:44Z.
default_pool_id	String	Specifies the ID of the default backend server group. If there is no matched forwarding policy, requests are forwarded to the default backend server.
default_tls_container_ref	String	Specifies the ID of the server certificate used by the listener.
description	String	Provides supplementary information about the listener.
http2_enable	Boolean	Specifies whether to use HTTP/2 if you want the clients to use HTTP/2 to communicate with the listener. However, connections between the load balancer and backend servers still use HTTP/1.x by default. This parameter is available only for HTTPS listeners. If you configure this parameter for listeners with other protocols, it will not take effect.
id	String	Specifies the listener ID.
insert_headers	ListenerInsertHeaders object	Specifies the HTTP header fields that can transmit required information to backend servers. For example, the X-Forwarded-ELB-IP header field can transmit the EIP of the load balancer to backend servers.
loadbalancers	Array of LoadBalancerRef objects	Specifies the ID of the load balancer that the listener is added to. A listener can be added to only one load balancer.
name	String	Specifies the listener name.
project_id	String	Specifies the ID of the project where the listener is used.
protocol	String	Specifies the protocol used by the listener. The value can be TCP, HTTP, UDP, HTTPS or TERMINATED_HTTPS. Note: Protocol used by HTTPS listeners added to a shared load balancer can only be set to TERMINATED_HTTPS. If HTTPS is passed, the value will be automatically changed to TERMINATED_HTTPS. Protocol used by HTTPS listeners added to a dedicated load balancer can only be set to HTTPS. If TERMINATED_HTTPS is passed, the value will be automatically changed to HTTPS.
protocol_port	Integer	Specifies the port used by the listener to receive requests from clients. Minimum: 1 Maximum: 65535
sni_container_refs	Array of strings	Specifies the IDs of SNI certificates (server certificates with domain names) used by the listener. Note: The domain names of all SNI certificates must be unique. The total number of domain names of all SNI certificates cannot exceed 30.
sni_match_algo	String	Specifies how wildcard domain name matches with the SNI certificates used by the listener. longest_suffix indicates longest suffix match. wildcard indicates wildcard match. The default value is wildcard.
tags	Array of Tag objects	Lists the tags.
updated_at	String	Specifies the time when the listener was updated, in the format of yyyy-MM-dd''T''HH:mm:ss''Z'', for example, 2021-07-30T12:03:44Z.
tls_ciphers_policy	String	Specifies the security policy used by the listener. Values: 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, and tls-1-0 (default). Note: This parameter will take effect only for HTTPS listeners added to a dedicated load balancer. If both security_policy_id and tls_ciphers_policy are specified, only security_policy_id will take effect. The priority of the encryption suite from high to low is: ecc suite, rsa suite, tls 1.3 suite (supporting both ecc and rsa).
security_policy_id	String	Specifies the ID of the custom security policy. Note: This parameter will take effect only for HTTPS listeners added to a dedicated load balancer. If both security_policy_id and tls_ciphers_policy are specified, only security_policy_id will take effect. The priority of the encryption suite from high to low is: ecc suite, rsa suite, tls 1.3 suite (supporting both ecc and rsa).
enable_member_retry	Boolean	Specifies whether to enable health check retries for backend servers. The value can be true (enable health check retries) or false (disable health check retries). The default value is true. Note: If a shared load balancer is associated, this parameter is available only when protocol is set to HTTP or TERMINATED_HTTPS. If a dedicated load balancer is associated, this parameter is available only when protocol is set to HTTP or HTTPS.
keepalive_timeout	Integer	Specifies the idle timeout duration, in seconds. If there are no requests reaching the load balancer after the idle timeout duration elapses, the load balancer will disconnect the connection with the client and establish a new connection when there is a new request. For TCP listeners, the value ranges from 10 to 4000, and the default value is 300. For HTTP and HTTPS listeners, the value ranges from 1 to 4000, and the default value is 60. For UDP listeners, this parameter does not take effect.
client_timeout	Integer	Specifies the timeout duration for waiting for a response from a client, in seconds. There are two situations: If the client fails to send a request header to the load balancer within the timeout duration, the request will be interrupted. If the interval between two consecutive request bodies reaching the load balancer is greater than the timeout duration, the connection will be disconnected. The value ranges from 1 to 300, and the default value is 60. This parameter is available only for HTTP and HTTPS listeners.
member_timeout	Integer	Specifies the timeout duration for waiting for a response from a backend server, in seconds. If the backend server fails to respond after the timeout duration elapses, the load balancer will stop waiting and return HTTP 504 Gateway Timeout to the client. The value ranges from 1 to 300, and the default value is 60. This parameter is available only for HTTP and HTTPS listeners.
ipgroup	ListenerIpGroup object	Specifies the IP address group associated with the listener.
transparent_client_ip_enable	Boolean	Specifies whether to pass source IP addresses of the clients to backend servers. TCP or UDP listeners of shared load balancers: The value can be true or false, and the default value is false if this parameter is not passed. HTTP or HTTPS listeners of shared load balancers: The value can only be true, and the default value is true if this parameter is not passed. All listeners of dedicated load balancers: The value can only be true, and the default value is true if this parameter is not passed. Note: If this function is enabled, the load balancer communicates with backend servers using their real IP addresses. Ensure that security group rules and access control policies are correctly configured. If this function is enabled, a server cannot serve as both a backend server and a client. If this function is enabled, backend server specifications cannot be changed.
enhance_l7policy_enable	Boolean	Specifies whether to enable advanced forwarding. The value can be true (enable advanced forwarding) or false (disable advanced forwarding), and the default value is false. If this function is enabled, action can be set to REDIRECT_TO_URL (requests will be redirected to another URL) or Fixed_RESPONSE (a fixed response body will be returned to clients). Parameters priority, redirect_url_config, and fixed_response_config can be specified in a forwarding policy. Parameter type can be set to METHOD, HEADER, QUERY_STRING, or SOURCE_IP for a forwarding rule . If type is set to HOST_NAME for a forwarding rule, the value parameter of the forwarding rule supports wildcard asterisks (``). The conditions* parameter can be specified for forwarding rules. Note Value false can't be used after this parameter was set to true. Default: false
quic_config	ListenerQuicConfig object	Specifies the QUIC configuration for the current listener. This parameter is valid only when protocol is set to HTTPS. For a TCP/UDP/HTTP/QUIC listener, if this parameter is not left blank, an error will be reported. Note The client sends a normal HTTP request that contains information indicating that the QUIC protocol is supported. If QUIC upgrade is enabled for the listeners, QUIC port and version information will be added to the response header. When the client sends both HTTPS and QUIC requests to the server, if the QUIC request is successfully sent, QUIC protocol will be used for subsequent communications. QUIC protocol is not supported.

**Table 10** ListenerInsertHeaders¶
Parameter	Type	Description
X-Forwarded-ELB-IP	Boolean	Specifies whether to transparently transmit the load balancer EIP to backend servers. If X-Forwarded-ELB-IP is set to true, the load balancer EIP will be stored in the HTTP header and passed to backend servers. Default: false
X-Forwarded-Port	Boolean	Specifies whether to transparently transmit the listening port of the load balancer to backend servers. If X-Forwarded-Port is set to true, the listening port of the load balancer will be stored in the HTTP header and passed to backend servers. Default: false
X-Forwarded-For-Port	Boolean	Specifies whether to transparently transmit the source port of the client to backend servers. If X-Forwarded-For-Port is set to true, the source port of the client will be stored in the HTTP header and passed to backend servers. Default: false
X-Forwarded-Host	Boolean	Specifies whether to rewrite the X-Forwarded-Host header. If X-Forwarded-Host is set to true, X-Forwarded-Host in the request header from the clients can be set to Host in the request header sent from the load balancer to backend servers. Default: true

**Table 11** LoadBalancerRef¶
Parameter	Type	Description
id	String	Specifies the load balancer ID.

**Table 12** Tag¶
Parameter	Type	Description
key	String	Specifies the tag key. Minimum: 1 Maximum: 36
value	String	Specifies the tag value. Minimum: 0 Maximum: 43

**Table 13** ListenerIpGroup¶
Parameter	Type	Description
ipgroup_id	String	Specifies the ID of the IP address group associated with the listener. This parameter is mandatory when you create the IP address group and is optional when you update the IP address group. The specified IP address group must exist, and the value cannot be null.
enable_ipgroup	Boolean	Specifies whether to enable access control. true: Access control is enabled. false: Access control is disabled. A listener with access control enabled can be directly deleted.
type	String	Specifies how access to the listener is controlled. white: A whitelist is configured. Only IP addresses in the whitelist can access the listener. black: A blacklist is configured. IP addresses in the blacklist are not allowed to access the listener.

**Table 14** ListenerQuicConfig¶
Parameter	Type	Description
quic_listener_id	String	Specifies the ID of the QUIC listener. This parameter is mandatory for creation and is optional for update. The specified quic_listener_id must exist. The listener protocol must be QUIC and cannot be set to null, otherwise, it will conflict with enable_quic_upgrade. QUIC protocol is not supported.
enable_quic_upgrade	Boolean	Specifies whether to enable QUIC upgrade. True: QUIC upgrade is enabled. False: QUIC upgrade is disabled. HTTPS listeners can be upgraded to QUIC listeners. QUIC protocol is not supported.

Example Requests¶

Example 1: Adding a TCP listener

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
    }
  }
}

Example 2: Adding an HTTPS listener

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"
  }
}

Example Responses¶

Status code: 201

Normal response to POST requests.

{
  "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"
}

Status Codes¶

Status Code	Description
201	Normal response to POST requests.

Error Codes¶

See Error Codes.

last updated: 2024-12-10 15:19 UTC - commit: ce8dfe31a7e62df8f351b369251e4667fec0f78a