Creating a Listener Rule

You can create a listener rule to manage redirection of incoming traffic between a load balancer and its backend virtual machines (VMs).

This action creates a pattern associated with a specified listener, based on a path in the URI of the request. Listener rules are treated in priority order, from the highest value to the lowest value.

To modify the pattern of an existing rule, see Modifying a Listener Rule.

When creating the listener rule, you need to register all target backends with it. To modify the list of backend VMs for a listener rule, you need to delete the rule and create a new one.

Creating a Listener Rule Using OSC CLI

The CreateListenerRule command creates a rule for traffic redirection for the specified listener. Each rule must have either the HostNamePattern or PathPattern parameter specified. Rules are treated in priority order, from the highest value to the lowest value.
Once the rule is created, you need to register backend VMs with it. For more information, see the RegisterVmsInLoadBalancer method.

For more information, see About Load Balancers.

Request sample: Creating a listener rule based on a host pattern
$ osc-cli api CreateListenerRule --profile "default" \
    --Listener '{
        "LoadBalancerName": "example-lbu",
        "LoadBalancerPort": 80
      }' \
    --ListenerRule '{
        "Action": "forward",
        "HostNamePattern": "*.example.com",
        "ListenerRuleName": "example-listener-rule",
        "Priority": 10
      }' \
    --VmIds '["i-12345678"]'
Request sample: Creating a listener rule based on a path pattern
$ osc-cli api CreateListenerRule --profile "default" \
    --Listener '{
        "LoadBalancerName": "example-lbu",
        "LoadBalancerPort": 80
      }' \
    --ListenerRule '{
        "Action": "forward",
        "PathPattern": "/docs/*",
        "ListenerRuleName": "example-listener-rule",
        "Priority": 100
      }' \
    --VmIds '["i-12345678"]'

This command contains the following attributes that you need to specify:

  • DryRun: (optional) If true, checks whether you have the required permissions to perform the action.

  • Listener: Information about the load balancer.

    • LoadBalancerName: The name of the load balancer to which the listener is attached.

    • LoadBalancerPort: The port of load balancer on which the load balancer is listening (between 1 and 65535 both included).

  • ListenerRule: Information about the listener rule.

    • Action: (optional) The type of action for the rule (always forward).

    • HostNamePattern: (optional) A host-name pattern for the rule, with a maximum length of 128 characters. This host-name pattern supports maximum three wildcards, and must not contain any special characters except -.?.

    • ListenerRuleName: A human-readable name for the listener rule.

    • PathPattern: (optional) A path pattern for the rule, with a maximum length of 128 characters. This path pattern supports maximum three wildcards, and must not contain any special characters except _-.$/~"'@:+?.

    • Priority: The priority level of the listener rule, between 1 and 19999 both included. Each rule must have a unique priority level. Otherwise, an error is returned.

  • VmIds: The IDs of the backend VMs.

The CreateListenerRule command returns the following elements:

  • ListenerRule: Information about the listener rule.

    • Action: The type of action for the rule (always forward).

    • HostNamePattern: A host-name pattern for the rule, with a maximum length of 128 characters. This host-name pattern supports maximum three wildcards, and must not contain any special characters except -.?.

    • ListenerId: The ID of the listener.

    • ListenerRuleId: The ID of the listener rule.

    • ListenerRuleName: A human-readable name for the listener rule.

    • PathPattern: A path pattern for the rule, with a maximum length of 128 characters. This path pattern supports maximum three wildcards, and must not contain any special characters except _-.$/~"'@:+?.

    • Priority: The priority level of the listener rule, between 1 and 19999 both included. Each rule must have a unique priority level. Otherwise, an error is returned.

    • VmIds: The IDs of the backend VMs.

  • ResponseContext: Information about the context of the response.

    • RequestId: The ID of the request.

Result sample: Creating a listener rule based on a host pattern
{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "ListenerRule": {
    "Priority": 10,
    "VmIds": [
      "i-12345678"
    ],
    "ListenerRuleName": "example-listener-rule",
    "Action": "forward",
    "ListenerId": 123456,
    "HostNamePattern": "*.example.com",
    "ListenerRuleId": 1234
  }
}
Result sample: Creating a listener rule based on a path pattern
{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "ListenerRule": {
    "Priority": 100,
    "VmIds": [
      "i-12345678"
    ],
    "ListenerRuleName": "example-listener-rule",
    "Action": "forward",
    "ListenerId": 123456,
    "PathPattern": "/docs/*",
    "ListenerRuleId": 1234
  }
}

