All Products
Search
Document Center

Resource Orchestration Service:ALIYUN::SLB::Listener

Last Updated:Dec 05, 2023

ALIYUN::SLB::Listener is used to create a Server Load Balancer (SLB) listener.

Syntax

{
  "Type": "ALIYUN::SLB::Listener",
  "Properties": {
    "MasterSlaveServerGroupId": String,
    "AclStatus": String,
    "Protocol": String,
    "AclId": String,
    "ServerCertificateId": String,
    "HealthCheck": Map,
    "RequestTimeout": Integer,
    "IdleTimeout": Integer,
    "ListenerPort": Integer,
    "HttpConfig": Map,
    "Bandwidth": Integer,
    "AclType": String,
    "BackendServerPort": Integer,
    "Scheduler": String,
    "LoadBalancerId": String,
    "CACertificateId": String,
    "Persistence": Map,
    "VServerGroupId": String,
    "Description": String,
    "PortRange": List,
    "StartListener": Boolean,
    "EnableHttp2": String,
    "Gzip": String,
    "TLSCipherPolicy": String,
    "AclIds": List
  }
}

Properties

Property

Type

Required

Editable

Description

Constraint

MasterSlaveServerGroupId

String

No

No

The ID of the primary/secondary server group.

None.

AclStatus

String

No

Yes

Specifies whether to enable the access control feature.

Valid values:

  • on (default)

  • off

EnableHttp2

String

No

Yes

Specifies whether to enable HTTP/2.

Valid values:

  • on

  • off

AclId

String

No

Yes

The ID of the access control list (ACL) that you want to associate with the listener.

This property is required if you set the AclStatus property to on.

AclType

String

No

Yes

The ACL type.

Valid values:

  • white: an IP address whitelist. Only requests from the IP addresses or CIDR blocks in the whitelist are forwarded. You can use an IP address whitelist in scenarios in which you want to allow access from only specific IP addresses to an application. Risks may arise if a whitelist is improperly configured. After you configure an IP address whitelist, only the IP addresses that are added to the IP address whitelist can access the listener. If you enable an IP address whitelist but do not add an IP address to the whitelist, the listener does not forward requests.

  • black: an IP address blacklist. All requests from the IP addresses or CIDR blocks in the blacklist are not forwarded. You can use an IP address blacklist in scenarios in which you want to deny access from only specific IP addresses to an application. If you enable an IP address blacklist but do not add an IP address to the blacklist, the listener forwards all requests. This property is required if you set the AclStatus property to on.

Protocol

String

Yes

No

The network protocol.

Valid values:

  • http

  • https

  • tcp

  • udp

ListenerPort

Integer

Yes

No

The frontend port that you want to use for the SLB instance.

Valid values: 1 to 65535.

Bandwidth

Integer

Yes

No

The bandwidth limit of the listener.

Valid values: 1 to 1000 and -1.

Unit: Mbit/s.

Valid values:

  • For a pay-by-bandwidth Internet-facing SLB instance, you cannot set this property to -1. The sum of maximum bandwidth values that you specify for all listeners of an SLB instance cannot exceed the bandwidth value of the SLB instance.

  • For a pay-by-data-transfer Internet-facing SLB instance, you can set this property to -1. The value -1 specifies that the bandwidth is unlimited.

BackendServerPort

Integer

No

No

The backend port that you want to use for the SLB instance.

Valid values: 1 to 65535.

LoadBalancerId

String

Yes

No

The ID of the SLB instance.

None.

HealthCheck

Map

No

No

The configuration of the health check feature.

For more information, see HealthCheck properties.

Persistence

Map

No

Yes

The configuration of persistence properties.

For more information, see Persistence properties.

Scheduler

String

No

No

The routing algorithm.

Valid values:

  • wrr (default): Backend servers that have higher weights receive more requests than backend servers that have lower weights.

  • wlc: Requests are distributed to backend servers in sequence.

CACertificateId

String

No

No

The ID of the certification authority (CA) certificate.

This property takes effect only if you set the Protocol property to https.

ServerCertificateId

String

No

Yes

The ID of the server certificate.

This property is required only if you set the Protocol property to https.

VServerGroupId

String

No

No

The ID of the server group.

None.

RequestTimeout

Integer

No

No

The timeout period of a request.

Valid values: 1 to 180.

Unit: seconds.

IdleTimeout

Integer

No

No

The timeout period of an idle connection.

Valid values: 1 to 60.

Unit: seconds.

HttpConfig

Map

No

No

The configuration of the HTTP protocol.

