oracle.oci.oci_database_data_guard_association – Manage a DataGuardAssociation resource in Oracle Cloud Infrastructure¶
Note
This plugin is part of the oracle.oci collection (version 5.0.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_database_data_guard_association
.
New in version 2.9.0: of oracle.oci
Synopsis¶
This module allows the user to create and update a DataGuardAssociation resource in Oracle Cloud Infrastructure
For state=present, creates a new Data Guard association. A Data Guard association represents the replication relationship between the specified database and a peer database. For more information, see Using Oracle Data Guard.
All Oracle Cloud Infrastructure resources, including Data Guard associations, get an Oracle-assigned, unique ID called an Oracle Cloud Identifier (OCID). When you create a resource, you can find its OCID in the response. You can also retrieve a resource’s OCID by using a List API operation on that resource type, or by viewing the resource in the Console. For more information, see Resource Identifiers.
This resource has the following action operations in the oracle.oci.oci_database_data_guard_association_actions module: failover, reinstate, switchover.
Requirements¶
The below requirements are needed on the host that executes this module.
python >= 3.6
Python SDK for Oracle Cloud Infrastructure https://oracle-cloud-infrastructure-python-sdk.readthedocs.io
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
|
|
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
|
|
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. |
|
availability_domain
string
|
The name of the availability domain that the standby database DB system will be located in. For example- "Uocm:PHX-AD-1".
Applicable when creation_type is 'NewDbSystem'
|
||
backup_network_nsg_ids
list
/ elements=string
|
A list of the OCIDs of the network security groups (NSGs) that the backup network of this DB system belongs to. Setting this to an empty array after the list is created removes the resource from all NSGs. For more information about NSGs, see Security Rules. Applicable only to Exadata systems.
Applicable when creation_type is 'NewDbSystem'
|
||
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 . |
||
cpu_core_count
integer
|
The number of CPU cores available for AMD-based virtual machine DB systems.
Applicable when creation_type is 'NewDbSystem'
|
||
creation_type
string
|
|
Specifies whether to create the peer database in an existing DB system or in a new DB system.
Required for create using state=present.
|
|
data_collection_options
dictionary
|
Applicable when creation_type is 'NewDbSystem'
|
||
is_diagnostics_events_enabled
boolean
|
|
Indicates whether diagnostic collection is enabled for the VM cluster/Cloud VM cluster/VMBM DBCS. Enabling diagnostic collection allows you to receive Events service notifications for guest VM issues. Diagnostic collection also allows Oracle to provide enhanced service and proactive support for your Exadata system. You can enable diagnostic collection during VM cluster/Cloud VM cluster provisioning. You can also disable or enable it at any time using the `UpdateVmCluster` or `updateCloudVmCluster` API.
Applicable when creation_type is 'NewDbSystem'
|
|
is_health_monitoring_enabled
boolean
|
|
Indicates whether health monitoring is enabled for the VM cluster / Cloud VM cluster / VMBM DBCS. Enabling health monitoring allows Oracle to collect diagnostic data and share it with its operations and support personnel. You may also receive notifications for some events. Collecting health diagnostics enables Oracle to provide proactive support and enhanced service for your system. Optionally enable health monitoring while provisioning a system. You can also disable or enable health monitoring anytime using the `UpdateVmCluster`, `UpdateCloudVmCluster` or `updateDbsystem` API.
Applicable when creation_type is 'NewDbSystem'
|
|
is_incident_logs_enabled
boolean
|
|
Indicates whether incident logs and trace collection are enabled for the VM cluster / Cloud VM cluster / VMBM DBCS. Enabling incident logs collection allows Oracle to receive Events service notifications for guest VM issues, collect incident logs and traces, and use them to diagnose issues and resolve them. Optionally enable incident logs collection while provisioning a system. You can also disable or enable incident logs collection anytime using the `UpdateVmCluster`, `updateCloudVmCluster` or `updateDbsystem` API.
Applicable when creation_type is 'NewDbSystem'
|
|
data_guard_association_id
string
|
The Data Guard association's OCID.
Required for update using state=present when environment variable
OCI_USE_NAME_AS_IDENTIFIER is not set.aliases: id |
||
database_admin_password
string
|
A strong password for the `SYS`, `SYSTEM`, and `PDB Admin` users to apply during standby creation.
The password must contain no fewer than nine characters and include:
* At least two uppercase characters.
* At least two lowercase characters.
* At least two numeric characters.
* At least two special characters. Valid special characters include "_", "#", and "-" only.
**The password MUST be the same as the primary admin password.**
Required for create using state=present.
This parameter is updatable.
|
||
database_defined_tags
dictionary
|
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
Applicable when creation_type is 'NewDbSystem'
|
||
database_freeform_tags
dictionary
|
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags.
Example: `{"Department": "Finance"}`
Applicable when creation_type is 'NewDbSystem'
|
||
database_id
string
/ required
|
The database OCID.
|
||
database_software_image_id
string
|
The database software image OCID
|
||
db_system_defined_tags
dictionary
|
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags.
Applicable when creation_type is 'NewDbSystem'
|
||
db_system_freeform_tags
dictionary
|
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags.
Example: `{"Department": "Finance"}`
Applicable when creation_type is 'NewDbSystem'
|
||
display_name
string
|
The user-friendly name of the DB system that will contain the the standby database. The display name does not have to be unique.
Required for create, update when environment variable
OCI_USE_NAME_AS_IDENTIFIER is set.Applicable when creation_type is 'NewDbSystem'
aliases: name |
||
fault_domains
list
/ elements=string
|
A Fault Domain is a grouping of hardware and infrastructure within an availability domain. Fault Domains let you distribute your instances so that they are not on the same physical hardware within a single availability domain. A hardware failure or maintenance that affects one Fault Domain does not affect DB systems in other Fault Domains.
If you do not specify the Fault Domain, the system selects one for you. To change the Fault Domain for a DB system, terminate it and launch a new DB system in the preferred Fault Domain.
If the node count is greater than 1, you can specify which Fault Domains these nodes will be distributed into. The system assigns your nodes automatically to the Fault Domains you specify so that no Fault Domain contains more than one node.
To get a list of Fault Domains, use the ListFaultDomains operation in the Identity and Access Management Service API.
Example: `FAULT-DOMAIN-1`
Applicable when creation_type is 'NewDbSystem'
|
||
force_create
boolean
|
|
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 key_by.
|
|
hostname
string
|
The hostname for the DB node.
Applicable when creation_type is 'NewDbSystem'
|
||
is_active_data_guard_enabled
boolean
|
|
True if active Data Guard is enabled.
This parameter is updatable.
|
|
key_by
list
/ elements=string
|
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.
|
||
license_model
string
|
|
The Oracle license model that applies to all the databases on the dataguard standby DB system. The default is LICENSE_INCLUDED. Bring your own license (BYOL) allows you to select the DB edition using the optional parameter, for Autonomous Database Serverless.
Applicable when creation_type is 'NewDbSystem'
|
|
node_count
integer
|
The number of nodes to launch for the DB system of the standby in the Data Guard association. For a 2-node RAC virtual machine DB system, specify either 1 or 2. If you do not supply this parameter, the default is the node count of the primary DB system.
Applicable when creation_type is 'NewDbSystem'
|
||
nsg_ids
list
/ elements=string
|
The list of OCIDs for the network security groups (NSGs) to which this resource belongs. Setting this to an empty list removes all resources from all NSGs. For more information about NSGs, see Security Rules. **NsgIds restrictions:** - A network security group (NSG) is optional for Autonomous Databases with private access. The nsgIds list can be empty.
Applicable when creation_type is 'NewDbSystem'
|
||
peer_db_home_id
string
|
The OCID of the DB home in which to create the standby database. You must supply this value to create standby database with an existing DB home
Applicable when creation_type is one of ['ExistingDbSystem', 'ExistingVmCluster']
|
||
peer_db_system_id
string
|
The OCID of the DB system in which to create the standby database. You must supply this value if creationType is `ExistingDbSystem`.
Applicable when creation_type is 'ExistingDbSystem'
|
||
peer_db_unique_name
string
|
Specifies the `DB_UNIQUE_NAME` of the peer database to be created.
|
||
peer_sid_prefix
string
|
Specifies a prefix for the `Oracle SID` of the database to be created.
|
||
peer_vm_cluster_id
string
|
The OCID of the VM Cluster in which to create the standby database. You must supply this value if creationType is `ExistingVmCluster`.
Applicable when creation_type is 'ExistingVmCluster'
|
||
private_ip
string
|
The IPv4 address from the provided OCI subnet which needs to be assigned to the VNIC. If not provided, it will be auto-assigned with an available IPv4 address from the subnet.
Applicable when creation_type is 'NewDbSystem'
|
||
protection_mode
string
|
|
The protection mode to set up between the primary and standby databases. For more information, see Oracle Data Guard Protection Modes in the Oracle Data Guard documentation.
**IMPORTANT** - The only protection mode currently supported by the Database service is MAXIMUM_PERFORMANCE.
Required for create using state=present.
This parameter is updatable.
|
|
realm_specific_endpoint_template_enabled
boolean
|
|
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.
|
|
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. |
||
shape
string
|
The virtual machine DB system shape to launch for the standby database in the Data Guard association. The shape determines the number of CPU cores and the amount of memory available for the DB system. Only virtual machine shapes are valid options. If you do not supply this parameter, the default shape is the shape of the primary DB system.
To get a list of all shapes, use the ListDbSystemShapes operation.
Applicable when creation_type is 'NewDbSystem'
|
||
state
string
|
|
The state of the DataGuardAssociation.
Use state=present to create or update a DataGuardAssociation.
|
|
storage_volume_performance_mode
string
|
|
The block storage volume performance level. Valid values are `BALANCED` and `HIGH_PERFORMANCE`. See Block Volume Performance for more information.
Applicable when creation_type is 'NewDbSystem'
|
|
subnet_id
string
|
The OCID of the subnet the DB system is associated with. **Subnet Restrictions:** - For 1- and 2-node RAC DB systems, do not use a subnet that overlaps with 192.168.16.16/28
These subnets are used by the Oracle Clusterware private interconnect on the database instance. Specifying an overlapping subnet will cause the private interconnect to malfunction. This restriction applies to both the client subnet and backup subnet.
Applicable when creation_type is 'NewDbSystem'
|
||
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 |
||
time_zone
string
|
The time zone of the dataguard standby DB system. For details, see DB System Time Zones.
Applicable when creation_type is 'NewDbSystem'
|
||
transport_type
string
|
|
The redo transport type to use for this Data Guard association. Valid values depend on the specified `protectionMode`:
* MAXIMUM_AVAILABILITY - SYNC or FASTSYNC * MAXIMUM_PERFORMANCE - ASYNC * MAXIMUM_PROTECTION - SYNC
For more information, see Redo Transport Services in the Oracle Data Guard documentation.
**IMPORTANT** - The only transport type currently supported by the Database service is ASYNC.
Required for create using state=present.
This parameter is updatable.
|
|
wait
boolean
|
|
Whether to wait for create or delete operation to complete.
|
|
wait_timeout
integer
|
Time, in seconds, to wait when wait=yes. Defaults to 1200 for most of the services but some services might have a longer wait timeout.
|
Notes¶
Note
For OCI python sdk configuration, please refer to https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html
Examples¶
- name: Create data_guard_association with creation_type = NewDbSystem
oci_database_data_guard_association:
# required
creation_type: NewDbSystem
database_admin_password: example-password
protection_mode: MAXIMUM_AVAILABILITY
transport_type: SYNC
# optional
display_name: display_name_example
availability_domain: Uocm:PHX-AD-1
shape: shape_example
cpu_core_count: 56
storage_volume_performance_mode: BALANCED
node_count: 56
subnet_id: "ocid1.subnet.oc1..xxxxxxEXAMPLExxxxxx"
nsg_ids: [ "nsg_ids_example" ]
backup_network_nsg_ids: [ "backup_network_nsg_ids_example" ]
hostname: hostname_example
time_zone: time_zone_example
fault_domains: [ "fault_domains_example" ]
private_ip: private_ip_example
license_model: LICENSE_INCLUDED
db_system_freeform_tags: null
db_system_defined_tags: null
database_freeform_tags: null
database_defined_tags: null
data_collection_options:
# optional
is_diagnostics_events_enabled: true
is_health_monitoring_enabled: true
is_incident_logs_enabled: true
database_software_image_id: "ocid1.databasesoftwareimage.oc1..xxxxxxEXAMPLExxxxxx"
peer_db_unique_name: peer_db_unique_name_example
peer_sid_prefix: peer_sid_prefix_example
is_active_data_guard_enabled: true
- name: Create data_guard_association with creation_type = ExistingVmCluster
oci_database_data_guard_association:
# required
creation_type: ExistingVmCluster
database_admin_password: example-password
protection_mode: MAXIMUM_AVAILABILITY
transport_type: SYNC
# optional
peer_vm_cluster_id: "ocid1.peervmcluster.oc1..xxxxxxEXAMPLExxxxxx"
database_software_image_id: "ocid1.databasesoftwareimage.oc1..xxxxxxEXAMPLExxxxxx"
peer_db_unique_name: peer_db_unique_name_example
peer_sid_prefix: peer_sid_prefix_example
peer_db_home_id: "ocid1.peerdbhome.oc1..xxxxxxEXAMPLExxxxxx"
is_active_data_guard_enabled: true
- name: Create data_guard_association with creation_type = ExistingDbSystem
oci_database_data_guard_association:
# required
creation_type: ExistingDbSystem
database_admin_password: example-password
protection_mode: MAXIMUM_AVAILABILITY
transport_type: SYNC
# optional
database_software_image_id: "ocid1.databasesoftwareimage.oc1..xxxxxxEXAMPLExxxxxx"
peer_db_unique_name: peer_db_unique_name_example
peer_sid_prefix: peer_sid_prefix_example
peer_db_system_id: "ocid1.peerdbsystem.oc1..xxxxxxEXAMPLExxxxxx"
peer_db_home_id: "ocid1.peerdbhome.oc1..xxxxxxEXAMPLExxxxxx"
is_active_data_guard_enabled: true
- name: Update data_guard_association
oci_database_data_guard_association:
# required
database_id: "ocid1.database.oc1..xxxxxxEXAMPLExxxxxx"
data_guard_association_id: "ocid1.dataguardassociation.oc1..xxxxxxEXAMPLExxxxxx"
# optional
database_admin_password: example-password
protection_mode: MAXIMUM_AVAILABILITY
transport_type: SYNC
is_active_data_guard_enabled: true
- name: Update data_guard_association using name (when environment variable OCI_USE_NAME_AS_IDENTIFIER is set)
oci_database_data_guard_association:
# required
display_name: display_name_example
database_id: "ocid1.database.oc1..xxxxxxEXAMPLExxxxxx"
# optional
database_admin_password: example-password
protection_mode: MAXIMUM_AVAILABILITY
transport_type: SYNC
is_active_data_guard_enabled: true
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description | |
---|---|---|---|
data_guard_association
complex
|
on success |
Details of the DataGuardAssociation resource acted upon by the current operation
Sample:
{'apply_lag': 'apply_lag_example', 'apply_rate': 'apply_rate_example', 'database_id': 'ocid1.database.oc1..xxxxxxEXAMPLExxxxxx', 'id': 'ocid1.resource.oc1..xxxxxxEXAMPLExxxxxx', 'is_active_data_guard_enabled': True, 'lifecycle_details': 'lifecycle_details_example', 'lifecycle_state': 'PROVISIONING', 'peer_data_guard_association_id': 'ocid1.peerdataguardassociation.oc1..xxxxxxEXAMPLExxxxxx', 'peer_database_id': 'ocid1.peerdatabase.oc1..xxxxxxEXAMPLExxxxxx', 'peer_db_home_id': 'ocid1.peerdbhome.oc1..xxxxxxEXAMPLExxxxxx', 'peer_db_system_id': 'ocid1.peerdbsystem.oc1..xxxxxxEXAMPLExxxxxx', 'peer_role': 'PRIMARY', 'protection_mode': 'MAXIMUM_AVAILABILITY', 'role': 'PRIMARY', 'time_created': '2013-10-20T19:20:30+01:00', 'transport_type': 'SYNC'}
|
|
apply_lag
string
|
on success |
The lag time between updates to the primary database and application of the redo data on the standby database, as computed by the reporting database.
Example: `9 seconds`
Sample:
apply_lag_example
|
|
apply_rate
string
|
on success |
The rate at which redo logs are synced between the associated databases.
Example: `180 Mb per second`
Sample:
apply_rate_example
|
|
database_id
string
|
on success |
The OCID of the reporting database.
Sample:
ocid1.database.oc1..xxxxxxEXAMPLExxxxxx
|
|
id
string
|
on success |
The OCID of the Data Guard association.
Sample:
ocid1.resource.oc1..xxxxxxEXAMPLExxxxxx
|
|
is_active_data_guard_enabled
boolean
|
on success |
True if active Data Guard is enabled.
Sample:
True
|
|
lifecycle_details
string
|
on success |
Additional information about the current lifecycleState, if available.
Sample:
lifecycle_details_example
|
|
lifecycle_state
string
|
on success |
The current state of the Data Guard association.
Sample:
PROVISIONING
|
|
peer_data_guard_association_id
string
|
on success |
The OCID of the peer database's Data Guard association.
Sample:
ocid1.peerdataguardassociation.oc1..xxxxxxEXAMPLExxxxxx
|
|
peer_database_id
string
|
on success |
The OCID of the associated peer database.
Sample:
ocid1.peerdatabase.oc1..xxxxxxEXAMPLExxxxxx
|
|
peer_db_home_id
string
|
on success |
The OCID of the Database Home containing the associated peer database.
Sample:
ocid1.peerdbhome.oc1..xxxxxxEXAMPLExxxxxx
|
|
peer_db_system_id
string
|
on success |
The OCID of the DB system containing the associated peer database.
Sample:
ocid1.peerdbsystem.oc1..xxxxxxEXAMPLExxxxxx
|
|
peer_role
string
|
on success |
The role of the peer database in this Data Guard association.
Sample:
PRIMARY
|
|
protection_mode
string
|
on success |
The protection mode of this Data Guard association. For more information, see Oracle Data Guard Protection Modes in the Oracle Data Guard documentation.
Sample:
MAXIMUM_AVAILABILITY
|
|
role
string
|
on success |
The role of the reporting database in this Data Guard association.
Sample:
PRIMARY
|
|
time_created
string
|
on success |
The date and time the Data Guard association was created.
Sample:
2013-10-20T19:20:30+01:00
|
|
transport_type
string
|
on success |
The redo transport type used by this Data Guard association. For more information, see Redo Transport Services in the Oracle Data Guard documentation.
Sample:
SYNC
|
Authors¶
Oracle (@oracle)