Adding a Listener¶

Function¶

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

Constraints¶

Only the administrator can specify connection_limit.

The listener protocol can be TCP, HTTP, UDP, or HTTPS.
For load balancing at Layer 4, the listener protocol can only be TCP or UDP.
For load balancing at Layer 7, the listener 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.
client_ca_tls_container_ref	No	String	Specifies the ID of the CA certificate used by the listener. Minimum: 1 Maximum: 128
default_pool_id	No	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 for processing. Minimum: 1 Maximum: 36
default_tls_container_ref	No	String	Specifies the ID of the server certificate used by the listener. 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. This parameter is available only for HTTPS listeners. If you configure this parameter for other types of listeners, it will not take effect. Enable 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 use HTTP/1.x by default.
insert_headers	No	ListenerInsertHeaders object	Specifies the HTTP header fields.
loadbalancer_id	Yes	String	Specifies the ID of the load balancer that the listener is added to. 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 protocol can be TCP, HTTP, UDP, or HTTPS.
protocol_port	Yes	Integer	Specifies the port used by the listener. Minimum: 1 Maximum: 65535
sni_container_refs	No	Array of strings	Lists the IDs of SNI certificates (server certificates with domain names) used by the listener. Each SNI certificate can have up to 30 domain names, and each domain name in the SNI certificate must be unique. This parameter will be ignored and an empty array will be returned if the listener's protocol is not HTTPS.
tags	No	Array of Tag objects	Lists the tags.
tls_ciphers_policy	No	String	Specifies the security policy that will be used by the listener. This parameter is available only for HTTPS listeners. The default value is tls-1-0. An error will be returned if the protocol of the listener is not HTTPS. Value options: tls-1-0 tls-1-1 tls-1-2 tls-1-2-strict
enable_member_retry	No	Boolean	Specifies whether to enable health check retries for backend servers. This parameter is available only for HTTP and HTTPS listeners. An error will be returned if you configure this parameter for TCP and UDP listeners. Default: true
keepalive_timeout	No	Integer	Specifies the idle timeout duration, in seconds. 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 0 to 4000, and the default value is 60. For UDP listeners, this parameter is not available. An error will be returned if you configure this parameter for UDP listeners.
client_timeout	No	Integer	Specifies the timeout duration for waiting for a request from a client, in seconds. This parameter is available only for HTTP and HTTPS listeners. The value ranges from 1 to 300, and the default value is 60. An error will be returned if you configure this parameter for TCP and UDP listeners. Minimum: 1 Maximum: 300 Default: 60
member_timeout	No	Integer	Specifies the timeout duration for waiting for a request from a backend server, in seconds. This parameter is available only for HTTP and HTTPS listeners. The value ranges from 1 to 300, and the default value is 60. An error will be returned if you configure this parameter for TCP and UDP listeners.
ipgroup	No	CreateListenerIpGroupOption object	Specifies the IP address group associated with the listener. The value can be null or an empty JSON structure, indicating that no IP address group is associated with the listener. ipgroup_id is also required if you want to associate an IP address group with the listener. This parameter is unsupported. Please do not use it.
transparent_client_ip_enable	No	Boolean	Specifies whether to pass source IP addresses of the clients to backend servers. Shared load balancers: The value can be true or false, and the default value is false for TCP and UDP listeners. The value can only be true for HTTP and HTTPS listeners. If this parameter is not passed, the default value is true. Dedicated load balancers: The value can only be true for all types of listeners. If this parameter is not passed, the default value is true.
enhance_l7policy_enable	No	Boolean	Specifies whether to enable advanced forwarding. The value can be true or false (default). true indicates that advanced forwarding will be enabled. false indicates that advanced forwarding will not be enabled. The following parameters will be available only when advanced forwarding is enabled: redirect_url_config fixed_response_config priority conditions For details, see the descriptions in the APIs of forwarding policies and forwarding rules. This parameter is unsupported. Please do not use it.

**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	Yes	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.
value	No	String	Specifies the tag value.

