All Products
Search

This Product

    Resource Orchestration Service:ALIYUN::ALB::Listener

    Document Center

    Resource Orchestration Service:ALIYUN::ALB::Listener

    Last Updated:Apr 01, 2025

    ALIYUN::ALB::Listener is used to create an HTTP, HTTPS, or Quick UDP Internet Connections (QUIC) listener.

    Syntax

    {
  "Type": "ALIYUN::ALB::Listener",
  "Properties": {
    "RequestTimeout": Integer,
    "ListenerPort": Integer,
    "Http2Enabled": Boolean,
    "DefaultActions": List,
    "Certificates": List,
    "IdleTimeout": Integer,
    "LoadBalancerId": String,
    "ListenerProtocol": String,
    "QuicConfig": Map,
    "GzipEnabled": Boolean,
    "SecurityPolicyId": String,
    "ListenerDescription": String,
    "XForwardedForConfig": Map,
    "CaEnabled": Boolean,
    "CaCertificates": List,
    "ListenerStatus": String,
    "LogConfig": Map
  }
}

    Properties

    Property

    Type

    Required

    Editable

    Description

    Constraint

    DefaultActions

    List

    Yes

    Yes

    The actions of the forwarding rule.

    Valid values:

    [
        {
          "ForwardGroupConfig": {
            "ServerGroupTuples": [
              {
                "ServerGroupId": "sgp-46ndzg2wz4v5mp****"
              }
            ]
          },
          "Type": "ForwardGroup"
        }
      ]

    For more information, see DefaultActions properties.

    ListenerPort

    Integer

    Yes

    No

    The listener port.

    Valid values: 1 to 65535.

    ListenerProtocol

    String

    Yes

    No

    The listener protocol.

    Valid values:

    • HTTP

    • HTTPS

    • QUIC

    LoadBalancerId

    String

    Yes

    No

    The ID of the Application Load Balancer (ALB) instance.

    None.

    CaCertificates

    List

    No

    Yes

    The certificate authority (CA) certificates.

    For more information, see CaCertificates property.

    CaEnabled

    Boolean

    No

    Yes

    Specifies whether to enable mutual authentication.

    Valid values:

    • true

    • false (default)

    Certificates

    List

    No

    Yes

    The certificates.

    For more information, see Certificates property.

    GzipEnabled

    Boolean

    No

    Yes

    Specifies whether to enable GNU zip (Gzip) compression to compress specific types of files.

    Valid values:

    • true (false)

    • false

    Http2Enabled

    Boolean

    No

    Yes

    Specifies whether to enable HTTP/2.

    Valid values:

    • true (default)

    • false

    Note

    You can configure this property only for HTTPS listeners.

    IdleTimeout

    Integer

    No

    Yes

    The timeout period of idle connections.

    Valid values: 1 to 60.

    Default value: 15.

    Unit: seconds.

    If no request is received within the specified timeout period, ALB closes the current connection. When another request is received, ALB establishes a new connection.

    ListenerDescription

    String

    No

    Yes

    The description of the listener.

    The description must be 2 to 256 characters in length,

    ListenerStatus

    String

    No

    Yes

    The status of the listener.

    Valid values:

    • Running

    • Stopped

    QuicConfig

    Map

    No

    Yes

    The configurations of the QUIC listener that you want to associate with the HTTPS listener of the ALB instance.

    For more information, see QuicConfig properties.

    RequestTimeout

    Integer

    No

    Yes

    The timeout period of a request.

    Valid values: 1 to 180.

    Default value: 60.

    Unit: seconds.

    If no response is received from the backend server within the specified timeout period, ALB stops waiting for the response and returns an HTTP 504 status code to the client.

    SecurityPolicyId

    String

    No

    Yes

    The ID of the security policy.

    System and custom security policies are supported.

    Default value: tls_cipher_policy_1_0. This value specifies the system security policy.

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForConfig

    Map

    No

    Yes

    The configurations of the X-Forwarded-For header.

    For more information, see XForwardedForConfig properties.

    LogConfig

    Map

    No

    Yes

    The log configurations.

    For more information, see the "LogConfig properties" section of this topic.

    DefaultActions syntax

    "DefaultActions": [
  {
    "Type": String,
    "ForwardGroupConfig": Map
  }
]

    DefaultActions properties

    Property

    Type

    Required

    Editable

    Description

    Constraint

    ForwardGroupConfig

    Map

    Yes

    Yes

    The configurations of the action.

    For more information, see ForwardGroupConfig property.

    Type

    String

    Yes

    Yes

    The action.

    Set the value to ForwardGroup. This value specifies that requests are forwarded to multiple server groups.

    ForwardGroupConfig syntax

    "ForwardGroupConfig": {
  "ServerGroupTuples": List
}

    ForwardGroupConfig property

    Property

    Type

    Required

    Editable

    Description

    Constraint

    ServerGroupTuples

    List

    Yes

    Yes

    The server groups to which requests are forwarded.

    For more information, see ServerGroupTuples property.

    ServerGroupTuples syntax

    "ServerGroupTuples": [
  {
    "ServerGroupId": String
  }
]

    ServerGroupTuples property

    Property

    Type

    Required

    Editable

    Description

    Constraint

    ServerGroupId

    String

    Yes

    Yes

    The ID of the server group to which requests are forwarded.

    None.

    Certificates syntax

    "Certificates": [
  {
    "CertificateId": String
  }
]

    Certificates property

    Property

    Type

    Required

    Editable

    Description

    Constraint

    CertificateId

    String

    No

    Yes

    The certificate ID.

    Only server certificates are supported.

    QuicConfig syntax

    "QuicConfig": {
  "QuicListenerId": String,
  "QuicUpgradeEnabled": Boolean
}

    QuicConfig properties

    Property

    Type

    Required

    Editable

    Description

    Constraint

    QuicListenerId

    String

    No

    Yes

    The ID of the QUIC listener.

    This property is required if you set QuicUpgradeEnabled to true.

    Note

    • You can configure this property only for HTTPS listeners.

    • You must add the HTTPS listener and the QUIC listener to the same ALB instance. In addition, make sure that the QUIC listener is not associated with another listener.

    QuicUpgradeEnabled

    Boolean

    No

    Yes

    Specifies whether to enable QUIC upgrade.

    Valid values:

    • true

    • false (default)

    Note

    You can configure this property only for HTTPS listeners.

    LogConfig syntax

    "LogConfig": {
  "AccessLogTracingConfig": Map,
  "AccessLogRecordCustomizedHeadersEnabled": Boolean
}

    LogConfig properties

    Property

    Type

    Required

    Editable

    Description

    Constraint

    AccessLogTracingConfig

    Map

    No

    Yes

    The tracing configurations of access logs.

    For more information, see the "AccessLogTracingConfig properties" section of this topic.

    AccessLogRecordCustomizedHeadersEnabled

    Boolean

    No

    Yes

    Specifies whether to record custom headers in access logs.

    Valid values:

    • true

    • false

    AccessLogTracingConfig syntax

    "AccessLogTracingConfig": {
  "TracingSample": Integer,
  "TracingType": String,
  "TracingEnabled": Boolean
}

    AccessLogTracingConfig properties

    Property

    Type

    Required

    Editable

    Description

    Constraint

    TracingSample

    Integer

    No

    Yes

    The sampling rate of tracing.

    Valid values: 1 to 10000.

    Note

    This property takes effect when TracingEnabled is set to true.

    TracingType

    String

    No

    Yes

    The tracing type.

    Set the value to Zipkin.

    Note

    This property takes effect when TracingEnabled is set ot true.

    TracingEnabled

    Boolean

    No

    Yes

    Specifies whether to enable the tracing feature.

    Valid values:

    • true

    • false

    Note

    You can set TracingEnabled to true only when AccessLogEnabled is set to true to enable the access log feature for the ALB instance.

    XForwardedForConfig syntax

    "XForwardedForConfig": {
  "XForwardedForClientCertFingerprintAlias": String,
  "XForwardedForClientCertFingerprintEnabled": Boolean,
  "XForwardedForClientCertIssuerDNAlias": String,
  "XForwardedForClientCertClientVerifyAlias": String,
  "XForwardedForSLBIdEnabled": Boolean,
  "XForwardedForClientCertSubjectDNEnabled": Boolean,
  "XForwardedForClientCertSubjectDNAlias": String,
  "XForwardedForProtoEnabled": Boolean,
  "XForwardedForClientSrcPortEnabled": Boolean,
  "XForwardedForSLBPortEnabled": Boolean,
  "XForwardedForEnabled": Boolean,
  "XForwardedForClientCertIssuerDNEnabled": Boolean,
  "XForwardedForClientCertClientVerifyEnabled": Boolean,
  "XForwardedForClientSourceIpsEnabled": Boolean,
  "XForwardedForClientSourceIpsTrusted": String,
  "XForwardedForProcessingMode": String,
  "XForwardedForHostEnabled": Boolean
}

    XForwardedForConfig properties

    Property

    Type

    Required

    Editable

    Description

    Constraint

    XForwardedForClientCertClientVerifyAlias

    String

    No

    Yes

    The name of the custom header. You can use this property to query the verification result of the client certificate.

    This property takes effect only if you set XForwardedForClientCertClientVerifyEnabled to true.

    The name must be 1 to 40 characters in length and can contain lowercase letters, digits, underscores (_), and hyphens (-).

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertClientVerifyEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Clientcert-clientverify header to query the verification result of the client certificate.

    Valid values:

    • true

    • false (default)

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertFingerprintAlias

    String

    No

    Yes

    The name of the custom header. You can use this property to query the fingerprint of the client certificate.

    This property takes effect only if you set XForwardedForClientCertFingerprintEnabled to true.

    The name must be 1 to 40 characters in length and can contain lowercase letters, digits, underscores (_), and hyphens (-).

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertFingerprintEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Clientcert-fingerprint header to query the fingerprint of the client certificate.

    Valid values:

    • true

    • false (default)

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertIssuerDNAlias

    String

    No

    Yes

    The name of the custom header. You can use this property to query the information about the CA that issues the client certificate.

    This property takes effect only if you set XForwardedForClientCertIssuerDNEnabled to true.

    The name must be 1 to 40 characters in length and can contain lowercase letters, digits, underscores (_), and hyphens (-).

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertIssuerDNEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Clientcert-issuerdn header to query the information about the CA that issues the client certificate.

    Valid values:

    • true

    • false (default)

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertSubjectDNAlias

    String

    No

    Yes

    The name of the custom header. You can use this property to query the information about the owner of the client certificate.

    This property takes effect only if you set XForwardedForClientCertSubjectDNEnabled to true.

    The name must be 1 to 40 characters in length and can contain lowercase letters, digits, underscores (_), and hyphens (-).

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientCertSubjectDNEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Clientcert-subjectdn header to query the information about the owner of the client certificate.

    Valid values:

    • true

    • false (default)

    Note

    You can configure this property only for HTTPS listeners.

    XForwardedForClientSourceIpsEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Client-SourceIps header to query the source port of the client.

    Valid values:

    • true

    • false (default)

    XForwardedForClientSourceIpsTrusted

    String

    No

    Yes

    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.

    XForwardedForClientSrcPortEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Client-Port header to query the client port.

    Valid values:

    • true

    • false (default)

    Note

    You can configure this property for HTTP and HTTPS listeners.

    XForwardedForEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-For header to query the real IP address of the client.

    Valid values:

    • true (default)

    • false

    Note

    You can configure this property for HTTP and HTTPS listeners.

    XForwardedForProtoEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Proto header to query the listener protocol of the ALB instance.

    Valid values:

    • true

    • false (default)

    XForwardedForSLBIdEnabled

    Boolean

    No

    Yes

    Specifies whether to use the SLB-ID header to query the ID of the ALB instance.

    Valid values:

    • true

    • false (default)

    XForwardedForSLBPortEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Port header to query the listener port of the ALB instance.

    Valid values:

    • true

    • false (default)

    XForwardedForProcessingMode

    String

    No

    Yes

    The method to handle the X-Forwarded-For header.

    This property takes effect only when XForwardedForEnabled is set to true. Valid values:

    • append (default)

    • remove

    Note

    • If you set XForwardedForProcessingMode to append, ALB appends the IP address of the last hop to the existingX-Forwarded-For header in the request before the request is sent to backend servers.

    • If you set XForwardedForProcessingMode to remove，ALB removes the X-Forwarded-For header in the request before the request is sent to backend servers, no matter whether the request carries the X-Forwarded-For header.

    • HTTP and HTTPS listeners support this property.

    XForwardedForHostEnabled

    Boolean

    No

    Yes

    Specifies whether to use the X-Forwarded-Host header to query the client domain name of the ALB instance.

    Vlaid values:

    • true

    • false (default)

    Note

    HTTP, HTTPS, and QUIC listeners support this property.

    CaCertificates syntax

    "CaCertificates": [
  {
    "CertificateId": String
  }
]

    CaCertificates property

    Property

    Type

    Required

    Editable

    Description

    Constraint

    CertificateId

    String

    No

    Yes

    The ID of the CA certificate.

    None.

    Return values

    Fn::GetAtt

    ListenerId: the ID of the listener.

    LoadBalancerId: the ID of the ALB instance.

    Examples

    YAML format

    ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  LoadBalancerId:
    Type: String
    Description: The ID of the ALB instance.
    Default: lb-bp1iilcd9ujny84z8****
