Updated on 2024-04-09 GMT+08:00

Adding a Listener

Function

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

URI

POST /v1.0/{project_id}/elbaas/listeners

Table 1 Parameter description

Parameter

Mandatory

Type

Description

project_id

Yes

String

Specifies the project ID.

name

Yes

String

  • Specifies the listener name.
  • The value can contain 1 to 64 characters that consist of letters, digits, underscores (_), and hyphens (-).

description

No

String

  • Provides supplementary information about the listener.
  • The value contains 0 to 128 characters and cannot contain angle brackets (< and >).

loadbalancer_id

Yes

String

Specifies the load balancer ID.

protocol

Yes

String

  • Specifies the protocol used by the listener.
  • The value can be HTTP, TCP, HTTPS, or UDP.
  • A UDP listener cannot be added to a private network load balancer.

port

Yes

Integer

  • Specifies the port used by the listener.
  • The port number ranges from 1 to 65535.

backend_protocol

Yes

String

  • Specifies the backend ECS protocol.

    If protocol is set to UDP, the value of this parameter can only be UDP.

  • The value can be HTTP, TCP, or UDP.

backend_port

Yes

Integer

  • Specifies the port used by backend ECSs.
  • The port number ranges from 1 to 65535.

lb_algorithm

Yes

String

  • Specifies the load balancing algorithm.
  • The value can be roundrobin, leastconn, or source.

session_sticky

No

Boolean

  • Specifies whether to enable the sticky session feature.
  • The value can be true or false. The feature is enabled when the value is true.
  • If protocol is set to HTTP, HTTPS, or TCP and lb_algorithm is not roundrobin, the value of this parameter can only be false.

sticky_session_type

No

String

Specifies where the cookie is from. The only value is insert, indicating that the cookie is inserted by the load balancer.

  • This parameter takes effect when protocol is set to HTTP and session_sticky to true.
  • This parameter does not take effect when protocol is set to TCP or UDP, which means that the parameter is unavailable or its value is set to null.

cookie_timeout

No

Integer

  • Specifies the cookie timeout duration. This parameter is valid when protocol is set to HTTP, session_sticky to true, and sticky_session_type to insert. This parameter is invalid when protocol is set to TCP or UDP.
  • The value ranges from 1 to 1440.

tcp_timeout

No

Integer

  • Specifies the TCP session timeout duration. This parameter is valid when protocol is set to TCP.
  • The value ranges from 1 to 1440.

tcp_draining

No

Boolean

  • Specifies whether to maintain TCP connections to a backend ECS that has been removed. This parameter is valid when protocol is set to TCP.
  • The value can be true or false.

tcp_draining_timeout

No

Integer

  • Specifies the timeout duration for maintaining TCP connections to a backend ECS that has been removed in the unit of minute.

    This parameter is valid when protocol is set to TCP and tcp_draining to true.

  • The value ranges from 0 to 60.

certificate_id

No

String

  • Specifies the certificate ID. This parameter is mandatory when protocol is set to HTTPS.
  • The ID can be obtained from the certificate list.

udp_timeout

No

Integer

  • Specifies the UDP session timeout duration. This parameter is valid when protocol is set to UDP.
  • The value ranges from 1 to 1440.

ssl_protocols

No

String

  • Specifies the supported SSL/TLS protocol version. This parameter is available only when protocol is set to HTTPS.
  • The value can be TLS 1.2 or TLS 1.2 TLS 1.1 TLS 1.0, and the default value is TLS 1.2.

ssl_ciphers

No

String

  • Specifies the cipher suites supported by a specific SSL/TLS protocol version. This parameter is available only when protocol is set to HTTPS.
  • The value is Default, Extended, or Strict.

    The value of Default is ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256.

    The value of Extended is ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:AES128-SHA256:AES256-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:AES128-SHA:AES256-SHA:DHE-DSS-AES128-SHA:CAMELLIA128-SHA:EDH-RSA-DES-CBC3-SHA:DES-CBC3-SHA:ECDHE-RSA-RC4-SHA:RC4-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:DHE-RSA-CAMELLIA256-SHA:DHE-DSS-CAMELLIA256-SHA:CAMELLIA256-SHA:EDH-DSS-DES-CBC3-SHA:DHE-RSA-CAMELLIA128-SHA:DHE-DSS-CAMELLIA128-SHA.

    The value of Strict is ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256.

    The default value is Default. When ssl_protocols is set to TLS 1.2 TLS 1.1 TLS 1.0, this parameter can only be set to Extended.

