• Elastic Load Balancing

elb
  1. Help Center
  2. Elastic Load Balancing
  3. API Reference
  4. Enhanced Load Balancer APIs
  5. Listener
  6. Modifying a Listener

Modifying a Listener

Function

This API is used to modify a listener, such as listener name, description, associated backend server group, and server certificate.

URI

PUT /v2.0/lbaas/listeners/{listener_id}

Table 1 Parameter description

Parameter

Type

Mandatory

Description

listener_id

Uuid

Yes

Specifies the listener ID.

Constraints

  • If the provisioning status of the associated load balancer is not ACTIVE, the listener cannot be updated.
  • Only the administrator can specify connection_limit.
  • The default_pool_id parameter has the following constraints:
    • Its value cannot be the ID of any backend server group of other listeners.
    • Its value cannot be the ID of any backend server group associated with the forwarding policies set for other listeners.
  • The relationships between the listener protocol and backend server group protocol are as follows:
    • When the listener protocol is TCP, the backend server group protocol must be TCP.
    • When the listener protocol is UDP, the backend server group protocol must be UDP.
    • When the listener protocol is HTTP or TERMINATED_HTTPS, the backend server group protocol must be HTTP.

Request

Table 2 Parameter description

Parameter

Type

Mandatory

Description

listener

Dict

Yes

Specifies the listener. For details, see Table 3.

Table 3 listener field description

Parameter

Type

Mandatory

Description

name

String (255)

No

Specifies the listener name.

description

String (255)

No

Provides supplementary information about the listener.

connection_limit

Int

No

Specifies the maximum number of connections.

The value ranges from -1 to 2,147,483,647.

This parameter is reserved and has been not used. Only the administrator can specify the maximum number of connections.

http2_enable

Bool

No

Specifies whether to use HTTP/2.

The value can be true or false. true: HTTP/2 is used. false: HTTP/2 is not used.

This parameter is valid only when the listener protocol is set to TERMINATED_HTTPS.

default_pool_id

Uuid

No

Specifies the ID of the associated backend server group.

If a request does not match the forwarding policy, the request is forwarded to the default backend server group for processing. If the value is null, the listener has no default backend server group.

This parameter has the following constraints:
  • Its value cannot be the ID of any backend server group associated with the forwarding policies set for other listeners.
  • It value cannot be the ID of any backend server group associated with the forwarding policies set for other listeners.
The relationships between the listener protocol and backend server group protocol are as follows:
  • When the listener protocol is TCP, the backend server group protocol must be TCP.
  • When the listener protocol is UDP, the backend server group protocol must be UDP.
  • When the listener protocol is HTTP or TERMINATED_HTTPS, the backend server group protocol must be HTTP.

admin_state_up

Bool

No

Specifies the administrative status of the listener.

This parameter is reserved and has been not used. The value can only be true.

default_tls_container_ref

String (128)

No

Specifies the ID of the server certificate used by the listener.

This parameter is mandatory when protocol is set to TERMINATED_HTTPS.

client_ca_tls_container_ref

String (128)

No

Specifies the ID of the CA certificate used by the listener.

sni_container_refs

String-list

No

Lists the IDs of SNI certificates (server certificates with a domain name) used by the listener.

If the parameter value is not an empty list, the SNI feature is enabled. If the parameter value is an empty list, the SNI feature is disabled.

Response

Table 4 Parameter description

Parameter

Type

Description

listener

Dict

Specifies the listener. For details, see Table 5.

Table 5 listeners field description

Parameter

Type

Description

id

Uuid

Specifies the listener ID.

tenant_id

String (255)

Specifies the ID of the project where the listener is used.

name

String (255)

Specifies the listener name.

description

String (255)

Provides supplementary information about the listener.

protocol

String

Specifies the listener protocol.

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

protocol_port

Int

Specifies the listening port.

The port number ranges from 1 to 65535.

loadbalancers

List

Specifies the ID of the associated load balancer.

connection_limit

Int

Specifies the maximum number of connections.

The value ranges from -1 to 2,147,483,647. The default value is -1, indicating that there is no restriction on maximum connections.

This parameter is reserved and has been not used.

admin_state_up

Bool

Specifies the administrative status of the listener.

This parameter is reserved and has been not used. The value can only be true.

http2_enable

Bool

Specifies whether to use HTTP/2.

The value can be true or false. true: HTTP/2 is used. false: HTTP/2 is not used.

This parameter is valid only when the listener protocol is set to TERMINATED_HTTPS.

default_pool_id

Uuid

Specifies the ID of the associated backend server group.

If a request does not match the forwarding policy, the request is forwarded to the default backend server group for processing. If the value is null, the listener has no default backend server group.

default_tls_container_ref

String (128)

Specifies the ID of the server certificate used by the listener. For details, see SSL Certificate.

This parameter is mandatory when protocol is set to TERMINATED_HTTPS.

client_ca_tls_container_ref

String (128)

Specifies the ID of the CA certificate used by the listener. For details, see SSL Certificate.

sni_container_refs

String-list

Lists the IDs of SNI certificates (server certificates with a domain name) used by the listener.

If the parameter value is an empty list, the SNI feature is disabled. If the parameter value is an empty list, the SNI feature is disabled.

tags

String-list

Tags the listener.

created_at

String (19)

Specifies the time when a listener was created. The time is in YYYY-MM-DDTHH:MM:SS format.

updated_at

String (19)

Specifies the time when the listener was updated. The time is in YYYY-MM-DDTHH:MM:SS format.

Example

  • Example request: Updating a listener
    PUT https://{Endpoint}/v2.0/lbaas/listeners/f622c150-72f5-4263-a47a-e5003c652aa3
    
    {  
        "listener": {  
            "description": "my listener",  
            "name": "listener-jy-test2", 
            "default_pool_id": "c61310de-9a06-4f0c-850c-6f4797b9984c", 
            "default_tls_container_ref": "23b58a961a4d4c95be585e98046e657a", 
            "client_ca_tls_container_ref": "417a0976969f497db8cbb083bff343ba"
            
        }  
    }
  • Example response
    {
        "listener": {
            "client_ca_tls_container_ref": "417a0976969f497db8cbb083bff343ba",
            "protocol": "TERMINATED_HTTPS",
            "description": "my listener",
            "default_tls_container_ref": "23b58a961a4d4c95be585e98046e657a",
            "admin_state_up": true,
            "http2_enable": false,
            "loadbalancers": [
                {
                    "id": "165b6a38-5278-4569-b747-b2ee65ea84a4"
                }
            ],
            "tenant_id": "601240b9c5c94059b63d484c92cfe308",
            
            "sni_container_refs": [],
            "connection_limit": -1,
            "protocol_port": 443,
            "tags": [],
            "default_pool_id": "c61310de-9a06-4f0c-850c-6f4797b9984c",
            "id": "f622c150-72f5-4263-a47a-e5003c652aa3",
            "name": "listener-jy-test2",
            "created_at": "2018-07-25T01:54:13", 
            "updated_at": "2018-07-25T01:54:14"
            
        }
    }

Response Codes

For details, see HTTP Status Codes for Enhanced Load Balancers.