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.

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.

security_policy_id

No

String

Specifies the ID of the custom security policy. Custom security policies take effect only for dedicated load balancers. If both security_policy_id and tls_ciphers_policy are passed, only security_policy_id will take effect.

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.

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.

security_policy_id

String

Specifies the ID of the custom security policy. Custom security policies take effect only for dedicated load balancers. If both security_policy_id and tls_ciphers_policy are passed, only security_policy_id will take effect.

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.