Menu
Elastic Load Balancing
API Reference (API Version 2015-12-01)

CreateRule

Creates a rule for the specified listener. The listener must be associated with an Application Load Balancer.

Rules are evaluated in priority order, from the lowest value to the highest value. When the condition for a rule is met, the specified action is taken. If no conditions are met, the action for the default rule is taken. For more information, see Listener Rules in the Application Load Balancers Guide.

To view your current rules, use DescribeRules. To update a rule, use ModifyRule. To set the priorities of your rules, use SetRulePriorities. To delete a rule, use DeleteRule.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

Actions.member.N

An action. Each action has the type forward and specifies a target group.

Type: Array of Action objects

Required: Yes

Conditions.member.N

The conditions. Each condition specifies a field name and a single value.

If the field name is host-header, you can specify a single host name (for example, my.example.com). A host name is case insensitive, can be up to 128 characters in length, and can contain any of the following characters. Note that you can include up to three wildcard characters.

  • A-Z, a-z, 0-9

  • - .

  • * (matches 0 or more characters)

  • ? (matches exactly 1 character)

If the field name is path-pattern, you can specify a single path pattern. A path pattern is case sensitive, can be up to 128 characters in length, and can contain any of the following characters. Note that you can include up to three wildcard characters.

  • A-Z, a-z, 0-9

  • _ - . $ / ~ " ' @ : +

  • & (using &)

  • * (matches 0 or more characters)

  • ? (matches exactly 1 character)

Type: Array of RuleCondition objects

Required: Yes

ListenerArn

The Amazon Resource Name (ARN) of the listener.

Type: String

Required: Yes

Priority

The priority for the rule. A listener can't have multiple rules with the same priority.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 50000.

Required: Yes

Response Elements

The following element is returned by the service.

Rules.member.N

Information about the rule.

Type: Array of Rule objects

Errors

For information about the errors that are common to all actions, see Common Errors.

IncompatibleProtocols

The specified configuration is not valid with this protocol.

HTTP Status Code: 400

InvalidConfigurationRequest

The requested configuration is not valid.

HTTP Status Code: 400

ListenerNotFound

The specified listener does not exist.

HTTP Status Code: 400

PriorityInUse

The specified priority is in use.

HTTP Status Code: 400

TargetGroupAssociationLimit

You've reached the limit on the number of load balancers per target group.

HTTP Status Code: 400

TargetGroupNotFound

The specified target group does not exist.

HTTP Status Code: 400

TooManyRegistrationsForTargetId

You've reached the limit on the number of times a target can be registered with a load balancer.

HTTP Status Code: 400

TooManyRules

You've reached the limit on the number of rules per load balancer.

HTTP Status Code: 400

TooManyTargetGroups

You've reached the limit on the number of target groups for your AWS account.

HTTP Status Code: 400

TooManyTargets

You've reached the limit on the number of targets.

HTTP Status Code: 400

Example

Create a rule

This example creates a rule that forwards requests to the specified target group if the URL contains the specified pattern (for example, /img/*).

Sample Request

https://elasticloadbalancing.amazonaws.com/?Action=CreateRule
&ListenerArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2
&Priority=10
&Conditions.member.1.Field=path-pattern
&Conditions.member.1.Values.member.1=/img/*
&Actions.member.1.Type=forward
&Actions.member.1.TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067
&Version=2015-12-01
&AUTHPARAMS

Sample Response

<CreateRuleResponse xmlns="http://elasticloadbalancing.amazonaws.com/doc/2015-12-01/">
  <CreateRuleResult> 
    <Rules> 
      <member> 
        <IsDefault>false</IsDefault> 
        <Conditions> 
          <member> 
            <Field>path-pattern</Field> 
            <Values> 
              <member>/img/*</member> 
            </Values> 
          </member> 
        </Conditions> 
        <Priority>10</Priority> 
        <Actions> 
          <member> 
            <Type>forward</Type> 
            <TargetGroupArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067</TargetGroupArn> 
          </member> 
        </Actions> 
        <RuleArn>arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2/9683b2d02a6cabee</RuleArn> 
      </member> 
    </Rules> 
  </CreateRuleResult> 
  <ResponseMetadata> 
    <RequestId>c5478c83-f397-11e5-bb98-57195a6eb84a</RequestId> 
  </ResponseMetadata>
</CreateRuleResponse>

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: