oracle.oci.oci_loadbalancer_listener_rule_facts – Fetches details about one or multiple ListenerRule resources in Oracle Cloud Infrastructure

Note

This plugin is part of the oracle.oci collection (version 4.14.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install oracle.oci.

To use it in a playbook, specify: oracle.oci.oci_loadbalancer_listener_rule_facts.

New in version 2.9.0: of oracle.oci

Synopsis

  • Fetches details about one or multiple ListenerRule resources in Oracle Cloud Infrastructure

  • Lists all of the rules from all of the rule sets associated with the specified listener. The response organizes the rules in the following order:

    • Access control rules * Allow method rules * Request header rules * Response header rules

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter Choices/Defaults Comments
api_user
string
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_ID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See config_file_location). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_fingerprint
string
Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See config_file_location). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm.
api_user_key_file
string
Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See config_file_location). If the key is encrypted with a pass-phrase, the api_user_key_pass_phrase option must also be provided.
api_user_key_pass_phrase
string
Passphrase used by the key referenced in api_user_key_file, if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See config_file_location).
auth_purpose
string
    Choices:
  • service_principal
The auth purpose which can be used in conjunction with 'auth_type=instance_principal'. The default auth_purpose for instance_principal is None.
auth_type
string
    Choices:
  • api_key ←
  • instance_principal
  • instance_obo_user
  • resource_principal
The type of authentication to use for making API requests. By default auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance.
cert_bundle
string
The full path to a CA certificate bundle to be used for SSL verification. This will override the default CA certificate bundle. If not set, then the value of the OCI_ANSIBLE_CERT_BUNDLE variable, if any, is used.
config_file_location
string
Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
config_profile_name
string
The profile to load from the config file referenced by config_file_location. If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in config_file_location.
listener_name
string / required
The name of the listener the rules are associated with.
load_balancer_id
string / required
The OCID of the load balancer associated with the listener.
region
string
The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is not specified through a configuration file (See config_file_location). Please refer to https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm for more information on OCI regions.
tenancy
string
OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See config_file_location). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm

Examples

- name: List listener_rules
  oci_loadbalancer_listener_rule_facts:
    # required
    load_balancer_id: "ocid1.loadbalancer.oc1..xxxxxxEXAMPLExxxxxx"
    listener_name: listener_name_example

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
listener_rules
complex
on success
List of ListenerRule resources

Sample:
[{'rule': {'action': 'ADD_HTTP_REQUEST_HEADER', 'allowed_methods': [], 'are_invalid_characters_allowed': True, 'conditions': [{'attribute_name': 'SOURCE_IP_ADDRESS', 'attribute_value': 'attribute_value_example', 'operator': 'EXACT_MATCH'}], 'description': 'description_example', 'header': 'header_example', 'http_large_header_size_in_kb': 56, 'prefix': 'prefix_example', 'redirect_uri': {'host': 'host_example', 'path': 'path_example', 'port': 56, 'protocol': 'protocol_example', 'query': 'query_example'}, 'response_code': 56, 'status_code': 56, 'suffix': 'suffix_example', 'value': 'value_example'}, 'rule_set_name': 'rule_set_name_example'}]
 
rule
complex
on success
A rule object that applies to the listener.

   
action
string
on success

Sample:
ADD_HTTP_REQUEST_HEADER
   
allowed_methods
list / elements=string
on success
The list of HTTP methods allowed for this listener.
By default, you can specify only the standard HTTP methods defined in the HTTP Method Registry. You can also see a list of supported standard HTTP methods in the Load Balancing service documentation at Managing Rule Sets.
Your backend application must be able to handle the methods specified in this list.
The list of HTTP methods is extensible. If you need to configure custom HTTP methods, contact My Oracle Support to remove the restriction for your tenancy.
Example: ["GET", "PUT", "POST", "PROPFIND"]

   
are_invalid_characters_allowed
boolean
on success
Indicates whether or not invalid characters in client header fields will be allowed. Valid names are composed of English letters, digits, hyphens and underscores. If "true", invalid characters are allowed in the HTTP header. If "false", invalid characters are not allowed in the HTTP header

Sample:
True
   
conditions
complex
on success

     
attribute_name
string
on success

Sample:
SOURCE_IP_ADDRESS
     
attribute_value
string
on success
The path string that the redirection rule applies to.
Example: `/example`

Sample:
attribute_value_example
     
operator
string
on success
A string that specifies how to compare the PathMatchCondition object's `attributeValue` string to the incoming URI.
* **EXACT_MATCH** - The incoming URI path must exactly and completely match the `attributeValue` string.
* **FORCE_LONGEST_PREFIX_MATCH** - The system looks for the `attributeValue` string with the best, longest match of the beginning portion of the incoming URI path.
* **PREFIX_MATCH** - The beginning portion of the incoming URI path must exactly match the `attributeValue` string.
* **SUFFIX_MATCH** - The ending portion of the incoming URI path must exactly match the `attributeValue` string.

Sample:
EXACT_MATCH
   
description
string
on success
A brief description of the access control rule. Avoid entering confidential information.
example: `192.168.0.0/16 and 2001:db8::/32 are trusted clients. Whitelist them.`

Sample:
description_example
   
header
string
on success
A header name that conforms to RFC 7230.
Example: `example_header_name`

Sample:
header_example
   
http_large_header_size_in_kb
integer
on success
The maximum size of each buffer used for reading http client request header. This value indicates the maximum size allowed for each buffer. The allowed values for buffer size are 8, 16, 32 and 64.

Sample:
56
   
prefix
string
on success
A string to prepend to the header value. The resulting header value must conform to RFC 7230. With the following exceptions: * value cannot contain `$` * value cannot contain patterns like `{variable_name}`. They are reserved for future extensions. Currently, such values are invalid.
Example: `example_prefix_value`

