Load Balancer
Load Balancer
Document
- Documentation
Load BalancerApplication Load Balancer (ALB)API ReferenceListenerCreateListener - Creating a listener
Copy page
Download PDFListener
CreateListener - Creating a listener
Copy pageDownload PDFCreateListener - Creating a listener
Call the CreateListener API to create a listener.
Instructions
Submit up to 5 API requests per second.
Debug
API Explorer
You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.
Request parameters
The following only details request parameters specific to this API and key common parameters. More information can be found in Common parameters.
Action string required Example: CreateListener
Action to execute. Set the value to CreateListener.
Version string required Example: 2020-04-01
The API version. Value: 2020-04-01.
XRealIpEnabled string optional Example: on
Enable or disable the X-real-ip Header for the listener. Values: * on (default): Enable. * off: Disable.
ListenerName string optional Example: test
Listener name.
- If left blank, it defaults to the format "Protocol-Port".
- Cannot start with http:// or https://.
- Must start with a letter or Chinese character. May include numbers, periods (.), underscores (_), and hyphens (-).
- Length must be between 1 and 128 characters.
Protocol string required Example: HTTP
Listener protocol. Valid values:
- HTTP
- HTTPS
Port integer required Example: 80
Listening port range: 1 - 65535.
Enabled string optional Example: on
Enable/Disable the listener. Values:
- on (default): Enable.
- off: Disable.
CertificateSource string optional Example: cert_center
Default certificate source. This parameter is only valid for HTTPS listeners. Valid values are as follows:
- alb: Indicates the certificate uploaded via ALB. Standard edition ALB instance does not support this value.
- cert_center: Represents an SSL certificate purchased from or uploaded to the VolcanoEngine Certificate Center.
CACertificateId string optional Example: cert-******
ID of the CA certificate associated with the listener. This parameter is used for mutual authentication on HTTPS listeners.
When the value of CACertificateSource is alb, the CACertificateId parameter must be specified.
CertCenterCertificateId string optional Example: cert-********
The certificate ID associated with the listener. Required when creating an HTTPS listener with the certificate source set to cert_center.
EnableHttp2 string optional Example: off
HTTP/2.0 feature switch. This parameter is only valid for HTTPS listeners. Valid values:
- on: Enable.
- off (default): Disable.
Tags.N.Value string[] optional Example: Tags.1.Value=v1&Tags.2.Value=v2
The tag value of the custom tag.
- To provide this parameter, provide Tags.N.Key first.
- The specific rules are as follows:
- The length limit is 0 to 256 characters.
- Case-sensitive.
- Must not start or end with a space.
- May include characters (any language), numbers, spaces ( ), underscores (_), periods (.), half-width colons (:), slashes (/), equal signs (=), plus signs (+), minus signs (-) and at signs (@).
EnableQuic string optional Example: off
QUIC feature switch. This parameter is only valid for HTTPS listeners. Valid values:
- on: Enable.
- off (default): Disable.
- Only standard edition ALB instances support QUIC. To use the QUIC feature, please contact your account manager.
Tags.N.Key string[] optional Example: Tags.1.Key=k1&Tags.2.Key=k2
The tag key of the custom tag. The specific rules are as follows:
- Must be 1 to 128 characters.
- Case-sensitive.
- It cannot start with volc: or sys: in any case form.
- Must not start or end with a space.
- May include characters (any language), numbers, spaces ( ), underscores (_), periods (.), half-width colons (:), slashes (/), equal signs (=), plus signs (+), minus signs (-) and at signs (@).
- Duplicate tag keys are not allowed for the same resource.
AclStatus string optional Example: off
Enable access control. Valid values:
- on: Enable.
- off (default): Do not enable.
PcaLeafCertificateId string optional Example: cert-********
The certificate ID associated with the listener. Required when creating an HTTPS listener with the certificate source set to pca_leaf.
AclType string optional Example: black
Method of access control. Valid values:
- white: Allowlist mode. Indicates that the listener forwards requests only from the IP addresses or CIDR blocks set in the selected access control policy group. If no IPs are added to the selected policy group, the listener does not forward any requests.
- black: Denylist mode. Indicates that the listener denies requests only from the IP addresses or CIDR blocks set in the selected access control policy group. If no IPs are added to the selected policy group, the listener forwards all requests.
- When the AclStatus parameter is set to on, AclType and AclIds.N are required.
Description string optional Example: test
Description of the listener.
- Cannot start with http:// or https://.
- Must start with a letter or Chinese character and may include numbers, half-width commas (,), periods (.), underscores (_), spaces ( ), equal signs (=), hyphens (-), full-width commas (，), and full-width periods (。).
- Must be 1 to 255 characters.
- If left blank, this parameter defaults to an empty string.
CACertificateSource string optional Example: pca_root
Source of the CA certificate associated with the listener. This parameter is only valid for HTTPS listeners and is used for mutual authentication. Valid values:
- alb (default): Indicates the certificate uploaded via ALB. Standard Edition ALB instances do not support certificates from this source.
- pca_root: Represents a private root CA certificate purchased from or uploaded to the VolcanoEngine Certificate Center.
- pca_sub: Represents a private sub CA certificate purchased from or uploaded to the VolcanoEngine Certificate Center.
tip
To enable mutual authentication for an HTTPS listener, you must specify both the CA certificate source and the CA certificate ID.
- When the value of CACertificateSource is alb, the CACertificateId parameter must be specified.
- When the value of CACertificateSource is pca_root, the PcaRootCACertificateId parameter must be specified.
- When the value of CACertificateSource is pca_sub, the PcaSubCACertificateId parameter must be specified.
DomainExtensions.N.Domain string[] optional Example: DomainExtensions.1.Domain=abc.com&DomainExtensions.2.Domain=def.com
Domain name.
- Parameter - N: Represents the sequence number of a domain. An HTTPS listener can associate with a maximum of 20 extended domains, with values ranging from 1 to 20.
- Specific format requirements are as follows:
- It generally cannot be empty. However, if the instance supports automatic extended certificate selection (i.e., SniAutoMatch is on), then DomainExtensions.N.Domain must be passed as an empty string.
- Must contain at least one '.', and cannot start or end with '.'.
- Only lowercase letters, numbers, '.', '-', and '*' are allowed.
- Length must be between 1 and 128 characters.
- Wildcard domain: Use "*" to replace one or more characters.
- The "*" must be at the beginning or end of the domain name.
- "*" cannot appear twice in the same domain name.
- No characters other than '.' are allowed before or after '*'.
- Valid example: .com, www.test..
- Invalid example: aaa.com, www..com
- Exact Domain Name: Must comply with domain name specifications (e.g., www.test.com).
- Domain names under the same HTTPS listener cannot be duplicated.
- Matching domain names is case-insensitive.
DomainExtensions.N.CertificateSource string[] optional Example: DomainExtensions.1.CertificateSource=cert_center&DomainExtensions.2.CertificateSource=alb
The server certificate source used by the domain name.
- Valid values:
- alb: Indicates the certificate uploaded via ALB. Standard edition ALB instance does not support this value.
- cert_center: Represents an SSL certificate purchased from or uploaded to the VolcanoEngine Certificate Center.
- Parameter - N: Represents the sequence number of a domain. An HTTPS listener can associate with a maximum of 20 extended domains, with values ranging from 1 to 20.
PcaRootCACertificateId string optional Example: cert-******
ID of the CA certificate associated with the listener. This parameter is used for mutual authentication on HTTPS listeners.
When the value of CACertificateSource is pca_root, the PcaRootCACertificateId parameter must be specified.
DomainExtensions.N.CertCenterCertificateId string[] optional Example: DomainExtensions.1.CertCenterCertificateId=cert-qwertyuqwert&DomainExtensions.2.CertCenterCertificateId=cert-zxcvbgasdfn
The server certificate used by the domain.
- Effective when the certificate source is cert_center.
- Parameter - N: Represents the serial number of a domain. An HTTPS listener can associate with a maximum of 20 additional domains, with values ranging from 1 to 20.
PcaSubCACertificateId string optional Example: cert-******
ID of the CA certificate associated with the listener. This parameter is used for mutual authentication on HTTPS listeners.
When the value of CACertificateSource is pca_sub, the PcaSubCACertificateId parameter must be specified.
LoadBalancerId string required Example: alb-abcderf******
The ALB instance ID to which the listener belongs.
CertificateId string optional Example: cert-********
The certificate ID associated with the listener. Required when creating an HTTPS listener with the certificate source set to alb.
ServerGroupId string required Example: rsp-********
The default server group ID associated with the listener.
AclIds.N string[] optional Example: AclIds.1=acl-3cj44nv0jhhxc6c6rrtet****& AclIds.2=acl-2febxt4pu0zy85oxruw0t****
The ID of the ACL bound to the listener.
- Parameter - N: Indicates the serial number of the access control list, with a maximum of 5.
- Separate multiple access control list IDs with ampersands ( & ).
- When the AclStatus parameter is set to on, AclType and AclIds.N are required.
DomainExtensions.N.CertificateId string[] optional Example: DomainExtensions.1.CertificateId=cert-qwertyuqwert&DomainExtensions.2.CertificateId=cert-zxcvbgasdfn
The server certificate used by the domain name.
- Effective only when the certificate source is alb.
- Parameter - N: Represents the serial number of a domain. An HTTPS listener can associate with a maximum of 20 additional domains, with values ranging from 1 to 20.
DomainExtensions.N.PcaLeafCertificateId string[] optional Example: DomainExtensions.1.PcaLeafCertificateId=pca_leaf-qwertyuqwert&DomainExtensions.2.PcaLeafCertificateId=pca_leaf-zxcvbgasdfn
The server certificate used by the domain name.
- Effective when the certificate source is pca_leaf.
- Parameter -N: Represents the serial number of a domain. An HTTPS listener can associate with a maximum of 20 extended domains, with values ranging from 1 to 20.
AccessLogRecordCustomizedHeadersEnabled string optional Example: off
Enable or disable header recording in the listener's access logs. Valid values:
- on: Enable.
- off (default): Disable.
Response parameters
Only the response parameters specific to this API are listed below. More information, see Response structure.
RequestId string Example: 20210811152539010225146063030****
Request ID.
ListenerId string Example: lsn-2fek3rgsxhrsw5oxruwec****
Listener ID.
Request examples
Response examples
Error codes
The following table lists the error codes related to the business logic for this API. For details, see Common error codes.
Last updated: 2026.06.12 14:05:15
All rights reserved © Beijing Volcano Engine Technology Co., Ltd2024