Creating a Listener Rule Using oapi-cli

The CreateListenerRule command creates a rule for traffic redirection for the specified listener. Each rule must have either the HostNamePattern or PathPattern parameter specified. Rules are treated in priority order, from the highest value to the lowest value.
Once the rule is created, you need to register backend VMs with it. For more information, see the RegisterVmsInLoadBalancer method.

For more information, see About Load Balancers.

Request sample: Creating a listener rule based on a host pattern
$ oapi-cli --profile "default" CreateListenerRule \
    --Listener '{
        "LoadBalancerName": "example-lbu",
        "LoadBalancerPort": 80
      }' \
    --ListenerRule '{
        "Action": "forward",
        "HostNamePattern": "*.example.com",
        "ListenerRuleName": "example-listener-rule",
        "Priority": 10
      }' \
    --VmIds '["i-12345678"]'
Request sample: Creating a listener rule based on a path pattern
$ oapi-cli --profile "default" CreateListenerRule \
    --Listener '{
        "LoadBalancerName": "example-lbu",
        "LoadBalancerPort": 80
      }' \
    --ListenerRule '{
        "Action": "forward",
        "PathPattern": "/docs/*",
        "ListenerRuleName": "example-listener-rule",
        "Priority": 100
      }' \
    --VmIds '["i-12345678"]'

This command contains the following attributes that you need to specify:

  • DryRun: (optional) If true, checks whether you have the required permissions to perform the action.

  • Listener: Information about the load balancer.

    • LoadBalancerName: The name of the load balancer to which the listener is attached.

    • LoadBalancerPort: The port of load balancer on which the load balancer is listening (between 1 and 65535 both included).

  • ListenerRule: Information about the listener rule.

    • Action: (optional) The type of action for the rule (always forward).

    • HostNamePattern: (optional) A host-name pattern for the rule, with a maximum length of 128 characters. This host-name pattern supports maximum three wildcards, and must not contain any special characters except -.?.

    • ListenerRuleName: A human-readable name for the listener rule.

    • PathPattern: (optional) A path pattern for the rule, with a maximum length of 128 characters. This path pattern supports maximum three wildcards, and must not contain any special characters except _-.$/~"'@:+?.

    • Priority: The priority level of the listener rule, between 1 and 19999 both included. Each rule must have a unique priority level. Otherwise, an error is returned.

  • VmIds: The IDs of the backend VMs.

The CreateListenerRule command returns the following elements:

  • ListenerRule: Information about the listener rule.

    • Action: The type of action for the rule (always forward).

    • HostNamePattern: A host-name pattern for the rule, with a maximum length of 128 characters. This host-name pattern supports maximum three wildcards, and must not contain any special characters except -.?.

    • ListenerId: The ID of the listener.

    • ListenerRuleId: The ID of the listener rule.

    • ListenerRuleName: A human-readable name for the listener rule.

    • PathPattern: A path pattern for the rule, with a maximum length of 128 characters. This path pattern supports maximum three wildcards, and must not contain any special characters except _-.$/~"'@:+?.

    • Priority: The priority level of the listener rule, between 1 and 19999 both included. Each rule must have a unique priority level. Otherwise, an error is returned.

    • VmIds: The IDs of the backend VMs.

  • ResponseContext: Information about the context of the response.

    • RequestId: The ID of the request.

Result sample: Creating a listener rule based on a host pattern
{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "ListenerRule": {
    "Priority": 10,
    "VmIds": [
      "i-12345678"
    ],
    "ListenerRuleName": "example-listener-rule",
    "Action": "forward",
    "ListenerId": 123456,
    "HostNamePattern": "*.example.com",
    "ListenerRuleId": 1234
  }
}
Result sample: Creating a listener rule based on a path pattern
{
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  },
  "ListenerRule": {
    "Priority": 100,
    "VmIds": [
      "i-12345678"
    ],
    "ListenerRuleName": "example-listener-rule",
    "Action": "forward",
    "ListenerId": 123456,
    "PathPattern": "/docs/*",
    "ListenerRuleId": 1234
  }
}

Related Pages

Corresponding API Methods

Export to PDF