Sample:
prefix_example
   
redirect_uri
complex
on success

     
host
string
on success
The valid domain name (hostname) or IP address to use in the redirect URI.
When this value is null, not set, or set to `{host}`, the service preserves the original domain name from the incoming HTTP request URI.
All RedirectUri tokens are valid for this property. You can use any token more than once.
Curly braces are valid in this property only to surround tokens, such as `{host}`
Examples:
* **example.com** appears as `example.com` in the redirect URI.
* **in{host}** appears as `inexample.com` in the redirect URI if `example.com` is the hostname in the incoming HTTP request URI.
* **{port}{host}** appears as `8081example.com` in the redirect URI if `example.com` is the hostname and the port is `8081` in the incoming HTTP request URI.

Sample:
host_example
     
path
string
on success
The HTTP URI path to use in the redirect URI.
When this value is null, not set, or set to `{path}`, the service preserves the original path from the incoming HTTP request URI. To omit the path from the redirect URI, set this value to an empty string, "".
All RedirectUri tokens are valid for this property. You can use any token more than once.
The path string must begin with `/` if it does not begin with the `{path}` token.
Examples:
* __/example/video/123__ appears as `/example/video/123` in the redirect URI.
* __/example{path}__ appears as `/example/video/123` in the redirect URI if `/video/123` is the path in the incoming HTTP request URI.
* __{path}/123__ appears as `/example/video/123` in the redirect URI if `/example/video` is the path in the incoming HTTP request URI.
* __{path}123__ appears as `/example/video123` in the redirect URI if `/example/video` is the path in the incoming HTTP request URI.
* __/{host}/123__ appears as `/example.com/123` in the redirect URI if `example.com` is the hostname in the incoming HTTP request URI.
* __/{host}/{port}__ appears as `/example.com/123` in the redirect URI if `example.com` is the hostname and `123` is the port in the incoming HTTP request URI.
* __/{query}__ appears as `/lang=en` in the redirect URI if the query is `lang=en` in the incoming HTTP request URI.

Sample:
path_example
     
port
integer
on success
The communication port to use in the redirect URI.
Valid values include integers from 1 to 65535.
When this value is null, the service preserves the original port from the incoming HTTP request URI.
Example: `8081`

Sample:
56
     
protocol
string
on success
The HTTP protocol to use in the redirect URI.
When this value is null, not set, or set to `{protocol}`, the service preserves the original protocol from the incoming HTTP request URI. Allowed values are:
* HTTP * HTTPS * {protocol}
`{protocol}` is the only valid token for this property. It can appear only once in the value string.
Example: `HTTPS`

Sample:
protocol_example
     
query
string
on success
The query string to use in the redirect URI.
When this value is null, not set, or set to `{query}`, the service preserves the original query parameters from the incoming HTTP request URI.
All `RedirectUri` tokens are valid for this property. You can use any token more than once.
If the query string does not begin with the `{query}` token, it must begin with the question mark (?) character.
You can specify multiple query parameters as a single string. Separate each query parameter with an ampersand (&) character. To omit all incoming query parameters from the redirect URI, set this value to an empty string, "".
If the specified query string results in a redirect URI ending with `?` or `&`, the last character is truncated. For example, if the incoming URI is `http://host.com:8080/documents` and the query property value is `?lang=en&{query}`, the redirect URI is `http://host.com:8080/documents?lang=en`. The system truncates the final ampersand (&) because the incoming URI included no value to replace the {query} token.
Examples: * **lang=en&time_zone=PST** appears as `lang=en&time_zone=PST` in the redirect URI.
* **{query}** appears as `lang=en&time_zone=PST` in the redirect URI if `lang=en&time_zone=PST` is the query string in the incoming HTTP request. If the incoming HTTP request has no query parameters, the `{query}` token renders as an empty string.
* **lang=en&{query}&time_zone=PST** appears as `lang=en&country=us&time_zone=PST` in the redirect URI if `country=us` is the query string in the incoming HTTP request. If the incoming HTTP request has no query parameters, this value renders as `lang=en&time_zone=PST`.
* **protocol={protocol}&hostname={host}** appears as `protocol=http&hostname=example.com` in the redirect URI if the protocol is `HTTP` and the hostname is `example.com` in the incoming HTTP request.
* **port={port}&hostname={host}** appears as `port=8080&hostname=example.com` in the redirect URI if the port is `8080` and the hostname is `example.com` in the incoming HTTP request URI.

Sample:
query_example
   
response_code
integer
on success
The HTTP status code to return when the incoming request is redirected.
The status line returned with the code is mapped from the standard HTTP specification. Valid response codes for redirection are:
* 301 * 302 * 303 * 307 * 308
The default value is `302` (Found).
Example: `301`

Sample:
56
   
status_code
integer
on success
The HTTP status code to return when the requested HTTP method is not in the list of allowed methods. The associated status line returned with the code is mapped from the standard HTTP specification. The default value is `405 (Method Not Allowed)`.
Example: 403

Sample:
56
   
suffix
string
on success
A string to append to the header value. The resulting header value must conform to RFC 7230. With the following exceptions: * value cannot contain `$` * value cannot contain patterns like `{variable_name}`. They are reserved for future extensions. Currently, such values are invalid.
Example: `example_suffix_value`

Sample:
suffix_example
   
value
string
on success
A header value that conforms to RFC 7230. With the following exceptions: * value cannot contain `$` * value cannot contain patterns like `{variable_name}`. They are reserved for future extensions. Currently, such values are invalid.
Example: `example_value`

Sample:
value_example
 
rule_set_name
string
on success
The name of the rule set that the rule belongs to.

Sample:
rule_set_name_example


Authors

  • Oracle (@oracle)