Resources:
  Listener:
    Type: ALIYUN::ALB::Listener
    Properties:
      ListenerPort: 80
      DefaultActions:
        - ForwardGroupConfig:
            ServerGroupTuples:
              - ServerGroupId: sgp-46ndzg2wz4v5mp****
          Type: ForwardGroup
      LoadBalancerId:
        Ref: LoadBalancerId
      ListenerProtocol: HTTP
Outputs:
  ListenerId:
    Description: The ID of the listener.
    Value:
      Fn::GetAtt:
        - Listener
        - ListenerId

    JSON format

    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "LoadBalancerId": {
      "Type": "String",
      "Description": "The ID of the ALB instance.",
      "Default": "lb-bp1iilcd9ujny84z8****"
    }
  },
  "Resources": {
    "Listener": {
      "Type": "ALIYUN::ALB::Listener",
      "Properties": {
        "ListenerPort": 80,
        "DefaultActions": [
          {
            "ForwardGroupConfig": {
              "ServerGroupTuples": [
                {
                  "ServerGroupId": "sgp-46ndzg2wz4v5mp****"
                }
              ]
            },
            "Type": "ForwardGroup"
          }
        ],
        "LoadBalancerId": {
          "Ref": "LoadBalancerId"
        },
        "ListenerProtocol": "HTTP"
      }
    }
  },
  "Outputs": {
    "ListenerId": {
      "Description": "The ID of the listener.",
      "Value": {
        "Fn::GetAtt": [
          "Listener",
          "ListenerId"
        ]
      }
    }
  }
}