**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 [] and type to whitelist, no IP addresses are allowed to access the listener. If ip_list is set to [] and type to blacklist, any IP address is allowed to access the listener. The specified IP address group must exist and this parameter cannot be set to null. IP address groups are not supported for now.
enable_ipgroup	No	Boolean	Specifies whether to enable access control. true (default): Access control will be enabled. false: Access control will be disabled. A listener with access control enabled can be directly deleted.
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. And the value can only be true. This parameter is unsupported. Please do not use it. Default: true
client_ca_tls_container_ref	String	Specifies the ID of the CA certificate used by the listener.
connection_limit	Integer	Specifies the maximum number of connections. The default value is -1. This parameter is unsupported. Please do not use it.
created_at	String	Specifies the time when the listener was created.
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. This parameter is available only for HTTPS listeners. If you configure this parameter for other types of listeners, it will not take effect. Enable 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 use HTTP/1.x by default. Default: true
id	String	Specifies the listener ID.
insert_headers	ListenerInsertHeaders object	Specifies the HTTP header fields.
loadbalancers	Array of LoadBalancerRef objects	Specifies the ID of the load balancer that the listener is added to.
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.
protocol_port	Integer	Specifies the port used by the listener. Minimum: 1 Maximum: 65535
sni_container_refs	Array of strings	Lists the IDs of SNI certificates (server certificates with domain names) used by the listener. Each SNI certificate can have up to 30 domain names, and each domain name in the SNI certificate must be unique. This parameter will be ignored and an empty array will be returned if the listener's protocol is not HTTPS.
tags	Array of Tag objects	Lists the tags.
updated_at	String	Specifies the time when the listener was updated.
tls_ciphers_policy	String	Specifies the security policy used by the listener. This parameter is available only for HTTPS listeners. The value can be tls-1-0, tls-1-1, tls-1-2, or tls-1-2-strict, and the default value is tls-1-0.
enable_member_retry	Boolean	Specifies whether to enable health check retries for backend servers. This parameter is available only for HTTP and HTTPS listeners.
keepalive_timeout	Integer	Specifies the idle timeout duration, in seconds. 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 0 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 request from a client, in seconds. This parameter is available only for HTTP and HTTPS listeners. The value ranges from 1 to 300, and the default value is 60.
member_timeout	Integer	Specifies the timeout duration for waiting for a request from a backend server, in seconds. This parameter is available only for HTTP and HTTPS listeners. The value ranges from 1 to 300, and the default value is 60.
ipgroup	ListenerIpGroup object	Specifies the IP address group associated with the listener. This parameter is unsupported. Please do not use it.
transparent_client_ip_enable	Boolean	Specifies whether to pass source IP addresses of the clients to backend servers. Shared load balancers: The value can be true or false, and the default value is false for TCP and UDP listeners. The value can only be true for HTTP and HTTPS listeners. If this parameter is not passed, the default value is true. Dedicated load balancers: The value can only be true for all types of listeners. If this parameter is not passed, the default value is true.
enhance_l7policy_enable	Boolean	Specifies whether to enable advanced forwarding. The value can be true or false (default). true indicates that advanced forwarding will be enabled. false indicates that advanced forwarding will not be enabled. The following parameters will be available only when advanced forwarding is enabled: redirect_url_config fixed_response_config priority conditions For details, see the descriptions in the APIs of forwarding policies and forwarding rules. This parameter is unsupported. Please do not use it.

**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.
value	String	Specifies the tag value.

**Table 13** ListenerIpGroup¶
Parameter	Type	Description
ipgroup_id	String	Specifies the ID of the IP address group associated with the listener. If ip_list is set to [] and type to whitelist, no IP addresses are allowed to access the listener. If ip_list is set to [] and type to blacklist, any IP address is allowed to access the listener. The specified IP address group must exist and this parameter cannot be set to 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.

Example Requests¶

Example 1: Adding an HTTPS listener

POST

https://{elb_endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners

{
  "listener" : {
    "protocol_port" : 90,
    "protocol" : "HTTPS",
    "loadbalancer_id" : "ac82ca77-8be3-4d65-9c4d-155771b463df",
    "name" : "My listener",
    "admin_state_up" : true,
    "default_tls_container_ref" : "4e7761d7c7d141c389479f2641c8bff8"
  }
}

Example 2: 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 Responses¶

Status code: 201

Successful request.

{
  "listener" : {
    "id" : "683cf917-3e51-4c41-830c-bc3a57e090f0",
    "name" : "My listener",
    "protocol_port" : 90,
    "protocol" : "HTTPS",
    "description" : "",
    "default_tls_container_ref" : "4e7761d7c7d141c389479f2641c8bff8",
    "admin_state_up" : true,
    "loadbalancers" : [ {
      "id" : "ac82ca77-8be3-4d65-9c4d-155771b463df"
    } ],
    "client_ca_tls_container_ref" : null,
    "project_id" : "060576782980d5762f9ec014dd2f1148",
    "sni_container_refs" : [ ],
    "connection_limit" : -1,
    "default_pool_id" : null,
    "tls_ciphers_policy" : "tls-1-0",
    "security_policy_id" : null,
    "tags" : [ ],
    "created_at" : "2021-04-02T07:48:38Z",
    "updated_at" : "2021-04-02T07:48:38Z",
    "http2_enable" : false,
    "insert_headers" : {
      "X-Forwarded-ELB-IP" : false,
      "X-Forwarded-Host" : true,
      "X-Forwarded-For-Port" : false,
      "X-Forwarded-Port" : false
    },
    "member_timeout" : 60,
    "client_timeout" : 60,
    "keepalive_timeout" : 60,
    "ipgroup" : null,
    "enable_member_retry" : true,
    "transparent_client_ip_enable" : true,
    "enhance_l7policy_enable" : false
  },
  "request_id" : "830de7c7c38232d925db168bfb3cb0e8"
}

Status Codes¶

Status Code	Description
201	Successful request.

Error Codes¶

See Error Codes.

last updated: 2023-03-02 13:42