CreateListener - Server Load Balancer - Alibaba Cloud Documentation Center

Creates an HTTP, HTTPS, or QUIC listener in a region.

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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

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	Write	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
XForwardedForClientCertClientVerifyAlias	string	No	The name of the custom header. This parameter takes effect only when XForwardedForClientCertClientVerifyEnabled is set to true. The name must be 1 to 40 characters in length, and can contain lowercase letters, hyphens (-), underscores (_), and digits. 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: uses the X-Forwarded-Clientcert-clientverify header. false (default): does not use the X-Forwarded-Clientcert-clientverify header. 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 lowercase letters, hyphens (-), underscores (_), and digits. 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: uses the X-Forwarded-Clientcert-fingerprint header. false (default): does not use the X-Forwarded-Clientcert-fingerprint header. 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 lowercase letters, hyphens (-), underscores (_), and digits. 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: uses the X-Forwarded-Clientcert-issuerdn header. false (default): does not use the X-Forwarded-Clientcert-issuerdn header. 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 lowercase letters, hyphens (-), underscores (_), and digits. 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: uses the X-Forwarded-Clientcert-subjectdn header. false (default): does not use the X-Forwarded-Clientcert-subjectdn header. Note Only HTTPS listeners support this parameter.	true
XForwardedForClientSrcPortEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Client-Port` header to retrieve the client port. Valid values: true: uses the X-Forwarded-Client-Port header. false (default): does not use the X-Forwarded-Client-Port header. 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): uses the X-Forwarded-For header. false: does not use the X-Forwarded-For header. Note HTTP and HTTPS listeners support this parameter.	true
XForwardedForProtoEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Proto` header to retrieve the listening protocol of the ALB instance. Valid values: true: uses the X-Forwarded-Proto header. false (default): does not use the X-Forwarded-Proto header. 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: uses the SLB-ID header. false (default): does not use the SLB-ID header. 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 listening port of the ALB instance. Valid values: true: uses the X-Forwarded-Port header. false (default): does not use the X-Forwarded-Port header. Note HTTP, HTTPS, and QUIC listeners support this parameter.	false
XForwardedForClientSourceIpsEnabled	boolean	No	Specifies whether to use the `X-Forwarded-Client-Ip` header to obtain the source IP address of the ALB instance. Valid values: true: uses the X-Forwarded-Client-Ip header. false (default): does not use the X-Forwarded-Client-Ip header. Note HTTP, HTTPS, and QUIC listeners support this parameter. The feature corresponding to this parameter is not available by default. If you want to use this feature, submit a ticket.	false
XForwardedForClientSourceIpsTrusted	string	No	The trusted proxy IP address. ALB traverses `X-Forwarded-For` backwards and selects the first IP address that is not in the trusted IP list as the originating IP address of the client, which will be throttled if source IP address throttling is enabled.	10.1.1.0/24
QuicConfig	object	No
QuicListenerId	string	No	The ID of the QUIC listener that you want to associate with the HTTPS listener. Only HTTPS listeners support this parameter. This parameter is required when QuicUpgradeEnabled is set to true. Note The HTTPS listener and the QUIC listener must be added to the same ALB instance. Make sure that the QUIC listener is not associated with any other listeners.	lsr-bp1bpn0kn908w4nbw****
QuicUpgradeEnabled	boolean	No	Specifies whether to enable QUIC upgrade. Valid values: true: enables QUIC upgrade. false (default): disables QUIC upgrade. Note Only HTTPS listeners support this parameter.	false
Certificates	object []	No
CertificateId	string	No	The ID of the certificate. Only server certificates are supported. You can specify up to 20 certificate IDs.	12315790212_166f8204689_1714763408_70998****
DefaultActions	object []	Yes
ForwardGroupConfig	object	Yes
ServerGroupTuples	object []	Yes
ServerGroupId	string	Yes	The ID of the server group to which requests are forwarded.	rsp-cige6j****
Type	string	Yes	The action type. You can specify only one action type. Valid value: ForwardGroup: forwards requests to multiple vServer groups.	ForwardGroup
Tag	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
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
ListenerId	string	The ID of the listener.	lsr-bp1bpn0kn908w4nbw****
RequestId	string	The ID of the request.	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-01-29

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	Error Codes 400 change
	Error Codes 403 change
	delete Error Codes: 404

2024-01-29

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	Error Codes 403 change
	delete Error Codes: 400
	delete Error Codes: 404

2024-01-18

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	Error Codes 400 change
	delete Error Codes: 404
	Added Error Codes: 403

2023-11-06

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	delete Error Codes: 400
	delete Error Codes: 404

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.
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.