The OCI Management Agent service collects data from services and sources for monitoring and management in Oracle Cloud Infrastructure. In this blog post series I will show you how you can monitor and manage an on-premises Oracle databases in OCI. The communication between an agent and OCI requires an Agent Install Key and is based on HTTPS. Service Plugins extend a Management Agent for example for Oracle database performance monitoring and management or log analytics.
This is a small blog post series
- Part 1 shows the installation of the Management Agent on an on-premises system
- Part 2 describes how to manage this Oracle database in OCI
- Part 3 watches behind the scenes for billing, job execution etc.
My Setup
- An OCI Tenant in datacenter EU-FRANKFURT-1
- An OCI compartment called datacenter-kestenholz
- An on-premises Container Database called CDB114, running on Oracle Linux 7
- Three on-premises Pluggable Databases
TYPE (Cluster|DG) : SID/PROCESS STATUS HOME [2021-02-22 08:05:03] ----------------------------------------------------------------------------- Dummy rdbms_ee : rdbms19 n/a /u01/app/oracle/product/19.0.0/dbhome_1 DB-instance (N|N) : CDB144 open /u01/app/oracle/product/19.0.0/dbhome_1 Listener : LISTENER up /u01/app/oracle/product/19.0.0/dbhome_1
Prerequisites for Management Agent Installation
- Oracle Linux 6 or higher
- Red Hat Enterprise Linux 6 or higher
- CentOS 6 or 7
- SUSE Linux Enterprise Server 12 or 15
- Windows Server 2012 R2, 2016 or 2019
There are other prerequisites on the target server like the correct Java version (e.g. version 11 does not work) and sudo permissions. For the complete list of prerequisites, see here:
Setup for OCI Management Agent
It is recommended to handle the agents in a separate user group and with policies. This allows us to define the Management Agent management on an fine granular level.
Group AGENT_ADMINS
According the documentation, I have created an user group called AGENT_ADMINS.
Policy Datacenter_Kestenholz_Agent_Policy
ALLOW GROUP AGENT_ADMINS TO MANAGE management-agents IN COMPARTMENT datacenter-kestenholz ALLOW GROUP AGENT_ADMINS TO MANAGE management-agent-install-keys IN COMPARTMENT datacenter-kestenholz ALLOW GROUP AGENT_ADMINS TO READ METRICS IN COMPARTMENT datacenter-kestenholz ALLOW GROUP AGENT_ADMINS TO READ USERS IN TENANCY
Dynamic Group Management_Agent_Dynamic_Group
New added agents in the compartment belong automatically to this group. Replace the OCID with the OCID for your compartment.
Policy Datacenter_Kestenholz_Agent_Communication_Policy
A policy is required that allows the agents to communicate with the OCI endpoints. This policy is important, otherwise you run in an communication error (see below in section troubleshooting).
ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO MANAGE management-agents IN COMPARTMENT datacenter-kestenholz ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO USE METRICS IN COMPARTMENT datacenter-kestenholz
Install On-Premises Management Agent
Create Agent Install Key
Go to Management Agent Menu / Downloads and Keys, create a new Agent Install Key. Set the compartment and the time how long the key is valid. In this example, I need to replace the key after one month.
When click on Download Key to File, a textfile is created with the ManagementAgentInstallKey and all other (optional) parameters which can be used for install. You can use this file as responsefile template later.
Download the Software and Transfer it to the Target Server
I use the Agent for Linux and transferred it to the target on-premises server into a stage directory as OS user root.
[root@bifangstrasse stage]# ll total 8128 -rw-r--r--. 1 root root 8323072 Feb 21 20:38 oracle.mgmt_agent.rpm
Create a Local Response File
This is an example of a simple two-lines response file for agent installation in the same folder where the rpm is located, called input.rsp. The parameter managementAgentInstallKey is visible in the OCI web interface, the CredentialWalletPassword is your password for the wallet.
managementAgentInstallKey = MS4wLHVzLWFzaGJ1cm4tMSxvY2lkMS50ZW5hbmN5-<YOUR_AGENT_KEY_HERE> CredentialWalletPassword = W3lcome#1
RPM Installation
As OS user root (or a user with sudo permissions) – install the rpm file. Here you can see that the minimum required Java version is not met.
[root@bifangstrasse stage]#
Verifying... ################################# [100%]
Preparing... ################################# [100%]
Checking pre-requisites
Checking if any previous agent service exists
Checking if OS has systemd or initd
Checking available disk space for agent install
Checking if /opt/oracle/mgmt_agent directory exists
Checking if 'mgmt_agent' user exists
Checking agent version
Checking Java version
JAVA_HOME is not set or not readable to root
Trying default path /usr/bin/java
Agent only supports JDK 8 with a miniumum upgrade version JDK 8u162. Please set your preferred path in JAVA_HOME
error: %prein(oracle.mgmt_agent-210114.0548-1.x86_64) scriptlet failed, exit status 1
error: oracle.mgmt_agent-210114.0548-1.x86_64: install failed
After installing the jdk-8u281-linux-x64.rpm to update the server Java version, the installer runs fine.
[root@bifangstrasse stage]# rpm -Uhv jdk-8u281-linux-x64.rpm
warning: jdk-8u281-linux-x64.rpm: Header V3 RSA/SHA256 Signature, key ID ec551f03: NOKEY
Verifying... ################################# [100%]
Preparing... ################################# [100%]
Updating / installing...
1:jdk1.8-2000:1.8.0_281-fcs ################################# [100%]
Unpacking JAR files...
tools.jar...
plugin.jar...
javaws.jar...
deploy.jar...
rt.jar...
jsse.jar...
charsets.jar...
localedata.jar...
[root@bifangstrasse stage]# java -version
java version "1.8.0_281"
Java(TM) SE Runtime Environment (build 1.8.0_281-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.281-b09, mixed mode)
2nd try – successful
[root@bifangstrasse stage]# rpm -ihv oracle.mgmt_agent.rpm
Verifying... ################################# [100%]
Preparing... ################################# [100%]
Checking pre-requisites
Checking if any previous agent service exists
Checking if OS has systemd or initd
Checking available disk space for agent install
Checking if /opt/oracle/mgmt_agent directory exists
Checking if 'mgmt_agent' user exists
Checking agent version
Checking Java version
JAVA_HOME is not set or not readable to root
Trying default path /usr/bin/java
Java version: 1.8.0_281 found at /usr/bin/java
Updating / installing...
1:oracle.mgmt_agent-210114.0548-1 ################################# [100%]
Executing install
Unpacking software zip
Copying files to destination dir (/opt/oracle/mgmt_agent)
Initializing software from template
Creating 'mgmt_agent' daemon
Agent Install Logs: /opt/oracle/mgmt_agent/installer-logs/installer.log.0
Setup agent using input response file (run as any user with 'sudo' privileges)
Usage:
sudo /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=[FULL_PATH_TO_INPUT.RSP]
Agent install successful
Agent Configuration
Run the install script with the created response file as additional parameter. The agent will be started automatically.
[root@bifangstrasse stage]# /opt/oracle/mgmt_agent/agent_inst/bin/setup.sh opts=/stage/input.rsp
Executing configure
Parsing input response file
Generating communication wallet
Validating install key
Generating security artifacts
Registering Management Agent
Starting agent...
Agent started successfully
Agent setup completed and the agent is running.
In the future agent can be started by directly running: sudo systemctl start mgmt_agent
Please make sure that you delete /stage/input.rsp or store it in secure location.
A systemd service is created.
[root@bifangstrasse stage]# systemctl list-units --type=service --state=active | grep mgmt_agent mgmt_agent.service loaded active running mgmt_agent
Verify the Management Agent in Oracle Cloud Infrastructure
Immediately after the setup, the Management Agent is visible with status Active in OCI and starts uploading data.
Agent details:
Troubleshooting
Management Agent logfiles are located in directory /opt/oracle/mgmt_agent/agent_inst/log.
[root@bifangstrasse log]# ls -latr total 64 drwxr-x---. 7 mgmt_agent mgmt_agent 68 Feb 21 21:23 .. -rw-r-----. 1 mgmt_agent mgmt_agent 5 Feb 21 21:24 mgmt_agent.pid -rw-r-----. 1 mgmt_agent mgmt_agent 3631 Feb 21 21:24 wrapper.log -rw-r-----. 1 mgmt_agent mgmt_agent 0 Feb 21 21:24 mgmt_agent_errors.log -rw-r-----. 1 mgmt_agent mgmt_agent 0 Feb 21 21:24 mgmt_agent_work.log -rw-r-----. 1 mgmt_agent mgmt_agent 75 Feb 21 21:24 agent.pid -rw-r-----. 1 mgmt_agent mgmt_agent 1679 Feb 21 21:24 startup.info drwxr-x---. 2 mgmt_agent mgmt_agent 246 Feb 21 21:24 . -rw-r-----. 1 mgmt_agent mgmt_agent 8 Feb 21 21:24 mgmt_agent.status -rw-r-----. 1 mgmt_agent mgmt_agent 8 Feb 21 21:24 mgmt_agent.java.status -rw-r-----. 1 mgmt_agent mgmt_agent 31966 Feb 21 21:25 mgmt_agent.log -rw-r-----. 1 mgmt_agent mgmt_agent 5091 Feb 21 21:25 mgmt_agent_client.log
Example error when the policy for agent communication is not set properly:
Error:
<--> Endpoint: management-agent.eu-frankfurt-1.oci.oraclecloud.com:-1
opc-request-id: US3E76CLWXAJYY5YH6Y37BOULWGHCTT1
StartTime: 2021-02-21 20:12:44,529 GMT
Status: 404 Not Found
Headers: Content-Length=111
opc-request-id=US3E76CLWXAJYY5YH6Y37BOULWGHCTT1/01E0A8DF939076673DF971035E99E335/5BB6AA66C5811DC0CA68288F16327F47
Date=Sun, 21 Feb 2021 20:12:44 GMT
Content-Type=application/json
ErrorBody:
{
"code" : "NotAuthorizedOrNotFound",
"message" : "Authorization failed or requested resource not found."
}
EndTime: 2021-02-21 20:12:44,795 GMT
From My Oracle Support: OCI : Management Agent Status Reporting As “Not Available” Post Installation (Doc ID 2745566.1)
Summary Part 1
The Management Agent installation and integration is easy to setup when all prerequisites are met. For troubleshooting you have full access on the agent logs. See you for blog post 2, where I try to integrate the on-premises Oracle databases into OCI.