Table Of Contents

Feedback

User Guide

First time using the AWS CLI? See the User Guide for help getting started.

[ aws . elbv2 ]

create-rule

Description

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 conditions for a rule are met, its actions are performed. If the conditions for no rules are met, the actions for the default rule are performed. 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 .

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.

Synopsis

  create-rule
--listener-arn <value>
--conditions <value>
--priority <value>
--actions <value>
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]

Options

--listener-arn (string)

The Amazon Resource Name (ARN) of the listener.

--conditions (list)

The conditions. Each rule can include zero or one of the following conditions: http-request-method , host-header , path-pattern , and source-ip , and zero or more of the following conditions: http-header and query-string .

JSON Syntax:

[
  {
    "Field": "string",
    "Values": ["string", ...],
    "HostHeaderConfig": {
      "Values": ["string", ...]
    },
    "PathPatternConfig": {
      "Values": ["string", ...]
    },
    "HttpHeaderConfig": {
      "HttpHeaderName": "string",
      "Values": ["string", ...]
    },
    "QueryStringConfig": {
      "Values": [
        {
          "Key": "string",
          "Value": "string"
        }
        ...
      ]
    },
    "HttpRequestMethodConfig": {
      "Values": ["string", ...]
    },
    "SourceIpConfig": {
      "Values": ["string", ...]
    }
  }
  ...
]

--priority (integer)

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

--actions (list)

The actions. Each rule must include exactly one of the following types of actions: forward , fixed-response , or redirect , and it must be the last action to be performed.

If the action type is forward , you specify one or more target groups. The protocol of the target group must be HTTP or HTTPS for an Application Load Balancer. The protocol of the target group must be TCP, TLS, UDP, or TCP_UDP for a Network Load Balancer.

[HTTPS listeners] If the action type is authenticate-oidc , you authenticate users through an identity provider that is OpenID Connect (OIDC) compliant.

[HTTPS listeners] If the action type is authenticate-cognito , you authenticate users through the user pools supported by Amazon Cognito.

[Application Load Balancer] If the action type is redirect , you redirect specified client requests from one URL to another.

[Application Load Balancer] If the action type is fixed-response , you drop specified client requests and return a custom HTTP response.

JSON Syntax:

[
  {
    "Type": "forward"|"authenticate-oidc"|"authenticate-cognito"|"redirect"|"fixed-response",
    "TargetGroupArn": "string",
    "AuthenticateOidcConfig": {
      "Issuer": "string",
      "AuthorizationEndpoint": "string",
      "TokenEndpoint": "string",
      "UserInfoEndpoint": "string",
      "ClientId": "string",
      "ClientSecret": "string",
      "SessionCookieName": "string",
      "Scope": "string",
      "SessionTimeout": long,
      "AuthenticationRequestExtraParams": {"string": "string"
        ...},
      "OnUnauthenticatedRequest": "deny"|"allow"|"authenticate",
      "UseExistingClientSecret": true|false
    },
    "AuthenticateCognitoConfig": {
      "UserPoolArn": "string",
      "UserPoolClientId": "string",
      "UserPoolDomain": "string",
      "SessionCookieName": "string",
      "Scope": "string",
      "SessionTimeout": long,
      "AuthenticationRequestExtraParams": {"string": "string"
        ...},
      "OnUnauthenticatedRequest": "deny"|"allow"|"authenticate"
    },
    "Order": integer,
    "RedirectConfig": {
      "Protocol": "string",
      "Port": "string",
      "Host": "string",
      "Path": "string",
      "Query": "string",
      "StatusCode": "HTTP_301"|"HTTP_302"
    },
    "FixedResponseConfig": {
      "MessageBody": "string",
      "StatusCode": "string",
      "ContentType": "string"
    },
    "ForwardConfig": {
      "TargetGroups": [
        {
          "TargetGroupArn": "string",
          "Weight": integer
        }
        ...
      ],
      "TargetGroupStickinessConfig": {
        "Enabled": true|false,
        "DurationSeconds": integer
      }
    }
  }
  ...
]

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.

Examples

Example 1: To create a rule using a path condition and a forward action

The following create-rule example creates a rule that forwards requests to the specified target group if the URL contains the specified pattern.

aws elbv2 create-rule \
    --listener-arn arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2 \
    --priority 5 \
    --conditions file://conditions-pattern.json
    --actions Type=forward,TargetGroupArn=arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067

Contents of conditions-pattern.json:

