Try SpotterManage a Listener resource in Oracle Cloud Infrastructure
| "added in version" 2.9.0 of oracle.oci"
Authors: Oracle (@oracle)
preview | supported by community
Install with ansible-galaxy collection install oracle.oci:==5.0.0
collections:
- name: oracle.oci
version: 5.0.0This module allows the user to create, update and delete a Listener resource in Oracle Cloud Infrastructure
For I(state=present), adds a listener to a load balancer.
- name: Create listener
oci_loadbalancer_listener:
# required
default_backend_set_name: default_backend_set_name_example
port: 56
protocol: protocol_example
load_balancer_id: "ocid1.loadbalancer.oc1..xxxxxxEXAMPLExxxxxx"
name: name_example
# optional
hostname_names: [ "hostname_names_example" ]
path_route_set_name: path_route_set_name_example
routing_policy_name: routing_policy_name_example
ssl_configuration:
# optional
verify_depth: 56
verify_peer_certificate: true
trusted_certificate_authority_ids: [ "trusted_certificate_authority_ids_example" ]
certificate_ids: [ "certificate_ids_example" ]
certificate_name: certificate_name_example
protocols: [ "protocols_example" ]
cipher_suite_name: cipher_suite_name_example
server_order_preference: ENABLED
connection_configuration:
# required
idle_timeout: 56
# optional
backend_tcp_proxy_protocol_version: 56
rule_set_names: [ "rule_set_names_example" ]
- name: Update listener
oci_loadbalancer_listener:
# required
default_backend_set_name: default_backend_set_name_example
port: 56
protocol: protocol_example
load_balancer_id: "ocid1.loadbalancer.oc1..xxxxxxEXAMPLExxxxxx"
name: name_example
# optional
hostname_names: [ "hostname_names_example" ]
path_route_set_name: path_route_set_name_example
routing_policy_name: routing_policy_name_example
ssl_configuration:
# optional
verify_depth: 56
verify_peer_certificate: true
trusted_certificate_authority_ids: [ "trusted_certificate_authority_ids_example" ]
certificate_ids: [ "certificate_ids_example" ]
certificate_name: certificate_name_example
protocols: [ "protocols_example" ]
cipher_suite_name: cipher_suite_name_example
server_order_preference: ENABLED
connection_configuration:
# required
idle_timeout: 56
# optional
backend_tcp_proxy_protocol_version: 56
rule_set_names: [ "rule_set_names_example" ]
- name: Delete listener
oci_loadbalancer_listener:
# required
load_balancer_id: "ocid1.loadbalancer.oc1..xxxxxxEXAMPLExxxxxx"
name: name_example
state: absent
name:
description:
- A friendly name for the listener. It must be unique and it cannot be changed. Avoid
entering confidential information.
- 'Example: `example_listener`'
required: true
type: str
port:
description:
- The communication port for the listener.
- 'Example: `80`'
- Required for create using I(state=present), update using I(state=present) with name
present.
type: int
wait:
default: true
description: Whether to wait for create or delete operation to complete.
type: bool
state:
choices:
- present
- absent
default: present
description:
- The state of the Listener.
- Use I(state=present) to create or update a Listener.
- Use I(state=absent) to delete a Listener.
required: false
type: str
key_by:
description: The list of attributes of this resource which should be used to uniquely
identify an instance of the resource. By default, all the attributes of a resource
are used to uniquely identify a resource.
elements: str
type: list
region:
description:
- 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 C(config_file_location)).
Please refer to U(https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm)
for more information on OCI regions.
type: str
tenancy:
description:
- 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 C(config_file_location)). To get the tenancy OCID, please
refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm)
type: str
api_user:
description:
- 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 C(config_file_location)).
To get the user's OCID, please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
type: str
protocol:
description:
- The protocol on which the listener accepts connection requests. To get a list of
valid protocols, use the L(ListProtocols,https://docs.cloud.oracle.com/en- us/iaas/api/#/en/loadbalancer/20170115/LoadBalancerProtocol/ListProtocols)
operation.
- 'Example: `HTTP`'
- Required for create using I(state=present), update using I(state=present) with name
present.
type: str
auth_type:
choices:
- api_key
- instance_principal
- instance_obo_user
- resource_principal
- security_token
default: api_key
description:
- The type of authentication to use for making API requests. By default C(auth_type="api_key")
based authentication is performed and the API key (see I(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 C(auth_type="instance_principal")
to use instance principal based authentication when running ansible playbooks within
an OCI compute instance.
type: str
cert_bundle:
description:
- 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.
type: str
auth_purpose:
choices:
- service_principal
description:
- The auth purpose which can be used in conjunction with 'auth_type=instance_principal'.
The default auth_purpose for instance_principal is None.
type: str
force_create:
default: false
description: Whether to attempt non-idempotent creation of a resource. By default,
create resource is an idempotent operation, and doesn't create the resource if it
already exists. Setting this option to true, forcefully creates a copy of the resource,
even if it already exists.This option is mutually exclusive with I(key_by).
type: bool
wait_timeout:
description: Time, in seconds, to wait when I(wait=yes). Defaults to 1200 for most
of the services but some services might have a longer wait timeout.
type: int
hostname_names:
description:
- An array of hostname resource names.
- This parameter is updatable.
elements: str
type: list
rule_set_names:
description:
- The names of the L(rule sets,https://docs.cloud.oracle.com/en-us/iaas/api/#/en/loadbalancer/20170115/RuleSet/)
to apply to the listener.
- 'Example: ["example_rule_set"]'
- This parameter is updatable.
elements: str
type: list
load_balancer_id:
description:
- The L(OCID,https://docs.cloud.oracle.com/Content/General/Concepts/identifiers.htm)
of the load balancer on which to add a listener.
required: true
type: str
api_user_key_file:
description:
- 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 C(config_file_location)).
If the key is encrypted with a pass-phrase, the C(api_user_key_pass_phrase) option
must also be provided.
type: str
ssl_configuration:
description:
- ''
- This parameter is updatable.
suboptions:
certificate_ids:
description:
- Ids for OCI certificates service certificates. Currently only a single Id may
be passed.
- 'Example: `[ocid1.certificate.oc1.us-ashburn-1.amaaaaaaav3bgsaa5o2q7rh5nfmkkukfkogasqhk6af2opufhjlqg7m6jqzq]`'
elements: str
type: list
certificate_name:
description:
- A friendly name for the certificate bundle. It must be unique and it cannot
be changed. Valid certificate bundle names include only alphanumeric characters,
dashes, and underscores. Certificate bundle names cannot contain spaces. Avoid
entering confidential information.
- 'Example: `example_certificate_bundle`'
type: str
cipher_suite_name:
description:
- The name of the cipher suite to use for HTTPS or SSL connections.
- If this field is not specified, the default is `oci-default-ssl-cipher-suite-v1`.
- '**Notes:**'
- '* You must ensure compatibility between the specified SSL protocols and the
ciphers configured in the cipher suite. Clients cannot perform an SSL handshake
if there is an incompatible configuration. * You must ensure compatibility
between the ciphers configured in the cipher suite and the configured certificates.
For example, RSA-based ciphers require RSA certificates and ECDSA-based ciphers
require ECDSA certificates. * If the cipher configuration is not modified after
load balancer creation, the `GET` operation returns `oci-default-ssl-cipher-suite-v1`
as the value of this field in the SSL configuration for existing listeners that
predate this feature. * If the cipher configuration was modified using Oracle
operations after load balancer creation, the `GET` operation returns `oci-customized-ssl-cipher-suite`
as the value of this field in the SSL configuration for existing listeners that
predate this feature. * The `GET` operation returns `oci-wider-compatible-ssl-cipher-suite-v1`
as the value of this field in the SSL configuration for existing backend sets
that predate this feature. * If the `GET` operation on a listener returns `oci-customized-ssl-cipher-suite`
as the value of this field, you must specify an appropriate predefined or custom
cipher suite name when updating the resource. * The `oci-customized-ssl-cipher-suite`
Oracle reserved cipher suite name is not accepted as valid input for this field.'
- 'example: `example_cipher_suite`'
type: str
protocols:
description:
- A list of SSL protocols the load balancer must support for HTTPS or SSL connections.
- The load balancer uses SSL protocols to establish a secure connection between
a client and a server. A secure connection ensures that all data passed between
the client and the server is private.
- 'The Load Balancing service supports the following protocols:'
- '* TLSv1 * TLSv1.1 * TLSv1.2'
- If this field is not specified, TLSv1.2 is the default.
- '**Warning:** All SSL listeners created on a given port must use the same set
of SSL protocols.'
- '**Notes:**'
- '* The handshake to establish an SSL connection fails if the client supports
none of the specified protocols. * You must ensure compatibility between the
specified SSL protocols and the ciphers configured in the cipher suite. * For
all existing load balancer listeners and backend sets that predate this feature,
the `GET` operation displays a list of SSL protocols currently used by those
resources.'
- 'example: `["TLSv1.1", "TLSv1.2"]`'
elements: str
type: list
server_order_preference:
choices:
- ENABLED
- DISABLED
description:
- When this attribute is set to ENABLED, the system gives preference to the server
ciphers over the client ciphers.
- '**Note:** This configuration is applicable only when the load balancer is acting
as an SSL/HTTPS server. This field is ignored when the `SSLConfiguration` object
is associated with a backend set.'
type: str
trusted_certificate_authority_ids:
description:
- Ids for OCI certificates service CA or CA bundles for the load balancer to trust.
- 'Example: `[ocid1.cabundle.oc1.us-ashburn-1.amaaaaaaav3bgsaagl4zzyqdop5i2vuwoqewdvauuw34llqa74otq2jdsfyq]`'
elements: str
type: list
verify_depth:
description:
- The maximum depth for peer certificate chain verification.
- 'Example: `3`'
type: int
verify_peer_certificate:
description:
- Whether the load balancer listener should verify peer certificates.
- 'Example: `true`'
type: bool
type: dict
config_profile_name:
description:
- The profile to load from the config file referenced by C(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 C(config_file_location).
type: str
path_route_set_name:
description:
- Deprecated. Please use `routingPolicies` instead.
- The name of the set of path-based routing rules, L(PathRouteSet,https://docs.cloud.oracle.com/en-
us/iaas/api/#/en/loadbalancer/20170115/PathRouteSet/), applied to this listener's
traffic.
- 'Example: `example_path_route_set`'
- This parameter is updatable.
type: str
routing_policy_name:
description:
- The name of the routing policy applied to this listener's traffic.
- 'Example: `example_routing_policy`'
- This parameter is updatable.
type: str
api_user_fingerprint:
description:
- 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 C(config_file_location)). To
get the key pair's fingerprint value please refer U(https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm).
type: str
config_file_location:
description:
- 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.
type: str
api_user_key_pass_phrase:
description:
- Passphrase used by the key referenced in C(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 C(config_file_location)).
type: str
connection_configuration:
description:
- ''
- This parameter is updatable.
suboptions:
backend_tcp_proxy_protocol_version:
description:
- The backend TCP Proxy Protocol version.
- 'Example: `1`'
type: int
idle_timeout:
description:
- The maximum idle time, in seconds, allowed between two successive receive or
two successive send operations between the client and backend servers. A send
operation does not reset the timer for receive operations. A receive operation
does not reset the timer for send operations.
- For more information, see L(Connection Configuration,https://docs.cloud.oracle.com/Content/Balance/Reference/connectionreuse.htm#ConnectionConfiguration).
- 'Example: `1200`'
required: true
type: int
type: dict
default_backend_set_name:
description:
- The name of the associated backend set.
- 'Example: `example_backend_set`'
- Required for create using I(state=present), update using I(state=present) with name
present.
type: str
realm_specific_endpoint_template_enabled:
description:
- Enable/Disable realm specific endpoint template for service client. By Default,
realm specific endpoint template is disabled. If not set, then the value of the
OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED variable, if any, is used.
type: bool
listener:
contains:
connection_configuration:
contains:
backend_tcp_proxy_protocol_version:
description:
- The backend TCP Proxy Protocol version.
- 'Example: `1`'
returned: on success
sample: 56
type: int
idle_timeout:
description:
- The maximum idle time, in seconds, allowed between two successive receive
or two successive send operations between the client and backend servers.
A send operation does not reset the timer for receive operations. A receive
operation does not reset the timer for send operations.
- For more information, see L(Connection Configuration,https://docs.cloud.oracle.com/Content/Balance/Reference/connectionreuse.htm#ConnectionConfiguration).
- 'Example: `1200`'
returned: on success
sample: 56
type: int
description:
- ''
returned: on success
type: complex
default_backend_set_name:
description:
- The name of the associated backend set.
- 'Example: `example_backend_set`'
returned: on success
sample: default_backend_set_name_example
type: str
hostname_names:
description:
- An array of hostname resource names.
returned: on success
sample: []
type: list
name:
description:
- A friendly name for the listener. It must be unique and it cannot be changed.
- 'Example: `example_listener`'
returned: on success
sample: name_example
type: str
path_route_set_name:
description:
- Deprecated. Please use `routingPolicies` instead.
- The name of the set of path-based routing rules, L(PathRouteSet,https://docs.cloud.oracle.com/en-
us/iaas/api/#/en/loadbalancer/20170115/PathRouteSet/), applied to this listener's
traffic.
- 'Example: `example_path_route_set`'
returned: on success
sample: path_route_set_name_example
type: str
port:
description:
- The communication port for the listener.
- 'Example: `80`'
returned: on success
sample: 56
type: int
protocol:
description:
- The protocol on which the listener accepts connection requests. To get a list
of valid protocols, use the L(ListProtocols,https://docs.cloud.oracle.com/en-
us/iaas/api/#/en/loadbalancer/20170115/LoadBalancerProtocol/ListProtocols)
operation.
- 'Example: `HTTP`'
returned: on success
sample: protocol_example
type: str
routing_policy_name:
description:
- The name of the routing policy applied to this listener's traffic.
- 'Example: `example_routing_policy_name`'
returned: on success
sample: routing_policy_name_example
type: str
rule_set_names:
description:
- The names of the L(rule sets,https://docs.cloud.oracle.com/en-us/iaas/api/#/en/loadbalancer/20170115/RuleSet/)
to apply to the listener.
- 'Example: ["example_rule_set"]'
returned: on success
sample: []
type: list
ssl_configuration:
contains:
certificate_ids:
description:
- Ids for OCI certificates service certificates. Currently only a single
Id may be passed.
- 'Example: `[ocid1.certificate.oc1.us-ashburn-1.amaaaaaaav3bgsaa5o2q7rh5nfmkkukfkogasqhk6af2opufhjlqg7m6jqzq]`'
returned: on success
sample: []
type: list
certificate_name:
description:
- A friendly name for the certificate bundle. It must be unique and it cannot
be changed. Valid certificate bundle names include only alphanumeric characters,
dashes, and underscores. Certificate bundle names cannot contain spaces.
Avoid entering confidential information.
- 'Example: `example_certificate_bundle`'
returned: on success
sample: certificate_name_example
type: str
cipher_suite_name:
description:
- The name of the cipher suite to use for HTTPS or SSL connections.
- If this field is not specified, the default is `oci-default-ssl-cipher-suite-v1`.
- '**Notes:**'
- '* You must ensure compatibility between the specified SSL protocols
and the ciphers configured in the cipher suite. Clients cannot perform
an SSL handshake if there is an incompatible configuration. * You must
ensure compatibility between the ciphers configured in the cipher suite
and the configured certificates. For example, RSA-based ciphers require
RSA certificates and ECDSA-based ciphers require ECDSA certificates. * If
the cipher configuration is not modified after load balancer creation,
the `GET` operation returns `oci-default-ssl-cipher-suite-v1` as the value
of this field in the SSL configuration for existing listeners that predate
this feature. * If the cipher configuration was modified using Oracle
operations after load balancer creation, the `GET` operation returns `oci-customized-ssl-cipher-suite`
as the value of this field in the SSL configuration for existing listeners
that predate this feature. * The `GET` operation returns `oci-wider-compatible-ssl-cipher-suite-v1`
as the value of this field in the SSL configuration for existing backend
sets that predate this feature. * If the `GET` operation on a listener
returns `oci-customized-ssl-cipher-suite` as the value of this field,
you must specify an appropriate predefined or custom cipher suite name
when updating the resource. * The `oci-customized-ssl-cipher-suite` Oracle
reserved cipher suite name is not accepted as valid input for this field.'
- 'example: `example_cipher_suite`'
returned: on success
sample: cipher_suite_name_example
type: str
protocols:
description:
- A list of SSL protocols the load balancer must support for HTTPS or SSL
connections.
- The load balancer uses SSL protocols to establish a secure connection
between a client and a server. A secure connection ensures that all data
passed between the client and the server is private.
- 'The Load Balancing service supports the following protocols:'
- '* TLSv1 * TLSv1.1 * TLSv1.2'
- If this field is not specified, TLSv1.2 is the default.
- '**Warning:** All SSL listeners created on a given port must use the same
set of SSL protocols.'
- '**Notes:**'
- '* The handshake to establish an SSL connection fails if the client supports
none of the specified protocols. * You must ensure compatibility between
the specified SSL protocols and the ciphers configured in the cipher suite.
* For all existing load balancer listeners and backend sets that predate
this feature, the `GET` operation displays a list of SSL protocols currently
used by those resources.'
- 'example: `["TLSv1.1", "TLSv1.2"]`'
returned: on success
sample: []
type: list
server_order_preference:
description:
- When this attribute is set to ENABLED, the system gives preference to
the server ciphers over the client ciphers.
- '**Note:** This configuration is applicable only when the load balancer
is acting as an SSL/HTTPS server. This field is ignored when the `SSLConfiguration`
object is associated with a backend set.'
returned: on success
sample: ENABLED
type: str
trusted_certificate_authority_ids:
description:
- Ids for OCI certificates service CA or CA bundles for the load balancer
to trust.
- 'Example: `[ocid1.cabundle.oc1.us-ashburn-1.amaaaaaaav3bgsaagl4zzyqdop5i2vuwoqewdvauuw34llqa74otq2jdsfyq]`'
returned: on success
sample: []
type: list
verify_depth:
description:
- The maximum depth for peer certificate chain verification.
- 'Example: `3`'
returned: on success
sample: 56
type: int
verify_peer_certificate:
description:
- Whether the load balancer listener should verify peer certificates.
- 'Example: `true`'
returned: on success
sample: true
type: bool
description:
- ''
returned: on success
type: complex
description:
- Details of the Listener resource acted upon by the current operation
returned: on success
sample:
connection_configuration:
backend_tcp_proxy_protocol_version: 56
idle_timeout: 56
default_backend_set_name: default_backend_set_name_example
hostname_names: []
name: name_example
path_route_set_name: path_route_set_name_example
port: 56
protocol: protocol_example
routing_policy_name: routing_policy_name_example
rule_set_names: []
ssl_configuration:
certificate_ids: []
certificate_name: certificate_name_example
cipher_suite_name: cipher_suite_name_example
protocols: []
server_order_preference: ENABLED
trusted_certificate_authority_ids: []
verify_depth: 56
verify_peer_certificate: true
type: complex