Request

  • Request parameters

    None

  • Example request
    {
        "name": "listener1",
        "description": "",
        "loadbalancer_id": "0b07acf06d243925bc24a0ac7445267a",
        "protocol": "HTTP",
        "port": 88,
        "backend_protocol": "HTTP",
        "backend_port": 80,
        "lb_algorithm": "roundrobin",
        "session_sticky": true,
        "sticky_session_type": "insert",
        "cookie_timeout": 100,
        "tcp_draining": true,
        "tcp_draining_timeout": 5
    }

Response

  • Response parameters
    Table 2 Parameter description

    Parameter

    Type

    Description

    update_time

    String

    Specifies the time when the listener was updated.

    backend_port

    Integer

    Specifies the port used by backend ECSs.

    id

    String

    Specifies the listener ID.

    backend_protocol

    String

    Specifies the protocol used by backend ECSs.

    sticky_session_type

    String

    Specifies where the cookie is from. The only value is insert, indicating that the cookie is inserted by the load balancer. This parameter is valid when protocol is set to HTTP and session_sticky to true.

    description

    String

    Provides supplementary information about the listener.

    loadbalancer_id

    String

    Specifies the load balancer ID.

    create_time

    String

    Specifies the time when the listener was created.

    status

    String

    Specifies the listener status. The value can be ACTIVE, PENDING_CREATE, or ERROR.

    protocol

    String

    Specifies the protocol used for load balancing at Layer 4 or Layer 7.

    port

    Integer

    Specifies the port used by the listener.

    cookie_timeout

    Integer

    • Specifies the cookie timeout duration in the unit of minute. This parameter is valid when session_sticky is set to true and sticky_session_type to insert.
    • The value ranges from 1 to 1440.

    admin_state_up

    Boolean

    • Specifies the administrative status of the load balancer.
    • Two options are available:

      false: The load balancer is disabled.

      true: The load balancer is running properly.

    session_sticky

    Boolean

    Specifies whether to enable the sticky session feature. The feature is enabled when the value is true.

    lb_algorithm

    String

    Specifies the load balancing algorithm.

    name

    String

    Specifies the listener name.

    tcp_draining

    Boolean

    • Specifies whether to maintain TCP connections to a backend ECS that has been removed. This parameter is valid when protocol is set to TCP.
    • The value can be true or false.

    tcp_draining_timeout

    Integer

    • Specifies the timeout duration for maintaining TCP connections to a backend ECS that has been removed in the unit of minute.

      This parameter is valid when protocol is set to TCP and tcp_draining to true.

    • The value ranges from 0 to 60.

    ssl_protocols

    String

    • Specifies the supported SSL/TLS protocol version.
    • This parameter is available only when protocol is set to HTTPS.

    ssl_ciphers

    String

    • Specifies the cipher suite of an encryption protocol.
    • This parameter is available only when protocol is set to HTTPS.

    certificate_id

    String

    • Specifies the default certificate ID.
    • This parameter is available only when protocol is set to HTTPS.
  • Example response
    {
        "update_time": "2015-09-15 07:41:17",
        "backend_port": 80,
        "tcp_draining": true,
        "id": "248425d7b97dc26920eb23720115e068",
        "backend_protocol": "HTTP",
        "sticky_session_type": "insert",
        "description": "",
        "loadbalancer_id": "0b07acf06d243925bc24a0ac7445267a",
        "create_time": "2015-09-15 07:41:17",
        "status": "ACTIVE",
        "protocol": "TCP",
        "port": 88,
        "cookie_timeout": 100,
        "admin_state_up": true,
        "session_sticky": true,
        "lb_algorithm": "roundrobin",
        "name": "listener1",
        "tcp_draining": true,
        "tcp_draining_timeout": 5
    }

Status Code

  • Normal

    200

  • Error

    Status Code

    Message

    Description

    400

    badRequest

    Request error.

    401

    unauthorized

    Authentication failed.

    403

    userDisabled

    You do not have the permission to perform the operation.

    404

    Not Found

    The requested page does not exist.

    500

    authFault

    System error.

    503

    serviceUnavailable

    The service is unavailable.