For more information, see HttpConfig properties.

Description

String

No

No

The description of the listener.

The description must be 1 to 80 characters in length and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), and underscores (_).

PortRange

List

No

No

The port range of the listener.

You must enable all ports. To enable all ports, set the StartPort property to 1 and the EndPort property to 65535.

For more information, see PortRange properties.

StartListener

Boolean

No

No

Specifies whether to start the listener.

Valid values:

  • true (default)

  • false

Gzip

String

No

Yes

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

Valid values:

  • true (default)

  • false

TLSCipherPolicy

String

No

Yes

The transport layer security (TLS) policy.

A TLS policy contains TLS protocol versions and cipher suites that are available for HTTPS.  

Note

This property takes effect only when you set the Protocol property to https.

AclIds

List

No

Yes

The IDs of the ACLs that you want to associate with the listener.

This property is required if you set the AclStatus property to on. The AclIds property takes precedence over the AclId property.  

HealthCheck syntax

"HealthCheck": {
  "Domain": String,
  "Interval": Integer,
  "URI": String,
  "HttpCode": String,
  "HealthyThreshold": Integer,
  "HealthCheckType": String,
  "Timeout": Integer,
  "UnhealthyThreshold": Integer,
  "Port": Integer,
  "Switch": String,
  "HealthCheckMethod": String
}

HealthCheck properties

Property

Type

Required

Editable

Description

Constraint

Domain

String

No

No

The domain name that you want to use for health checks.

Valid values:

  • $_ip

  • Custom string. The custom string that you specify must be 1 to 80 characters in length and can contain letters, digits, hyphens (-), and periods (.).

  • Null.

Note

If you set this property to $_ip or Null, SLB uses the private IP address of each backend server as the domain name to perform health checks.

Interval

Integer

No

No

The interval at which the system performs health checks.

Valid values: 1 to 5.

Unit: seconds.

URI

String

No

No

The Uniform Resource Identifier (URI) that you want to use for health checks.

