Skip to content

Commit 2d2662c

Browse files
AlexanderHodickeAlexanderHodicke
authored
Merge pull request #856 from oracle-devrel/external_dbs_observability_and_management
External dbs observability and management v2
2 parents b738392 + 9ec1ae4 commit 2d2662c

File tree

16 files changed

+888
-0
lines changed

16 files changed

+888
-0
lines changed

‎manageability-and-operations/observability-and-manageability/external-database-enablement/README.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Enable Observability & Management for Multiple External Database Systems with Terraform
2+
3+
This Terraform asset enables Database Management, Operations Insights, and/or Stack Monitoring for multiple external container and pluggable databases based on input from two JSON-files in **root_module**:
4+
- **db_systems.json**
5+
- **db_credentials.json**
6+
7+
Reviewed: 18.03.25
8+
9+
## How does it work?
10+
11+
OCI's [External Database Service](https://docs.oracle.com/en-us/iaas/external-database/index.html) handles management agent connections to on-prem database systems. Using these connections, certain services in Observability & Management can then be enabled for the external databases: [Database Management](https://docs.oracle.com/en-us/iaas/database-management/home.htm), [Operations Insights](https://docs.oracle.com/en-us/iaas/operations-insights/home.htm), and [Stack Monitoring](https://docs.oracle.com/en-us/iaas/stack-monitoring/index.html). After [installing management agents](https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html), the Terraform configuration files in this asset can perform the database connection setup for agents and enable Observability & Management services for all external databases
12+
13+
## When to use this asset?
14+
15+
This asset is for anyone managing multiple on-prem database systems who needs to enable services in Observability & Management. Instead of spending valuable time doing this manually for each container and pluggable database in the OCI Console, just use these Terraform configuration files to complete the setup for you
16+
17+
## How to use this asset?
18+
19+
### Prerequisites
20+
21+
1. Prepare required policies for Management Agent Service, Database Management, Operations Insights, and/or Stack Monitoring:
22+
- Click [here](https://docs.oracle.com/en-us/iaas/management-agents/doc/perform-prerequisites-deploying-management-agents.html) for more about Management Agent policies
23+
- Click [here](https://docs.oracle.com/en-us/iaas/database-management/doc/permissions-required-enable-database-management-external-databases.html#DBMGM-GUID-3DDC9D5F-99B8-4DD5-A0C4-194D29FC883F) for more about Database Management policies
24+
- Click [here](https://docs.oracle.com/en-us/iaas/operations-insights/doc/set-groups-users-and-policies.html) for more about Operations Insights policies
25+
- Click [here](https://docs.oracle.com/en-us/iaas/stack-monitoring/doc/service-requirements.html) for more about Stack Monitoring policies
26+
2. [Install management agent(s)](https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html) connecting to database systems
27+
28+
**NOTE**: The management agent can either be installed locally on a database instance host or connect to databases remotely on a separate machine. The agent can connect to and monitor one or more databases
29+
30+
4. [Install Terraform and create RSA keys for API signing](https://docs.oracle.com/en-us/iaas/developer-tutorials/tutorials/tf-provider/01-summary.htm)
31+
32+
**NOTE**: Remember to save the values in the **configuration file preview** when adding the public API key to an OCI user
33+
34+
### Prepare and apply Terraform configurations
35+
36+
1. Download **root_module** and its configuration files to the machine with the private RSA key and Terraform installation
37+
2. Set configuration options for the OCI provider in **root_module/provider.tf**
38+
39+
**NOTE**: Most options can be set with the configuration file preview values shown when adding a public API key to an OCI user
40+
3. Set **compartment_ocid** variable in **root_module/variables.tf**
41+
42+
**NOTE**: This is the compartment where everything will be managed in the External Database Service: database connections and enablement of services in Observability & Management. This will also be the compartment where all monitoring data will be located across the enabled services
43+
4. Define your database systems in **root_module/db_systems.json**. See **root_module/db_systems_example.json** for an example:
44+
- Create a database system object for every database system. You can copy-paste the **system1** object as a template in **root_module/db_systems.json**
45+
46+
**NOTE**: You can name the keys for the system objects however you want as long as they are unique e.g. system1, system2, systemA, systemB, Alpha, Beta, etc.
47+
- For each database system object, copy-paste the template within the **pdbs** array to match the number of pluggable databases per system
48+
- Now fill out the details for each container and pluggable database in the database system objects as described below:
49+
50+
| ***Key*** | ***Description*** | ***Mandatory*** |
51+
|--------------|-----------|------------|
52+
| **host** | Host name used by management agent for connections with container and pluggable databases in system<br>**NOTE**: It is recommended to use the SCAN hostname for RAC systems | Yes |
53+
| **port** | Port used by management agent for connections with container and pluggable databases in system<br>**NOTE**: Set to 1521 by default if no value is provided | Yes |
54+
| **protocol** | Protocol used by management agent for connections with container and pluggable databases in system<br>**NOTE**: Must be **TCP** or **TCPS** | Yes |
55+
| **managementAgentId** | OCID of the management agent connecting to container and pluggable databases in system | Yes |
56+
| **databaseCredentials** | Key for credential object in **root_module/db_credentials.json** used by management agent for database connections<br>**NOTE**: If **protocol** is set to **TCPS**, the credential object must include **sslSecretId** | Yes |
57+
| **containerName** | Desired name for container database | Yes |
58+
| **containerServiceName** | Service name used by management agent for container database connection | Yes |
59+
| **containerDBManagement** | Add **enable** or **disable** to manage Database Management enablement for container database | Yes |
60+
| **dbManagementLicense** | Add **BRING_YOUR_OWN_LICENSE** or **LICENSE_INCLUDED** to select the license type used for Database Management. Click [here](https://docs.oracle.com/en-us/iaas/database-management/doc/enable-database-management-external-databases.html) for more | Yes, if **containerDBManagement** is set to **enable** |
61+
| **containerStackMonitoring** | Add **enable** or **disable** to manage Stack Monitoring enablement for container database | Yes |
62+
| **asmStackMonitoring** | Add **enable** or **disable** to manage Stack Monitoring enablement for ASM<br>**NOTE**: Enablement requires **containerStackMonitoring** to be **enable** as well | Yes |
63+
| **asmHost** | Host name used by management agent for ASM connection | Yes, if **asmStackMonitoring** is set to **enable** |
64+
| **asmPort** | Port used by management agent for ASM connection | Yes, if **asmStackMonitoring** is set to **enable** |
65+
| **asmServiceName** | Service name used by management agent for ASM connection | Yes, if **asmStackMonitoring** is set to **enable** |
66+
| **asmCredentials** | Key for credential object in **root_module/db_credentials.json** used by management agent for ASM connection<br>**NOTE**: Credential object must include **userPasswordSecretId** for the ASM password | Yes, if **asmStackMonitoring** is set to **enable** |
67+
| **pdbName** | Desired name for pluggable database | Yes |
68+
| **databaseCredentials** | Key for credential object in **root_module/db_credentials.json** used by management agent for database connections<br>**NOTE**: If **protocol** is set to **TCPS**, the credential object must include **sslSecretId** | Yes |
69+
| **pdbServiceName** | Service name used by management agent for pluggable database connection | Yes |
70+
| **pdbDBManagement** | Add **enable** or **disable** to manage Database Management enablement for pluggable database<br>**NOTE**: Enablement requires **containerDBManagement** to be **enable** as well | Yes |
71+
| **pdbStackMonitoring** | Add **enable** or **disable** to manage Database Management enablement for pluggable database<br>**NOTE**: Enablement DOES NOT REQUIRE **containerStackMonitoring** to be **enable** as well | Yes |
72+
| **pdbOPSI** | Add **enable** or **disable** to manage Operations Insights enablement for pluggable database | Yes |
73+
74+
5. Define your database credentials in **root_module/db_credentials.json**. See **root_module/db_credentials_example.json** for an example:
75+
- Create a credential object for every credential set used for management agent connections in **root_module/db_systems.json**. You can copy-paste the **cred1** and/or **cred2** objects as templates in **root_module/db_credentials.json**
76+
- Now fill out the details for each credential object as described below:
77+
| ***Key*** | ***Description*** | ***Mandatory*** |
78+
|--------------|-----------|------------|
79+
| **userName** | Database user name for management agent connections e.g. DBSNMP | Yes |
80+
| **userPassword** | Database user password in plain text for management agent connections | No, if using **userPasswordSecretId** instead |
81+
| **userPasswordSecretId** | OCID for encrypted Secret with database user password in OCI Vault. Click [here](https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/managingsecrets.htm) for more<br>**NOTE**: Required to enable Stack Monitoring for ASM | No, if using **userPassword** instead |
82+
| **userRole** | Database user role for management agent connections<br>**NOTE**: For database connections, **userRole** can be **NORMAL** or **SYSDBA**. For ASM connections, **userRole** can be **SYSASM**, **SYSDBA**, or **SYSOPER** | Yes |
83+
| **sslSecretId** | OCID for encrypted Secret with JSON containing SSL-settings for database connections via TCPS. Click [here](https://docs.oracle.com/en-us/iaas/external-database/doc/create-connection-external-database.html#EXTUG-GUID-59ECD72C-EAC2-426D-B865-D8DDB1297F0E) for more | Yes, if **protocol** is set to **TCPS** for database system object in **root_module/db_systems.json**|
84+
85+
**NOTE**: **CREDENTIAL VALUES ABOVE ARE SAVED AS PLAIN TEXT** IN BOTH **root_module/db_credentials.json** AS WELL AS IN **root_module/terraform.tfstate** AFTER APPLYING THE TERRAFORM CONFIGURATION. **ENSURE THAT THESE FILES ARE STORED SECURELY**
86+
87+
6. Run the following commands from **root_module** to initialize the Terraform configuration, see its execution plan, and finally apply that plan:
88+
89+
**terraform init**<br>
90+
**terraform plan**<br>
91+
**terraform apply**<br>
92+
93+
### Update applied Terraform configurations
94+
95+
To apply new configurations, update **root_module/db_systems.json** and/or **root_module/db_credentials.json** and run **terraform apply** from **root_module** again
96+
97+
### Destroy applied Terraform configurations
98+
To remove everything previously applied by Terraform configurations, run **terraform destroy** from **root_module**
99+
100+
## Useful Links
101+
102+
- [Oracle](https://www.oracle.com)
103+
- Oracle's Main Website
104+
- [Terraform Provider](https://registry.terraform.io/providers/oracle/oci/latest/docs)
105+
- General documentaion for Terraform's Oracle Cloud Infrastructure Provider
106+
- [Management Agent Service](https://docs.oracle.com/en-us/iaas/management-agents/index.html)
107+
- General documentation for Management Agent Service
108+
- [External Database Service](https://docs.oracle.com/en-us/iaas/external-database/index.html)
109+
- General documentation for External Database Service
110+
- [Database Management](https://docs.oracle.com/en-us/iaas/database-management/home.htm)
111+
- General documentation for Database Management
112+
- [Operations Insights](https://docs.oracle.com/en-us/iaas/operations-insights/home.htm)
113+
- General documentation for Operations Insights
114+
- [Stack Monitoring](https://docs.oracle.com/en-us/iaas/stack-monitoring/index.html)
115+
- General documentation for Stack Monitoring
116+
117+
## License
118+
119+
Copyright (c) 2025 Oracle and/or its affiliates.
120+
121+
Licensed under the Universal Permissive License (UPL), Version 1.0.
122+
123+
See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.

‎manageability-and-operations/observability-and-manageability/external-database-enablement/db_credentials_example.json

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"cred1": {
3+
"userName":"DBSNMP",
4+
"userPassword":"<INSERT PASSWORD HERE>",
5+
"userRole":"NORMAL"
6+
},
7+
"cred2": {
8+
"userName":"ASMSNMP",
9+
"userPasswordSecretId":"ocid1.vaultsecret.oc1.XXXXXX",
10+
"userRole":"SYSDBA"
11+
},
12+
"cred3": {
13+
"userName":"DBSNMP",
14+
"userPasswordSecretId":"ocid1.vaultsecret.oc1.XXXXXX",
15+
"userRole":"NORMAL",
16+
"sslSecretId":"ocid1.vaultsecret.oc1.XXXXXX"
17+
}
18+
}

‎manageability-and-operations/observability-and-manageability/external-database-enablement/db_systems_example.json

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
{
2+
"system1": {
3+
"host":"dba.com",
4+
"port":"1521",
5+
"protocol":"TCP",
6+
"managementAgentId":"ocid1.managementagent.oc1.XXXXXX",
7+
"databaseCredentials":"cred1",
8+
"containerName":"DBA_container",
9+
"containerServiceName":"dba_container_service",
10+
"containerDBManagement":"disable",
11+
"dbManagementLicense":"",
12+
"containerStackMonitoring":"enable",
13+
"asmStackMonitoring":"enable",
14+
"asmHost":"dba_asm.com",
15+
"asmPort":"1525",
16+
"asmServiceName":"+ASM",
17+
"asmCredentials":"cred2",
18+
"pdbs":[
19+
{
20+
"pdbName":"DBA_pdb1",
21+
"databaseCredentials":"cred1",
22+
"pdbServiceName":"dba_pdb1_service",
23+
"pdbDBManagement":"disable",
24+
"pdbStackMonitoring":"enable",
25+
"pdbOPSI":"enable"
26+
}
27+
]
28+
},
29+
"system2": {
30+
"host":"dbb-scan.com",
31+
"port":"2484",
32+
"protocol":"TCPS",
33+
"managementAgentId":"ocid1.managementagent.oc1.XXXXXX",
34+
"databaseCredentials":"cred3",
35+
"containerName":"DBB_container",
36+
"containerServiceName":"dbb_container_service",
37+
"containerDBManagement":"enable",
38+
"dbManagementLicense":"BRING_YOUR_OWN_LICENSE",
39+
"containerStackMonitoring":"enable",
40+
"asmStackMonitoring":"disable",
41+
"asmHost":"",
42+
"asmPort":"",
43+
"asmServiceName":"",
44+
"asmCredentials":"",
45+
"pdbs":[
46+
{
47+
"pdbName":"DBB_pdb1",
48+
"databaseCredentials":"cred3",
49+
"pdbServiceName":"dbb_pdb1_service",
50+
"pdbDBManagement":"enable",
51+
"pdbStackMonitoring":"disable",
52+
"pdbOPSI":"enable"
53+
},
54+
{
55+
"pdbName":"DBB_pdb2",
56+
"databaseCredentials":"cred3",
57+
"pdbServiceName":"dbb_pdb2_service",
58+
"pdbDBManagement":"enable",
59+
"pdbStackMonitoring":"enable",
60+
"pdbOPSI":"disable"
61+
}
62+
]
63+
}
64+
}

‎manageability-and-operations/observability-and-manageability/external-database-enablement/root_module/db_credentials.json

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"cred1": {
3+
"userName":"DBSNMP",
4+
"userPassword":"<INSERT PASSWORD HERE>",
5+
"userRole":"NORMAL"
6+
},
7+
"cred2": {
8+
"userName":"DBSNMP",
9+
"userPasswordSecretId":"ocid1.vaultsecret.oc1.XXXXXX",
10+
"userRole":"NORMAL",
11+
"sslSecretId":"ocid1.vaultsecret.oc1.XXXXXX"
12+
}
13+
}

‎manageability-and-operations/observability-and-manageability/external-database-enablement/root_module/db_systems.json

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"system1": {
3+
"host":"IP ADDRESS OR HOSTNAME TO ACCESS DATABASE SYSTEM",
4+
"port":"1521",
5+
"protocol":"TCP OR TCPS",
6+
"managementAgentId":"OCID FOR MANAGEMENT AGENT CONNECTING TO CONTAINER AND PLUGGABLE DATABASES",
7+
"databaseCredentials":"KEY FOR THE CORRECT CREDENTIAL OBJECT IN db_credentials.json. IF protocol IS TCPS, CREDENTIAL OBJECT MUST INCLUDE sslSecretId",
8+
"containerName":"container1",
9+
"containerServiceName":"CONTAINER SERVICE NAME",
10+
"containerDBManagement":"INSERT enable OR disable TO MANAGE DATABASE MANAGEMENT FOR CONTAINER DATABASE",
11+
"dbManagementLicense":"BRING_YOUR_OWN_LICENSE OR LICENSE_INCLUDED",
12+
"containerStackMonitoring":"INSERT enable OR disable TO MANAGE STACK MONITORING FOR CONTAINER DATABASE",
13+
"asmStackMonitoring":"INSERT enable OR disable TO MANAGE STACK MONITORING FOR ASM. IF disable, OTHER ASM DETAILS ARE IGNORED",
14+
"asmHost":"IP ADDRESS OR HOSTNAME TO ACCESS ASM INSTANCE",
15+
"asmPort":"PORT TO ACCESS ASM INSTANCE",
16+
"asmServiceName":"ASM SERVICE NAME",
17+
"asmCredentials":"KEY FOR THE CORRECT CREDENTIAL OBJECT IN db_credentials.json. CREDENTIAL OBJECT MUST INCLUDE userPasswordSecretId",
18+
"pdbs":[
19+
{
20+
"pdbName":"pdb1",
21+
"databaseCredentials":"KEY FOR THE CORRECT CREDENTIAL OBJECT IN db_credentials.json",
22+
"pdbServiceName":"PDB SERVICE NAME",
23+
"pdbDBManagement":"INSERT enable OR disable TO MANAGE DATABASE MANAGEMENT FOR PLUGGABLE DATABASE",
24+
"pdbStackMonitoring":"INSERT enable OR disable TO MANAGE STACK MONITORING FOR PLUGGABLE DATABASE",
25+
"pdbOPSI":"INSERT enable OR disable TO MANAGE OPERATIONS INSIGHTS FOR PLUGGABLE DATABASE"
26+
}
27+
]
28+
}
29+
}

0 commit comments

Comments
 (0)