oci_load_balancer_listener - Add, modify and remove a listener from a backend set of a load balancer in OCI Load Balancing Service¶
New in version 2.5.
Synopsis¶
- Add a listener to a backend set in a OCI Load Balancer
- Update a listener in a Load Balancer, if present, with any changed attribute
- Delete a listener from OCI Load Balancer Backends, if present.
Requirements¶
The below requirements are needed on the host that executes this module.
- python >= 2.6
- Python SDK for Oracle Cloud Infrastructure https://oracle-cloud-infrastructure-python-sdk.readthedocs.io
Parameters¶
Parameter | Choices/Defaults | Comments | |
---|---|---|---|
api_user |
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_OCID 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 |
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 |
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 |
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_type |
|
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. |
|
config_file_location |
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 |
Default: DEFAULT
|
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 . |
|
connection_configuration |
Configuration details for the connection between the client and backend servers.
|
||
idle_timeout
required |
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.
|
||
default_backend_set_name |
The name of the associated backend set. Mandatory for create and update.
|
||
hostname_names |
An array of hostname resource names.
|
||
load_balancer_id
required |
Identifier of the Load Balancer in which the listener belongs.
aliases: id |
||
name
required |
Name of the listener. It must be unique and it cannot be changed. Mandatory field for all use cases.
|
||
path_route_set_name |
The name of the set of path-based routing rules, PathRouteSet, applied to this listener's traffic.
|
||
port |
The communication port for the listener. Mandatory for create and update.
|
||
protocol |
The protocol on which the listener accepts connection requests. Mandatory for create and update.
|
||
purge_hostname_names
bool |
|
Purge any Hostname names in the Listener named name that is not specified in hostname_names. This is only applicable in case of updating Listener.If purge_hostname_names=no, provided hostname_names would be appended to existing hostname_names.
|
|
region |
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. |
||
ssl_configuration |
The load balancer SSL handling configuration details
|
||
certificate_name
required |
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.
|
||
verify_depth |
The maximum depth for peer certificate chain verification.
|
||
verify_peer_certificate |
Whether the load balancer listener should verify peer certificates.
|
||
state |
|
Create,update or delete Load Balancer Backend. For state=present, if it does not exists, it gets added. If exists, it gets updated.
|
|
tenancy |
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 |
||
wait
bool |
|
Whether to wait for create or delete operation to complete.
|
|
wait_timeout |
Default: 1200
|
Time, in seconds, to wait when wait=yes.
|
|
wait_until |
The lifecycle state to wait for the resource to transition into when wait=yes. By default, when wait=yes, we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/ RUNNING applicable lifecycle state during create operation & to get into DELETED/DETACHED/ TERMINATED lifecycle state during delete operation.
|
Notes¶
Note
- For OCI python sdk configuration, please refer to https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html
Examples¶
# Note: These examples do not set authentication details.
# Create Listener
- name: Create Listener
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
default_backend_set_name: "ansible_backend_set"
protocol: "HTTP"
port: 80
ssl_configuration:
certificate_name: 'certs1'
verify_depth: 1
verify_peer_certificate: True
connection_configuration:
idle_timeout: 1200
hostname_names: ['hostname_001']
path_route_set_name: 'path_route_set_001'
state: 'present'
# Update Listener
- name: Update Listener Port
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
default_backend_set_name: "ansible_backend_set"
protocol: "HTTP"
port: 82
state: 'present'
- name: Update Listener's SSL Configuration
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
default_backend_set_name: "ansible_backend_set"
protocol: "HTTP"
port: 80
ssl_configuration:
certificate_name: 'certs2'
verify_depth: 2
verify_peer_certificate: False
state: 'present'
- name: Update Listener's Connection Configuration
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
default_backend_set_name: "ansible_backend_set"
protocol: "HTTP"
port: 80
connection_configuration:
idle_timeout: 1200
state: 'present'
- name: Update Listener's Hostname Names by appending new name
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
hostname_names: ['hostname_002']
purge_hostname_names: False
state: 'present'
- name: Update Listener's Hostname Names by replacing existing names
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
hostname_names: ['hostname_002']
purge_hostname_names: True
state: 'present'
- name: Update Listener's Path Route Set Name
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
path_route_set_name: 'path_route_set_002'
state: 'present'
# Delete listener
- name: Delete Listener
oci_load_balancer_listener:
load_balancer_id: "ocid1.loadbalancer.oc1.iad.xxxxxEXAMPLExxxxx"
name: "ansible_listener"
state: 'absent'
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description | |
---|---|---|---|
listener
complex
|
success |
Attributes of the created/updated Listener. For delete, deleted Listener description will be returned.
Sample:
{'path_route_set_name': 'path_route_set_001', 'protocol': 'HTTP', 'name': 'ansible_listener', 'connection_configuration': {'idle_timeout': 1200}, 'ssl_configuration': {'certificate_name': 'certs1', 'verify_depth': 1, 'verify_peer_certificate': True}, 'hostname_names': ['hostname_001'], 'default_backend_set_name': 'ansible_backend', 'port': 87}
|
|
path_route_set_name
string
|
always |
The name of the set of path-based routing rules, PathRouteSet, applied to this listener's traffic.
Sample:
path_route_set_001
|
|
protocol
string
|
always |
The protocol on which the listener accepts connection requests.
Sample:
HTTP
|
|
name
string
|
always |
Name of the Listener
Sample:
ansible_listener
|
|
connection_configuration
dict
|
always |
Configuration details for the connection between the client and backend servers.
Sample:
{'idle_timeout': 1200}
|
|
ssl_configuration
dict
|
always |
The load balancer SSL handling configuration details
Sample:
{'certificate_name': 'certs1', 'verify_depth': 1, 'verify_peer_certificate': True}
|
|
hostname_names
list
|
always |
An array of hostname resource names.
Sample:
['hostname_001']
|
|
default_backend_set_name
string
|
always |
The name of the associated backend set
Sample:
ansible_backend_set
|
|
port
string
|
always |
The communication port for the listener.
Sample:
80
|
Status¶
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Author¶
- Debayan Gupta(@debayan_gupta)
Hint
If you notice any issues in this documentation you can edit this document to improve it.