CreateListener - Server Load Balancer - Alibaba Cloud Documentation Center

Creates a listener.

Operation description

Usage notes

CreateListener is an asynchronous operation. After you call this operation, the system returns a request ID. However, the operation is still being performed in the background. You can call the GetListenerAttribute operation to query the status of the HTTP, HTTPS, or QUIC listener.

If the HTTP, HTTPS, or QUIC listener is in the Provisioning state, it indicates that the listener is being created.
If the HTTP, HTTPS, or QUIC listener is in the Running state, it indicates that the listener has been created successfully.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
alb:CreateListener	create	LoadBalancer acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId} SecurityPolicy acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId} ServerGroup acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}	alb:ListenerProtocol	none

Request parameters

Parameter	Type	Required	Description	Example
LoadBalancerId	string	Yes	The ID of the ALB instance.	alb-n5qw04uq8vavfe****
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that it is unique among all requests. The token can contain only ASCII characters. Note If you do not set this parameter, the system automatically uses the value of RequestId as the value of ClientToken. RequestId may be different for each API request.	123e4567-e89b-12d3-a456-426655440000
DryRun	boolean	No	Specifies whether to perform only a precheck. Valid values: true: prechecks the request without creating a listener. The system checks the required parameters, request syntax, and limits. If the request fails the precheck, an error code is returned based on the cause of the failure. If the request passes the precheck, the `DryRunOperation` error code is returned. false (default): sends the API request. If the request passes the precheck, a 2xx HTTP status code is returned and the system proceeds to create a listener.	false
ListenerProtocol	string	Yes	The listener protocol. Valid values: HTTP, HTTPS, and QUIC.	HTTP
ListenerPort	integer	Yes	The frontend port that is used by the ALB instance. Valid values: 1 to 65535.	80
ListenerDescription	string	No	The name of the listener. The description must be 2 to 256 characters in length, and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), and underscores (_). Regular expressions are supported.	HTTP_80
RequestTimeout	integer	No	The timeout period of a request. Unit: seconds. Valid values: 1 to 180. Default value: 60. If no response is received from the backend server during the request timeout period, ALB sends an `HTTP 504` error code to the client.	60
IdleTimeout	integer	No	The timeout period of an idle connection. Unit: seconds. Valid values: 1 to 60. Default value: 15. If no requests are received within the specified timeout period, ALB closes the current connection. When a new request is received, ALB establishes a new connection.	3
GzipEnabled	boolean	No	Specifies whether to enable `Gzip` compression to compress specific types of files. Valid values: true (default): enables Gzip compression. false: disables Gzip compression.	true
Http2Enabled	boolean	No	Specifies whether to enable `HTTP/2`. Valid values: true (default): enables HTTP/2. false: disables HTTP/2. Note Only HTTPS listeners support this parameter.	true
SecurityPolicyId	string	No	The ID of the security policy. System security policies and custom security policies are supported. Default value: tls_cipher_policy_1_0 (system security policy). Note Only HTTPS listeners support this parameter.	tls_cipher_policy_1_0
CaEnabled	boolean	No	Specifies whether to enable mutual authentication. Valid values: true: enables mutual authentication. false (default): disables mutual authentication.	false
XForwardedForConfig	object	No	The configuration of the XForward header.
XForwardedForClientCertClientVerifyAlias	string	No	The name of the custom header. This parameter takes effect only when you set XForwardedForClientCertClientVerifyEnabled to true. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). Note Only HTTPS listeners support this parameter.	test_client-verify-alias_123456
XForwardedForClientCertClientVerifyEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-clientverify` header to retrieve the verification result of the client certificate. Valid values: true false (default) Note Only HTTPS listeners support this parameter.	true
XForwardedForClientCertFingerprintAlias	string	No	The name of the custom header. This parameter takes effect only when XForwardedForClientCertFingerprintEnabled is set to true. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). Note Only HTTPS listeners support this parameter.	test_finger-print-alias_123456
XForwardedForClientCertFingerprintEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-fingerprint` header to retrieve the fingerprint of the client certificate. Valid values: true false (default) Note Only HTTPS listeners support this parameter.	true
XForwardedForClientCertIssuerDNAlias	string	No	The name of the custom header. This parameter takes effect only when XForwardedForClientCertIssuerDNEnabled is set to true. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). Note Only HTTPS listeners support this parameter.	test_issue-dn-alias_123456
XForwardedForClientCertIssuerDNEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-issuerdn` header to retrieve information about the authority that issues the client certificate. Valid values: true false (default) Note Only HTTPS listeners support this parameter.	true
XForwardedForClientCertSubjectDNAlias	string	No	The name of the custom header. This parameter takes effect only when XForwardedForClientCertSubjectDNEnabled is set to true. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). Note Only HTTPS listeners support this parameter.	test_subject-dn-alias_123456
XForwardedForClientCertSubjectDNEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Clientcert-subjectdn` header to retrieve information about the owner of the client certificate. Valid values: true false (default) Note Only HTTPS listeners support this parameter.	true
XForwardedForClientSrcPortEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Client-srcport` header to retrieve the client port. Valid values: true false (default) Note HTTP and HTTPS listeners support this parameter.	true
XForwardedForEnabled	boolean	No	Specifies whether to use the `X-Forwarded-For` header to retrieve client IP addresses. Valid values: true (default) false Note HTTP and HTTPS listeners support this parameter.	true
XForwardedForProtoEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Proto` header to retrieve the listener protocol. Valid values: true false (default) Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForSLBIdEnabled	boolean	No	Specifies whether to use the `SLB-ID` header to retrieve the ID of the ALB instance. Valid values: true false (default) Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForSLBPortEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Port` header to retrieve the listener port of the ALB instance. Valid values: true false (default) Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForClientSourceIpsEnabled	boolean	No	Specifies whether to allow the ALB instance to retrieve client IP addresses from the X-Forwarded-For header. Valid values: true false (default) Note HTTP and HTTPS listeners support this parameter.	false
XForwardedForClientSourceIpsTrusted	string	No	The trusted proxy IP address. ALB instances traverse the IP addresses in the `X-Forwarded-For` header from the rightmost IP address to the leftmost IP address. The first IP address that is not on the trusted IP address list is considered the client IP address. Requests from the client IP address are throttled.	10.1.1.0/24
QuicConfig	object	No	Select a QUIC listener and associate it with the ALB instance.
QuicListenerId	string	No	The ID of the QUIC listener that you want to associate with the ALB instance. This parameter is required if you set QuicUpgradeEnabled to true. Note The original listener and the QUIC listener must belong to the same ALB instance.	lsr-bp1bpn0kn908w4nbw****
QuicUpgradeEnabled	boolean	No	Specifies whether to enable QUIC upgrade. Valid values: true: false (default) Note Only HTTPS listeners support this parameter.	false
Certificates	array<object>	No	The details about each certificate.
	object	No	The configurations of the certificate.
CertificateId	string	No	The ID of the certificate. Only server certificates are supported. You can specify at most 20 certificates IDs. Note This parameter is required when you set ListenerProtocol to HTTPS or QUIC.	12315790212_166f8204689_1714763408_70998****
CaCertificates	array<object>	No	The certificate authority (CA) certificates. You can specify only one CA certificate.
	object	No	The CA hierarchy.
CertificateId	string	No	The ID of the CA certificate. Note This parameter is required if you set CaEnabled to true.	12315790212_166f8204689_1714763408_70998****
DefaultActions	array<object>	Yes	The actions of the forwarding rule.
	object	Yes
ForwardGroupConfig	object	Yes	The configuration of the forwarding action. You can specify at most 20 actions.
ServerGroupTuples	array<object>	Yes	The destination server group to which requests are forwarded.
	object	Yes
ServerGroupId	string	Yes	The ID of the server group to which requests are forwarded.	rsp-cige6j****
Type	string	Yes	The action. You can specify only one type. Valid value example: ForwardGroup: forwards requests to multiple server groups.	ForwardGroup
Tag	array<object>	No	The tags.
	object	No	The tags.
Key	string	No	The tag key. The tag key can be up to 128 characters in length and cannot start with `acs:` or `aliyun`. It cannot contain `http://` or `https://`.	env
Value	string	No	The tag value. The tag value can be up to 128 characters in length and cannot start with `acs:` or `aliyun`. It cannot contain `http://` or `https://`.	product