[
    {
        "Field": "path-pattern",
        "PathPatternConfig": {
            "Values": ["/images/*"]
        }
    }
]

Example 2: To create a rule using a host condition and a fixed response

The following create-rule example creates a rule that provides a fixed response if the hostname in the host header matches the specified hostname.

aws elbv2 create-rule \
    --listener-arn arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2 \
    --priority 10 \
    --conditions file://conditions-host.json \
    --actions file://actions-fixed-response.json

Contents of conditions-host.json

[
  {
      "Field": "host-header",
      "HostHeaderConfig": {
          "Values": ["*.example.com"]
      }
  }
]

Contents of actions-fixed-response.json

[
    {
        "Type": "fixed-response",
        "FixedResponseConfig": {
            "MessageBody": "Hello world",
            "StatusCode": "200",
            "ContentType": "text/plain"
        }
    }
]

Example 3: To create a rule using a source IP address condition, an authenticate action, and a forward action

The following create-rule example creates a rule that authenticates the user if the source IP address matches the specified IP address, and forwards the request to the specified target group if authentication is successful.

aws elbv2 create-rule \
    --listener-arn arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2 \
    --priority 20 \
    --conditions file://conditions-source-ip.json \
    --actions file://actions-authenticate.json

Contents of conditions-source-ip.json

[
    {
        "Field": "source-ip",
        "SourceIpConfig": {
            "Values": ["192.0.2.0/24", "198.51.100.10/32"]
        }
    }
]

Contents of actions-authenticate.json

[
    {
        "Type": "authenticate-oidc",
        "AuthenticateOidcConfig": {
            "Issuer": "https://idp-issuer.com",
            "AuthorizationEndpoint": "https://authorization-endpoint.com",
            "TokenEndpoint": "https://token-endpoint.com",
            "UserInfoEndpoint": "https://user-info-endpoint.com",
            "ClientId": "abcdefghijklmnopqrstuvwxyz123456789",
            "ClientSecret": "123456789012345678901234567890",
            "SessionCookieName": "my-cookie",
            "SessionTimeout": 3600,
            "Scope": "email",
            "AuthenticationRequestExtraParams": {
                "display": "page",
                "prompt": "login"
            },
            "OnUnauthenticatedRequest": "deny"
        },
        "Order": 1
    },
    {
        "Type": "forward",
        "TargetGroupArn": "arn:aws:elasticloadbalancing:us-east-1:880185128111:targetgroup/cli-test/642a97ecb0e0f26b",
        "Order": 2
    }
]

Output

Rules -> (list)

Information about the rule.

(structure)

Information about a rule.

RuleArn -> (string)

The Amazon Resource Name (ARN) of the rule.

Priority -> (string)

The priority.

Conditions -> (list)

The conditions. Each rule can include zero or one of the following conditions: http-request-method , host-header , path-pattern , and source-ip , and zero or more of the following conditions: http-header and query-string .

(structure)

Information about a condition for a rule.

Field -> (string)

The field in the HTTP request. The following are the possible values:

  • http-header
  • http-request-method
  • host-header
  • path-pattern
  • query-string
  • source-ip

Values -> (list)

The condition value. You can use Values if the rule contains only host-header and path-pattern conditions. Otherwise, you can use HostHeaderConfig for host-header conditions and PathPatternConfig for path-pattern conditions.

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

  • A-Z, a-z, 0-9
    • .
    • (matches 0 or more characters)
  • ? (matches exactly 1 character)

