oracle / oracle.oci / 4.21.0 / module / oci_loadbalancer_listener Manage a Listener resource in Oracle Cloud Infrastructure | "added in version" 2.9.0 of oracle.oci" Authors: Oracle (@oracle) preview | supported by communityoracle.oci.oci_loadbalancer_listener (4.21.0) — module
Install with ansible-galaxy collection install oracle.oci:==4.21.0
collections: - name: oracle.oci version: 4.21.0
This 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 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