oracle.oci.oci_waas_policy_config_facts – Fetches details about a PolicyConfig resource 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_waas_policy_config_facts.

New in version 2.9.0: of oracle.oci

Synopsis

  • Fetches details about a PolicyConfig resource in Oracle Cloud Infrastructure

  • Gets the configuration of a WAAS policy.

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.
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
waas_policy_id
string / required
The OCID of the WAAS policy.

aliases: id

Examples

- name: Get a specific policy_config
  oci_waas_policy_config_facts:
    # required
    waas_policy_id: "ocid1.waaspolicy.oc1..xxxxxxEXAMPLExxxxxx"

Return Values

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

Key Returned Description
policy_config
complex
on success
PolicyConfig resource

Sample:
{'certificate_id': 'ocid1.certificate.oc1..xxxxxxEXAMPLExxxxxx', 'cipher_group': 'DEFAULT', 'client_address_header': 'X_FORWARDED_FOR', 'health_checks': {'expected_response_code_group': [], 'expected_response_text': 'expected_response_text_example', 'headers': {}, 'healthy_threshold': 56, 'interval_in_seconds': 56, 'is_enabled': True, 'is_response_text_check_enabled': True, 'method': 'GET', 'path': 'path_example', 'timeout_in_seconds': 56, 'unhealthy_threshold': 56}, 'is_behind_cdn': True, 'is_cache_control_respected': True, 'is_https_enabled': True, 'is_https_forced': True, 'is_origin_compression_enabled': True, 'is_response_buffering_enabled': True, 'is_sni_enabled': True, 'load_balancing_method': {'domain': 'domain_example', 'expiration_time_in_seconds': 56, 'method': 'IP_HASH', 'name': 'name_example'}, 'tls_protocols': [], 'websocket_path_prefixes': []}
 
certificate_id
string
on success
The OCID of the SSL certificate to use if HTTPS is supported.

Sample:
ocid1.certificate.oc1..xxxxxxEXAMPLExxxxxx
 
cipher_group
string
on success
The set cipher group for the configured TLS protocol. This sets the configuration for the TLS connections between clients and edge nodes only. - **DEFAULT:** Cipher group supports TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3 protocols. It has the following ciphers enabled: `ECDHE-RSA- AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS- AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA- AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS- AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM- SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:!DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH- DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA`

Sample:
DEFAULT
 
client_address_header
string
on success
Specifies an HTTP header name which is treated as the connecting client's IP address. Applicable only if `isBehindCdn` is enabled.
The edge node reads this header and its value and sets the client IP address as specified. It does not create the header if the header is not present in the request. If the header is not present, the connecting IP address will be used as the client's true IP address. It uses the last IP address in the header's value as the true IP address.
Example: `X-Client-Ip: 11.1.1.1, 13.3.3.3`
In the case of multiple headers with the same name, only the first header will be used. It is assumed that CDN sets the correct client IP address to prevent spoofing.
- **X_FORWARDED_FOR:** Corresponds to `X-Forwarded-For` header name.
- **X_CLIENT_IP:** Corresponds to `X-Client-Ip` header name.
- **X_REAL_IP:** Corresponds to `X-Real-Ip` header name.
- **CLIENT_IP:** Corresponds to `Client-Ip` header name.
- **TRUE_CLIENT_IP:** Corresponds to `True-Client-Ip` header name.

Sample:
X_FORWARDED_FOR
 
health_checks
complex
on success

   
expected_response_code_group
list / elements=string
on success
The HTTP response codes that signify a healthy state. - **2XX:** Success response code group. - **3XX:** Redirection response code group. - **4XX:** Client errors response code group. - **5XX:** Server errors response code group.

   
expected_response_text
string
on success
Health check will search for the given text in a case-sensitive manner within the response body and will fail if the text is not found.

Sample:
expected_response_text_example
   
headers
dictionary
on success
HTTP header fields to include in health check requests, expressed as `"name": "value"` properties. Because HTTP header field names are case-insensitive, any use of names that are case-insensitive equal to other names will be rejected. If Host is not specified, requests will include a Host header field with value matching the policy's protected domain. If User-Agent is not specified, requests will include a User-Agent header field with value "waf health checks".
**Note:** The only currently-supported header fields are Host and User-Agent.

   
healthy_threshold
integer
on success
Number of successful health checks after which the server is marked up.

Sample:
56
   
interval_in_seconds
integer
on success
Time between health checks of an individual origin server, in seconds.

Sample:
56
   
is_enabled
boolean
on success
Enables or disables the health checks.

Sample:
True
   
is_response_text_check_enabled
boolean
on success
Enables or disables additional check for predefined text in addition to response code.

