ElasticLoadBalancingv2 / Client / describe_rules

describe_rules

ElasticLoadBalancingv2.Client.describe_rules(**kwargs)

Describes the specified rules or the rules for the specified listener. You must specify either a listener or one or more rules.

See also: AWS API Documentation

Request Syntax

response = client.describe_rules(
    ListenerArn='string',
    RuleArns=[
        'string',
    ],
    Marker='string',
    PageSize=123
)

Parameters:

• ListenerArn (string) – The Amazon Resource Name (ARN) of the listener.

• RuleArns (list) –

  The Amazon Resource Names (ARN) of the rules.

  • (string) –

• Marker (string) – The marker for the next set of results. (You received this marker from a previous call.)

• PageSize (integer) – The maximum number of results to return with this call.

Return type:

dict

Returns:

Response Syntax

{
    'Rules': [
        {
            'RuleArn': 'string',
            'Priority': 'string',
            'Conditions': [
                {
                    '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',
                        ]
                    }
                },
            ],
            'Actions': [
                {
                    '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': 123,
                        'AuthenticationRequestExtraParams': {
                            'string': 'string'
                        },
                        'OnUnauthenticatedRequest': 'deny'|'allow'|'authenticate',
                        'UseExistingClientSecret': True|False
                    },
                    'AuthenticateCognitoConfig': {
                        'UserPoolArn': 'string',
                        'UserPoolClientId': 'string',
                        'UserPoolDomain': 'string',
                        'SessionCookieName': 'string',
                        'Scope': 'string',
                        'SessionTimeout': 123,
                        'AuthenticationRequestExtraParams': {
                            'string': 'string'
                        },
                        'OnUnauthenticatedRequest': 'deny'|'allow'|'authenticate'
                    },
                    'Order': 123,
                    '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': 123
                            },
                        ],
                        'TargetGroupStickinessConfig': {
                            'Enabled': True|False,
                            'DurationSeconds': 123
                        }
                    }
                },
            ],
            'IsDefault': True|False
        },
    ],
    'NextMarker': 'string'
}

Response Structure

• (dict) –

  • Rules (list) –

    Information about the rules.

    • (dict) –

      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.

        • (dict) –

          Information about a condition for a rule.

          Each rule can optionally include up to one of each of the following conditions: http-request-method, host-header, path-pattern, and source-ip. Each rule can also optionally include one or more of each of the following conditions: http-header and query-string. Note that the value for a condition can’t be empty.

          For more information, see Quotas for your Application Load Balancers.

          • 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. Specify only when Field is host-header or path-pattern. Alternatively, to specify multiple host names or multiple path patterns, use HostHeaderConfig or PathPatternConfig.

            If Field is host-header and you are not using HostHeaderConfig, you can specify a single host name (for example, my.example.com) in Values. 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 and you are not using PathPatternConfig, you can specify a single path pattern (for example, /img/*) in Values. 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 &)

            • • (matches 0 or more characters)

            • ? (matches exactly 1 character)

            • (string) –

          • HostHeaderConfig (dict) –

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

            • Values (list) –

              The 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 (dict) –

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

            • Values (list) –

              The 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 (dict) –

            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) –

              The 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 (dict) –

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

            • Values (list) –

              The 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.

              • (dict) –

                Information about a key/value pair.

                • Key (string) –

                  The key. You can omit the key.

                • Value (string) –

                  The value.

          • HttpRequestMethodConfig (dict) –

            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 (dict) –

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

            • Values (list) –

              The 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.

              The total number of values must be less than, or equal to five.

              • (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.

        • (dict) –

          Information about an action.

          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.

          • 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 (dict) –

            [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 (integer) –

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

            • AuthenticationRequestExtraParams (dict) –

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

              • (string) –

                • (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 (dict) –

            [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 (integer) –

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

            • AuthenticationRequestExtraParams (dict) –

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

              • (string) –

                • (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.

          • RedirectConfig (dict) –

            [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 can’t 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 (dict) –

            [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 (dict) –

            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) –

              The target groups. For Network Load Balancers, you can specify a single target group.

              • (dict) –

                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 (dict) –

              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.

  • NextMarker (string) –

    If there are additional results, this is the marker for the next set of results. Otherwise, this is null.

Exceptions

• ElasticLoadBalancingv2.Client.exceptions.ListenerNotFoundException

• ElasticLoadBalancingv2.Client.exceptions.RuleNotFoundException

• ElasticLoadBalancingv2.Client.exceptions.UnsupportedProtocolException

Examples

This example describes the specified rule.

response = client.describe_rules(
    RuleArns=[
        'arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2/9683b2d02a6cabee',
    ],
)

print(response)

Expected Output:

{
    'Rules': [
        {
            'Actions': [
                {
                    'TargetGroupArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/my-targets/73e2d6bc24d8a067',
                    'Type': 'forward',
                },
            ],
            'Conditions': [
                {
                    'Field': 'path-pattern',
                    'Values': [
                        '/img/*',
                    ],
                },
            ],
            'IsDefault': False,
            'Priority': '10',
            'RuleArn': 'arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/my-load-balancer/50dc6c495c0c9188/f2f7dc8efc522ab2/9683b2d02a6cabee',
        },
    ],
    'ResponseMetadata': {
        '...': '...',
    },
}