The URI must be 1 to 80 characters in length and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), percent signs (%), question marks (?), number signs (#), and ampersands (&). The URI must start with a forward slash (/).

HttpCode

String

No

No

The HTTP status code

Valid values:

  • http_2xx (default)

  • http_3xx

  • http_4xx

  • http_5xx

Separate multiple HTTP status codes with commas (,).

HealthyThreshold

Integer

No

No

The threshold that is used to determine whether a backend server is healthy. The value specifies the number of times that an unhealthy backend server must consecutively pass health checks before it is declared healthy. When this threshold is reached, the health check status is changed from failed to successful.

Valid values: 1 to 10.

HealthCheckType

String

No

No

The type of the health check.

Valid values:

  • tcp

  • http

Timeout

Integer

No

No

The timeout period of a health check response.

Valid values: 1 to 50.

Unit: seconds.

Note

This property takes effect only when the value of the Timeout property is greater than or equal to the value of the Interval property. Otherwise, the value of the Timeout property is overwritten by the value of the Interval property.

UnhealthyThreshold

Integer

No

No

The threshold that is used to determine whether a backend server is unhealthy. The value specifies the number of times that a healthy backend server must consecutively fail health checks before it is declared unhealthy. When this number is reached, the health check status is changed from successful to failed.

Valid values: 1 to 10.

Port

Integer

No

No

The port that you want to use for health checks.

Valid values: 0 to 65535.

Switch

String

No

No

Specifies whether to enable the health check feature.

Valid values:

  • on

  • off

Note

This property takes effect only when you set the Protocol property to http or https. If you leave the Switch property empty, the health check feature is disabled unless health check items are already configured.

HealthCheckMethod

String

No

No

The method that you want to use to perform health checks.

Valid values:

  • head

  • get

Note

This property takes effect when you set the Protocol property to https or http and set the Switch property to on.

Persistence syntax

"Persistence": {
  "PersistenceTimeout": Integer,
  "CookieTimeout": Integer,
  "XForwardedFor": String,
  "XForwardedFor_SLBID": String,
  "XForwardedFor_proto": String,
  "XForwardedFor_SLBIP": String,
  "Cookie": String,
  "StickySession": String,
  "StickySessionType": String,
  "XForwardedFor_ClientSrcPort": String,
  "XForwardedFor_SLBPORT": String
}

Persistence properties

Property

Type

Required

Editable

Description

Constraint

StickySession

String

No

Yes

Specifies whether to enable session persistence.

Valid values:

  • on

  • off

    Note

    This property takes effect only when you set the Protocol property to http and https.

PersistenceTimeout

Integer

No

Yes

The timeout period of session persistence.

Valid values: 0 to 1000.

Default value: 0. The value 0 specifies that session persistence is disabled.

Unit: seconds.

CookieTimeout

Integer

No

Yes

The timeout period of the cookie.

Valid values: 1 to 86400.

Unit: seconds.

Note

This property is required if you set the StickySession property to on and the StickySessionType property to insert.

XForwardedFor

String

No

Yes

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

Valid values:

  • on

  • off (default)

XForwardedFor_proto

String

No

Yes

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

Valid values:

  • on

  • off (default)

XForwardedFor_SLBID

String

No

Yes

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

Valid values:

  • on

  • off (default)

XForwardedFor_SLBIP

String

No

Yes

Specifies whether to use the SLB-IP header to query the real IP address that is requested by a client.

Valid values:

  • on

  • off (default)

Cookie

String

No

Yes

The cookie that you want to configure for the server.

The cookie must be 1 to 200 characters in length, and cannot start with a dollar sign ($). The cookie can contain letters and digits but cannot contain commas (,), semicolons (;), or spaces.

Note

This property is required if you set the StickySession property to on and the StickySessionType property to server.

StickySessionType

String

No

Yes

The method that you want to use to handle the cookie.

Valid values:

  • insert: inserts the cookie.

  • server: rewrites the cookie.

Note

This property is required if you set the StickySession property to on.

XForwardedFor_ClientSrcPort

String

No

Yes

Specifies whether to use the X-Forwarded-Client-srcport header to query the port that is used by a client to access the SLB instance.

Valid values:

  • on

  • off (default)

XForwardedFor_SLBPORT

String

No

Yes

Specifies whether to use the XForwardedFor_SLBPORT header to query the listener port of the SLB instance.

Valid values:

  • on

  • off (default)

HttpConfig syntax

"HttpConfig": {
  "ForwardPort": Integer,
  "ListenerForward": String
}

HttpConfig properties

Property

Type

Required

Editable

Description

Constraint

ForwardPort

Integer

No

No

The listener port that is used to redirect HTTP requests to HTTPS.

Valid values: 1 to 65535.

Default value: 443.

ListenerForward

String

No

No

Specifies whether to redirect HTTP requests to HTTPS.

Valid values:

  • on

  • off (default)

PortRange syntax

"PortRange": [
  {
    "StartPort": Integer,
    "EndPort": Integer
  }
]

PortRange properties

Property

Type

Required

Editable

Description

Constraint

StartPort

Integer

Yes

No

The start number of the port range.

Set the value to 1.

EndPort

Integer

Yes

No

The end number of the port range.

Set the value to 65535.

Return values

Fn::GetAtt

  • LoadBalancerId: the SLB instance ID.

  • ListenerPortsAndProtocol: the frontend ports and protocol that are used by the SLB instance.

Examples

YAML format

ROSTemplateFormatVersion: '2015-09-01'
Description: Test SLB Listener
Parameters:
  SlbInstanceId:
    AssociationProperty: ALIYUN::SLB::Instance::InstanceId
    Type: String
Resources:
  Listener:
    Type: ALIYUN::SLB::Listener
    Properties:
      BackendServerPort: 8080
      Bandwidth: 50
      ListenerPort: 80
      LoadBalancerId:
        Ref: SlbInstanceId
      Protocol: https
      Scheduler: wrr
Outputs: {}

JSON format

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Description": "Test SLB Listener",
  "Parameters": {
    "SlbInstanceId": {
      "AssociationProperty": "ALIYUN::SLB::Instance::InstanceId",
      "Type": "String"
    }
  },
  "Resources": {
    "Listener": {
      "Type": "ALIYUN::SLB::Listener",
      "Properties": {
        "BackendServerPort": 8080,
        "Bandwidth": 50,
        "ListenerPort": 80,
        "LoadBalancerId": {
          "Ref": "SlbInstanceId"
        },
        "Protocol": "https",
        "Scheduler": "wrr"
      }
    }
  },
  "Outputs": {
  }
}

For more examples, visit Listener.json and Listener.yml. In the examples, the following resource types are used: ALIYUN::SLB::Listener, ALIYUN::SLB::LoadBalancerClone, ALIYUN::SLB::Certificate, ALIYUN::SLB::DomainExtension, ALIYUN::SLB::VServerGroup, ALIYUN::SLB::Rule, and ALIYUN::SLB::BackendServerToVServerGroupAddition.