If Field is path-pattern , you can specify a single path pattern (for example, /img/*). A path pattern is case-sensitive, can be up to 128 characters in length, and can contain any of the following characters.

  • A-Z, a-z, 0-9
  • _ - . $ / ~ " ' @ : +
  • (using amp;)
    • (matches 0 or more characters)
  • ? (matches exactly 1 character)

(string)

HostHeaderConfig -> (structure)

Information for a host header condition. Specify only when Field is host-header .

Values -> (list)

One or more host names. The maximum size of each name is 128 characters. The comparison is case insensitive. The following wildcard characters are supported: * (matches 0 or more characters) and ? (matches exactly 1 character).

If you specify multiple strings, the condition is satisfied if one of the strings matches the host name.

(string)

PathPatternConfig -> (structure)

Information for a path pattern condition. Specify only when Field is path-pattern .

Values -> (list)

One or more path patterns to compare against the request URL. The maximum size of each string is 128 characters. The comparison is case sensitive. The following wildcard characters are supported: * (matches 0 or more characters) and ? (matches exactly 1 character).

If you specify multiple strings, the condition is satisfied if one of them matches the request URL. The path pattern is compared only to the path of the URL, not to its query string. To compare against the query string, use QueryStringConditionConfig .

(string)

HttpHeaderConfig -> (structure)

Information for an HTTP header condition. Specify only when Field is http-header .

HttpHeaderName -> (string)

The name of the HTTP header field. The maximum size is 40 characters. The header name is case insensitive. The allowed characters are specified by RFC 7230. Wildcards are not supported.

You can't use an HTTP header condition to specify the host header. Use HostHeaderConditionConfig to specify a host header condition.

Values -> (list)

One or more strings to compare against the value of the HTTP header. The maximum size of each string is 128 characters. The comparison strings are case insensitive. The following wildcard characters are supported: * (matches 0 or more characters) and ? (matches exactly 1 character).

If the same header appears multiple times in the request, we search them in order until a match is found.

If you specify multiple strings, the condition is satisfied if one of the strings matches the value of the HTTP header. To require that all of the strings are a match, create one condition per string.

(string)

QueryStringConfig -> (structure)

Information for a query string condition. Specify only when Field is query-string .

Values -> (list)

One or more key/value pairs or values to find in the query string. The maximum size of each string is 128 characters. The comparison is case insensitive. The following wildcard characters are supported: * (matches 0 or more characters) and ? (matches exactly 1 character). To search for a literal '*' or '?' character in a query string, you must escape these characters in Values using a '' character.

If you specify multiple key/value pairs or values, the condition is satisfied if one of them is found in the query string.

(structure)

Information about a key/value pair.

Key -> (string)

The key. You can omit the key.

Value -> (string)

The value.

HttpRequestMethodConfig -> (structure)

Information for an HTTP method condition. Specify only when Field is http-request-method .

Values -> (list)

The name of the request method. The maximum size is 40 characters. The allowed characters are A-Z, hyphen (-), and underscore (_). The comparison is case sensitive. Wildcards are not supported; therefore, the method name must be an exact match.

If you specify multiple strings, the condition is satisfied if one of the strings matches the HTTP request method. We recommend that you route GET and HEAD requests in the same way, because the response to a HEAD request may be cached.

(string)

SourceIpConfig -> (structure)

Information for a source IP condition. Specify only when Field is source-ip .

Values -> (list)

One or more source IP addresses, in CIDR format. You can use both IPv4 and IPv6 addresses. Wildcards are not supported.

If you specify multiple addresses, the condition is satisfied if the source IP address of the request matches one of the CIDR blocks. This condition is not satisfied by the addresses in the X-Forwarded-For header. To search for addresses in the X-Forwarded-For header, use HttpHeaderConditionConfig .

(string)

Actions -> (list)

The actions. Each rule must include exactly one of the following types of actions: forward , redirect , or fixed-response , and it must be the last action to be performed.

(structure)

Information about an action.

Type -> (string)

The type of action.

TargetGroupArn -> (string)

The Amazon Resource Name (ARN) of the target group. Specify only when Type is forward and you want to route to a single target group. To route to one or more target groups, use ForwardConfig instead.

AuthenticateOidcConfig -> (structure)

[HTTPS listeners] Information about an identity provider that is compliant with OpenID Connect (OIDC). Specify only when Type is authenticate-oidc .

Issuer -> (string)

The OIDC issuer identifier of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

AuthorizationEndpoint -> (string)

The authorization endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

TokenEndpoint -> (string)

The token endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

UserInfoEndpoint -> (string)

The user info endpoint of the IdP. This must be a full URL, including the HTTPS protocol, the domain, and the path.

ClientId -> (string)

The OAuth 2.0 client identifier.

ClientSecret -> (string)

The OAuth 2.0 client secret. This parameter is required if you are creating a rule. If you are modifying a rule, you can omit this parameter if you set UseExistingClientSecret to true.

SessionCookieName -> (string)

The name of the cookie used to maintain session information. The default is AWSELBAuthSessionCookie.

Scope -> (string)

The set of user claims to be requested from the IdP. The default is openid .

To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP.

SessionTimeout -> (long)

The maximum duration of the authentication session, in seconds. The default is 604800 seconds (7 days).

AuthenticationRequestExtraParams -> (map)

The query parameters (up to 10) to include in the redirect request to the authorization endpoint.

key -> (string)

value -> (string)

OnUnauthenticatedRequest -> (string)

The behavior if the user is not authenticated. The following are possible values:

  • deny- Return an HTTP 401 Unauthorized error.
  • allow- Allow the request to be forwarded to the target.
  • authenticate- Redirect the request to the IdP authorization endpoint. This is the default value.

UseExistingClientSecret -> (boolean)

Indicates whether to use the existing client secret when modifying a rule. If you are creating a rule, you can omit this parameter or set it to false.

AuthenticateCognitoConfig -> (structure)

[HTTPS listeners] Information for using Amazon Cognito to authenticate users. Specify only when Type is authenticate-cognito .

UserPoolArn -> (string)

The Amazon Resource Name (ARN) of the Amazon Cognito user pool.

UserPoolClientId -> (string)

The ID of the Amazon Cognito user pool client.

UserPoolDomain -> (string)

The domain prefix or fully-qualified domain name of the Amazon Cognito user pool.

SessionCookieName -> (string)

The name of the cookie used to maintain session information. The default is AWSELBAuthSessionCookie.

Scope -> (string)

The set of user claims to be requested from the IdP. The default is openid .

To verify which scope values your IdP supports and how to separate multiple values, see the documentation for your IdP.

SessionTimeout -> (long)

The maximum duration of the authentication session, in seconds. The default is 604800 seconds (7 days).

AuthenticationRequestExtraParams -> (map)

The query parameters (up to 10) to include in the redirect request to the authorization endpoint.

key -> (string)

value -> (string)

OnUnauthenticatedRequest -> (string)

The behavior if the user is not authenticated. The following are possible values:

  • deny- Return an HTTP 401 Unauthorized error.
  • allow- Allow the request to be forwarded to the target.
  • authenticate- Redirect the request to the IdP authorization endpoint. This is the default value.

Order -> (integer)

The order for the action. This value is required for rules with multiple actions. The action with the lowest value for order is performed first. The last action to be performed must be one of the following types of actions: a forward , fixed-response , or redirect .

RedirectConfig -> (structure)

[Application Load Balancer] Information for creating a redirect action. Specify only when Type is redirect .

Protocol -> (string)

The protocol. You can specify HTTP, HTTPS, or #{protocol}. You can redirect HTTP to HTTP, HTTP to HTTPS, and HTTPS to HTTPS. You cannot redirect HTTPS to HTTP.

Port -> (string)

The port. You can specify a value from 1 to 65535 or #{port}.

Host -> (string)

The hostname. This component is not percent-encoded. The hostname can contain #{host}.

Path -> (string)

The absolute path, starting with the leading "/". This component is not percent-encoded. The path can contain #{host}, #{path}, and #{port}.

Query -> (string)

The query parameters, URL-encoded when necessary, but not percent-encoded. Do not include the leading "?", as it is automatically added. You can specify any of the reserved keywords.

StatusCode -> (string)

The HTTP redirect code. The redirect is either permanent (HTTP 301) or temporary (HTTP 302).

FixedResponseConfig -> (structure)

[Application Load Balancer] Information for creating an action that returns a custom HTTP response. Specify only when Type is fixed-response .

MessageBody -> (string)

The message.

StatusCode -> (string)

The HTTP response code (2XX, 4XX, or 5XX).

ContentType -> (string)

The content type.

Valid Values: text/plain | text/css | text/html | application/javascript | application/json

ForwardConfig -> (structure)

Information for creating an action that distributes requests among one or more target groups. For Network Load Balancers, you can specify a single target group. Specify only when Type is forward . If you specify both ForwardConfig and TargetGroupArn , you can specify only one target group using ForwardConfig and it must be the same target group specified in TargetGroupArn .

TargetGroups -> (list)

One or more target groups. For Network Load Balancers, you can specify a single target group.

(structure)

Information about how traffic will be distributed between multiple target groups in a forward rule.

TargetGroupArn -> (string)

The Amazon Resource Name (ARN) of the target group.

Weight -> (integer)

The weight. The range is 0 to 999.

TargetGroupStickinessConfig -> (structure)

The target group stickiness for the rule.

Enabled -> (boolean)

Indicates whether target group stickiness is enabled.

DurationSeconds -> (integer)

The time period, in seconds, during which requests from a client should be routed to the same target group. The range is 1-604800 seconds (7 days).

IsDefault -> (boolean)

Indicates whether this is the default rule.