Sample:
True
   
method
string
on success
An HTTP verb (i.e. HEAD, GET, or POST) to use when performing the health check.

Sample:
GET
   
path
string
on success
Path to visit on your origins when performing the health check.

Sample:
path_example
   
timeout_in_seconds
integer
on success
Response timeout represents wait time until request is considered failed, in seconds.

Sample:
56
   
unhealthy_threshold
integer
on success
Number of failed health checks after which the server is marked down.

Sample:
56
 
is_behind_cdn
boolean
on success
Enabling `isBehindCdn` allows for the collection of IP addresses from client requests if the WAF is connected to a CDN.

Sample:
True
 
is_cache_control_respected
boolean
on success
Enable or disable automatic content caching based on the response `cache-control` header. This feature enables the origin to act as a proxy cache. Caching is usually defined using `cache-control` header. For example `cache-control: max-age=120` means that the returned resource is valid for 120 seconds. Caching rules will overwrite this setting.

Sample:
True
 
is_https_enabled
boolean
on success
Enable or disable HTTPS support. If true, a `certificateId` is required. If unspecified, defaults to `false`.

Sample:
True
 
is_https_forced
boolean
on success
Force HTTP to HTTPS redirection. If unspecified, defaults to `false`.

Sample:
True
 
is_origin_compression_enabled
boolean
on success
Enable or disable GZIP compression of origin responses. If enabled, the header `Accept-Encoding: gzip` is sent to origin, otherwise, the empty `Accept-Encoding:` header is used.

Sample:
True
 
is_response_buffering_enabled
boolean
on success
Enable or disable buffering of responses from the origin. Buffering improves overall stability in case of network issues, but slightly increases Time To First Byte.

Sample:
True
 
is_sni_enabled
boolean
on success
SNI stands for Server Name Indication and is an extension of the TLS protocol. It indicates which hostname is being contacted by the browser at the beginning of the 'handshake'-process. This allows a server to connect multiple SSL Certificates to one IP address and port.

Sample:
True
 
load_balancing_method
complex
on success
An object that represents a load balancing method and its properties.

   
domain
string
on success
The domain for which the cookie is set, defaults to WAAS policy domain.

Sample:
domain_example
   
expiration_time_in_seconds
integer
on success
The time for which a browser should keep the cookie in seconds. Empty value will cause the cookie to expire at the end of a browser session.

Sample:
56
   
method
string
on success
Load balancing methods are algorithms used to efficiently distribute traffic among origin servers.
- **IP_HASH:** All the incoming requests from the same client IP address should go to the same content origination server. IP_HASH load balancing method uses origin weights when choosing which origin should the hash be assigned to initially.
- **ROUND_ROBIN:** Forwards requests sequentially to the available origin servers. The first request - to the first origin server, the second request - to the next origin server, and so on. After it sends a request to the last origin server, it starts again with the first origin server. When using weights on origins, Weighted Round Robin assigns more requests to origins with a greater weight. Over a period of time, origins will receive a number of requests in proportion to their weight.
- **STICKY_COOKIE:** Adds a session cookie to the first response from the origin server and identifies the server that sent the response. The client's next request contains the cookie value, and nginx routes the request to the origin server that responded to the first request. STICKY_COOKIE load balancing method falls back to Round Robin for the first request.

Sample:
IP_HASH
   
name
string
on success
The name of the cookie used to track the persistence. Can contain any US-ASCII character except separator or control character.

Sample:
name_example
 
tls_protocols
list / elements=string
on success
A list of allowed TLS protocols. Only applicable when HTTPS support is enabled. The TLS protocol is negotiated while the request is connecting and the most recent protocol supported by both the edge node and client browser will be selected. If no such version exists, the connection will be aborted. - **TLS_V1:** corresponds to TLS 1.0 specification.
- **TLS_V1_1:** corresponds to TLS 1.1 specification.
- **TLS_V1_2:** corresponds to TLS 1.2 specification.
- **TLS_V1_3:** corresponds to TLS 1.3 specification.
Enabled TLS protocols must go in a row. For example if `TLS_v1_1` and `TLS_V1_3` are enabled, `TLS_V1_2` must be enabled too.

 
websocket_path_prefixes
list / elements=string
on success
ModSecurity is not capable to inspect WebSockets. Therefore paths specified here have WAF disabled if Connection request header from the client has the value Upgrade (case insensitive matching) and Upgrade request header has the value websocket (case insensitive matching). Paths matches if the concatenation of request URL path and query starts with the contents of the one of `websocketPathPrefixes` array value. In All other cases challenges, like JSC, HIC and etc., remain active.



Authors

  • Oracle (@oracle)