You can create an OCI external database handle for the following types of external databases:

The handle stores a few pieces of metadata that enable you to manage your database instance within OCI. This metadata includes the following information related to managing the handle in OCI:

• An Oracle Cloud ID (OCID), which enables the external database instance to be identified and managed within OCI.
• An OCI display name.
• Compartment assignment information (optional).
• Tags (optional).

For more information, see:

• Oracle Cloud IDs (OCIDs)
• compartments in About Oracle Cloud Basics
• Tagging Overview

In addition to the OCI-related metadata, the handle stores metadata derived from the database instance. This includes the database unique name, the Oracle Database software edition and version, and other details. All of this information stored by the handle can be viewed in the OCI Console or retrieved using the API. Metadata derived from the external database instance (such as database unique name) is only populated in the handle after a database connection is established between the handle and the instance.

After you create and connect an external container database handle, you can use the handle to scan the external container database and discover pluggable databases that have not been connected to OCI. If any pluggable databases are discovered that are not connected to OCI, the connection details for these databases are listed in the work request generated by the scan operation.

For more information, see:

• Create a Handle to an External Container Database
• Create a Connection to an External Container Database
• Scan an External Container Database for Pluggable Databases
• Work Requests

The OCI database connection resource stores details about how a specific handle connects to an external Oracle Database instance. These details include the following:

• Connection type and OCI agent ID
• User credentials and role
• Connection strings information, including the following:
  • DNS hostname, single-client access name (SCAN), or virtual IP (VIP) address
  • Port
  • Service name
  • Network protocol (TCP or TCPS)
    Note
    
    

    • TCPS is TCP/IP with SSL. This protocol enables an Oracle application on a client to communicate with remote databases through TCP/IP and SSL. Using SSL provides higher security than TCP alone. For more information, see TCP/IP with SSL Protocol in Database Net Services Administrator's Guide.
    • If you use TCPS, you must provide a database user password and password secret, along with the following:
      • regular database credentials
      • the ssl key and trust store wallet locations on the management agent and their passwords
      • distinguished name values.

      All SSL details are accepted through the secret resource.

You can create an OCI external database connection resource for the following types of external databases:

• External container databases
• External pluggable databases
• External non-container databases

For more information, see:

To use the OCI external database, you will need the following:

• An OCI tenancy.
• One or more external databases located outside of OCI. OCI external database supports container databases, pluggable databases, and non-container databases that use the following Oracle Database software versions: 11gR2, 12cR1, 12cR2, 18c, and 19c.
• A Management Agent service agent with source credentials.

For more information, see:

• Learn Best Practices for Setting Up Your Tenancy
• Management Agent

The OCI Management Agent is required to create a connection with an external database. It is also required to enable the communication and data collection between an external database and other OCI services such as Database Management, Operations Insights, and the Monitoring service.

A Management Agent permission is required to allow a user in a particular user group to manage the management-agents resource-type in a specific compartment:

ALLOW GROUP <group_name> TO MANAGE management-agents IN COMPARTMENT <compartment_name>

In addition, you must create a dynamic group for all the management agents to be used by the external database. This is required to allow the external database to interact with the OCI service endpoints. A dynamic group is created using the IAM service from the OCI Console.

When creating a dynamic group, you can define a rule that will ensure that all the management agents in a compartment or in the tenancy are added to the dynamic group. This will ensure that this step is a one-time setup step and any new management agent being installed will automatically belong to the dynamic group.

Example: Create a dynamic group named Management_Agent_Dynamic_Group with the following under Rule 1:

ALL {resource.type='managementagent', resource.compartment.id='ocid1.compartment.oc1.examplecompartmentid'}

Where resource.type='managementagent' is the management agent resource-type definition for Management Agent at the dynamic group level, and resource.compartment.id value is the compartment OCID.

This can also be created more generically to cover agents from all compartments of the tenancy:

ALL {resource.type='managementagent'}

Once the dynamic group is created, you must create policies to allow the management agents to interact with the Management Agent service and to allow the management agents to upload data to OCI Monitoring service.

Example: The following commands allow Management_Agent_Dynamic_Group dynamic group to interact with the Management Agent service in Agents_Compartment compartment, and upload data to the Monitoring service.

ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO MANAGE management-agents IN COMPARTMENT Agents_Compartment
ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO USE METRICS IN COMPARTMENT Agents_Compartment