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 4.10.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.

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.
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 OCPU cores available for AMD-based virtual machine DB systems.
Applicable when creation_type is 'NewDbSystem'
creation_type
string
    Choices:
  • NewDbSystem
  • ExistingVmCluster
  • ExistingDbSystem
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
    Choices:
  • no
  • yes
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
    Choices:
  • no
  • yes
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
    Choices:
  • no
  • yes
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
    Choices:
  • no ←
  • yes
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
    Choices:
  • no
  • yes
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
    Choices:
  • LICENSE_INCLUDED
  • BRING_YOUR_OWN_LICENSE
The Oracle license model that applies to all the databases on the dataguard standby DB system. The default is LICENSE_INCLUDED.
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
    Choices:
  • MAXIMUM_AVAILABILITY
  • MAXIMUM_PERFORMANCE
  • MAXIMUM_PROTECTION
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.
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
    Choices:
  • present ←
The state of the DataGuardAssociation.
Use state=present to create or update a DataGuardAssociation.
storage_volume_performance_mode
string
    Choices:
  • BALANCED
  • HIGH_PERFORMANCE
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
    Choices:
  • SYNC
  • ASYNC
  • FASTSYNC
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
    Choices:
  • no
  • yes ←
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.

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)