Getting Started with Resource Discovery and Monitoring
Before you can use the Resource Discovery and Monitoring features of the OS Management service, you need to enable the automatic deployment of the Management Agent and plugin. The following section guides you through the setup and configuration process to activate Resource Discovery and Monitoring functionality.
General Workflow for Setting Up Resource Discovery and Monitoring
Step 1: Choose the OCI Compartment
Step 2: Set Up OS Management Service Policies
Step 3: Create a Dynamic Groups of All Management Agents
Step 4: Set Up Resource Discovery and Monitoring Policies
Ensure that the prerequisites have been performed for the Management Agent. For more information on performing prerequisite setup tasks for the Management Agent, see Perform Prerequisites for Deploying Management Agents on Compute Instances. As part of the Management Agent setup, it will require the creation of a group of instances. Consider re-using the dynamic group whenever possible. For example, you create a dynamic group of instances that can be re-used in the following steps.
Management Agent policies only need to be set up once for each compartment or tenancy.
Step 1: Choose the OCI Compartment
You need to identify the OCI compartment where you want the feature enabled. Users of the Resource Monitoring and Discovery feature must have access to the Compute instances within this compartment. Once you've identified the OCI Compartment with the Compute instances containing the resources you want to monitor, you need to ensure the prerequisite policies have been set up.
If you want to enable the features for multiple compartments, the policies described in subsequent sections must be set up for each compartment. For a list of resource types that can be monitored, see Monitor Resources.
Step 2: Set Up OS Management Service Policies
If you have not already done so, you'll need to set up polices for the OS Management service. These policies only need to be set up once, per compartment or per tenancy.
For prerequisites and explicit instructions on setting up OS Management policies, see Setting Up Policies for OS Management. This only needs to be run one time per compartment.
You first need to create a dynamic group of Compute instances and then create policies on that dynamic group to enable OS Management service.
A single instance can belong to a maximum of five dynamic groups. A good practice is to re-use the same dynamic group wherever possible across services instead of creating one or more dynamic groups for each service. Make a note of the dynamic group used to set up the policies for OS Management service, and consider re-using that same dynamic group for the policies described in subsequent steps.
For more information about this limitation, see Managing Dynamic Groups.
If a Compute instance existed before policy setup, you need to bounce its Oracle Cloud Agent or wait 24 hours for policies to take effect.
You can verify that the policy is in effect from the OS Management service home page for a specific Compute instance.
Step 3: Create a Dynamic Groups of All Management Agents
To interact with the Oracle Cloud Infrastructure service end-points, users must explicitly create a dynamic group to allow Management Agents to communicate with the Management Agent service (MACS).
In this step, a dynamic group is created using the Identity and Access Management service from the OCI Console. This group includes all the management agents. This is a one-time set up step, as any new management agent being installed will automatically belong to this group based on resource type definition shown below.
-
To access the Identity and Access Management service, open the navigation menu. Under Identity & Security, go to Identity and click Dynamic Groups.
-
Click Create Dynamic Group.
-
In the Create Dynamic Group dialog box, enter a name for the dynamic group, a description and the matching rules, and then click Create Dynamic Group.
Create a Dynamic Group of Management Agent Resources
For example, you 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 dynamic group level, and resource.compartment.id value is the compartment id.
Create a Dynamic Group of Instances
For example, you create a dynamic group named AppmgmtMonitoredInstances with the following under RULE 1:
ALL {instance.compartment.id='<compartment-ocid>'}Create a Policy for Agent Communication
Once both dynamic groups are created, you need to create a policies to allow the management agents to interact with the Management Agent service and to allow the management agents to upload data to Oracle Cloud Infrastructure Monitoring service.
ALLOW DYNAMIC-GROUP Management_Agent_Dynamic_Group TO USE METRICS IN COMPARTMENT <compartment id from the definition of this dynamic group> where target.metrics.namespace = 'oracle_appmgmt'ALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {MGMT_AGENT_DEPLOY_PLUGIN_CREATE, MGMT_AGENT_INSPECT, MGMT_AGENT_READ} IN COMPARTMENT <compartment_name>Step 4: Set Up Resource Discovery and Monitoring Policies
The following policies/permissions are specific to Resource Discovery and Monitoring. The policies only need to be set up once for each compartment or tenancy.
Create the User Group AppmgmtUsers
You need to create a group of users who will use the monitoring features and then grant appropriate policies to the users.
Configure the Policy Statements
ALLOW GROUP AppmgmtUsers TO USE appmgmt-family IN COMPARTMENT <compartment_name>
ALLOW GROUP AppmgmtUsers TO READ metrics IN COMPARTMENT <compartment_name>If the Compute instance existed before policy setup, bounce its Oracle Cloud Agent or wait 24 hours for policies to take effect.
Enabling Resource Discovery and Monitoring Automatically
Automatic activation requires Oracle Cloud Agent version 1.14 or later be installed on the Compute instance.
The following dynamic group policies will allow each Compute instance to automatically enable this functionality. This allows each instance in the defined compartment(s) to automatically install the OCA Management Agent plugin and deploy the Stack Monitoring plugin that is required for OS Management service Monitored Resource and Top Processes functionality.
Configure the Policy Statements
ALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {APPMGMT_MONITORED_INSTANCE_READ, APPMGMT_MONITORED_INSTANCE_ACTIVATE}
IN COMPARTMENT <compartment_name> where request.instance.id = target.monitored-instance.idALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {INSTANCE_UPDATE}
IN COMPARTMENT <compartment_name> where request.instance.id = target.instance.idALLOW DYNAMIC-GROUP AppmgmtMonitoredInstances TO {APPMGMT_WORK_REQUEST_READ, INSTANCE_AGENT_PLUGIN_INSPECT}
IN COMPARTMENT <compartment_name>Make sure the OS Management service is enabled/operational first. This is a prerequisite for automatic enabling functionality along with the policy setup performed above.
Within 15 minutes, the UI should start showing monitored resources/top processes.
Step 5: Enabling Resource Discovery and Monitoring Manually
The following procedure is only needed if the prior steps (which should have auto-deployed the agent) did not successfully occur for some reason.
Enabling Resource Discovery and Monitoring manually involves the following steps:
Deploy the Management Agent Plugin
- From OCI Console main menu, select Compute and then Instances. The Instances page displays.
- Click on the name of your instance from the table. The Instance Details page displays.
- Click the Oracle Cloud Agent tab.
- In the Enable Plugin column, make sure the Management Agent plugin is set to Enabled.
- Proceed with Deploy the Stack Monitoring Management Agent Plugin.
Deploy the Stack Monitoring Management Agent Plugin
Once the Management Agent is enabled via calling UpdateInstance metadata, it will appear in the OCI Console where you deploy the Stack Monitoring plugin.
- From the OCI Console main menu, click Observability & Management. Under Management Agent , click Agents. The Management Agents page displays.
- From the Scope menu, select the desired Compartment. The agent running in the Compartment appears in the Agents list.
- Click on the vertical ellipses (3 vertical dots) menu located at the far right of the agent line to open the drop-down menu showing actions that can be performed.
- From the drop-down menu, choose Deploy Plugins. The Deploy Plugins dialog displays.
- Select Stack Monitoring and click Update to close the dialog and initiate the deployment process.
The plugin will be installed on the selected agent (instance) in a few minutes and immediately start reporting metrics
.Step 6: (Optional) Set up Java Management Service
If you are planning to use the Java Management Service integration, you will also need to complete these additional steps.
Complete Java Management Service Setup
Ensure that the prerequisites have been performed for the Java Management Service. For more information on performing prerequisite setup tasks for the Java Management Service, see Setting Up Oracle Cloud Infrastructure for Java Management Service. Part of setting up the Java Management Service requires the creation of a group of Management Agents and instances. For those steps, consider re-using the dynamic groups created for the OS Management service and Management Agent setup.
Conifigure Management Agents on OCI Hosts
Follow Configuring a Management Agent on an OCI Compute Instance instructions
for each host on which you want to collect Java Runtime details. For Step 4 of
the instructions, make sure to execute the setup script with the
--enable-user-name flag as shown in section describing collection
of user.name property.
Create a Fleet
Create a fleet to group your Java Management resources. For instructions on how to create a Java Management Service fleet, see Creating a Fleet Using an Existing Management Agent Configuration.
Configure the User Policy Statement
You need to add following policy to your AppmgmtUsers group.
ALLOW GROUP AppmgmtUsers TO READ fleet IN COMPARTMENT <compartment_name>