Response parameters

Parameter	Type	Description	Example
	object	Creates a listener.
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
ListenerId	string	The listener ID.	lsr-bp1bpn0kn908w4nbw****
RequestId	string	The request ID.	CEF72CEB-54B6-4AE8-B225-F876FF7BA984

Examples

Sample success responses

JSONformat

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "ListenerId": "lsr-bp1bpn0kn908w4nbw****",
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984"
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-09-03	The Error code has changed	View Change Details
2024-01-29	The Error code has changed	View Change Details
2024-01-29	The Error code has changed	View Change Details
2024-01-18	The Error code has changed	View Change Details
2023-11-06	The Error code has changed	View Change Details

HTTP status code	Error code	Error message	Description
400	ResourceAlreadyExist.Listener	The specified resource %s is already exist.	The specified resource %s already exists.
400	IncorrectStatus.LoadBalancer	The status of %s [%s] is incorrect.	The status of %s [%s] is incorrect.
400	IncorrectBusinessStatus.LoadBalancer	The business status of %s [%s] is incorrect.	The business status of %s [%s] is incorrect.
400	ResourceQuotaExceeded.LoadBalancerListenersNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s, usage %s/%s.
400	OperationDenied.CrossLoadBalancerQUICListener	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	ResourceAlreadyAssociated.Listener	The specified resource %s is already associated.	The specified resource %s is already associated.
400	ResourceQuotaExceeded.SecurityPolicyAttachedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	ResourceQuotaExceeded.ServerGroupAttachedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s, usage %s/%s.
400	ResourceQuotaExceeded.LoadBalancerServersNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	ResourceQuotaExceeded.ServerAddedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	Mismatch.VpcId	The %s is mismatched for %s and %s.	The %s is mismatched for %s and %s.
400	OperationDenied.ServerGroupProtocolNotSupport	The operation is not allowed because of ServerGroupProtocolNotSupport.	The operation is not allowed because the server group protocol is not supported.
400	OperationDenied.GRPCServerGroup	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	Mismatch.LoadBalancerEditionAndConnectionDrain	The %s and %s are mismatched.	The %s and %s are mismatched.
400	Mismatch.LoadBalancerEditionAndSlowStartEnable	The %s and %s are mismatched.	The %s and %s are mismatched.
400	InvalidParameter	Invalid parameter, please check the parameter input.	Invalid parameter, please check the parameter input.
403	Forbidden.SecurityPolicy	Authentication has failed for SecurityPolicy.	-
403	Forbidden.LoadBalancer	Authentication is failed for %s.	Authentication is failed for %s.
403	Forbidden.Listener	Authentication is failed for %s.	Authentication is failed for %s.
404	ResourceNotFound.LoadBalancer	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.ServerGroup	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.SecurityPolicy	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.Listener	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.Certificate	The specified resource %s is not found.	The specified resource %s is not found.