Oracle Cloud Infrastructure Documentation

Oracle Cloud Agent

Oracle Cloud Agent is a lightweight process that manages plugins running on compute instances. Plugins collect performance metrics, install OS updates, and perform other instance management tasks.

To use plugins on an instance, the Oracle Cloud Agent software must be installed on the instance, the plugins must be enabled, and the plugins must be running. You might need to perform additional configuration tasks before you can use certain plugins.

Supported Images

Oracle Cloud Agent: Oracle Cloud Agent is supported on current platform images and on custom images that are based on current platform images. Oracle Cloud Agent is installed by default on current platform images.

If you use an older platform image, you must manually install the Oracle Cloud Agent software. Select an image dated after November 15, 2018 (except Ubuntu, which must be dated after February 28, 2019).

You might have success manually installing Oracle Cloud Agent on other images, though it has not been tested on other operating systems and there is no guarantee that it will work.

Plugins: Plugins are installed as part of Oracle Cloud Agent. The plugins that are supported for an instance depend on the version of Oracle Cloud Agent and on the image that you use to create the instance. To determine which plugins are supported for a particular image, use the Console to create an instance. Or, use the ListInstanceagentAvailablePlugins API operation, providing the OS name and OS version of the image.

Note

On Arm-based OCI Ampere A1 Compute shapes, the Custom Logs Monitoring plugin is not supported.

Available Plugins

Each Oracle Cloud Agent plugin provides functionality related to compute instances. This functionality can enable features that are part of the Compute service, and features that are part of other services.

The following Oracle Cloud Agent plugins are available.

Plugin Name Description Steps to Configure and Use
Bastion Allows secure shell (SSH) connections to an instance without public IP addresses using the Bastion service. See Bastion.
Block Volume Management Configures Block Volume sessions for the instance. See Enabling the Block Volume Management Plugin and Attaching Ultra High Performance Volumes.
Compute Instance Monitoring Emits metrics about the instance's health, capacity, and performance. These metrics are consumed by the Monitoring service. See Enabling Monitoring for Compute Instances and Compute Instance Metrics.
Compute Instance Run Command Runs scripts within the instance to remotely configure, manage, and troubleshoot the instance. See Running Commands on an Instance.
Cloud Guard Workload Protection Allows you to manually manage updates to the Instance Security agent if you are running a custom image which doesn't have Oracle Cloud Agent (OCA) enabled. See Manually Updating the Instance Security Agent.
Custom Logs Monitoring Ingests custom logs into the Logging service. See Custom Logs.
High Performance Computing Performs complex calculations and processes data faster than traditional Compute. See High Performance Computing.
Management Agent Collects data from resources such as OSs, applications, and infrastructure resources for Oracle Cloud Infrastructure services that are integrated with Management Agent. Data can include observability, log, configuration, capacity, and health data. See Deploy Management Agents on Compute Instances.
Oracle Java Management Service Monitors Java deployments on instances managed by the Java Management service. See Java Management.
OS Management Hub Agent Manage and monitor updates and patches for the operating system environment on the instance. See Registering an Instance with OS Management.
Vulnerability Scanning Scans the instance for potential security vulnerabilities like OS packages that require updates. See Scanning Overview.

Required IAM Policy

To use Oracle Cloud Infrastructure, an administrator must be a member of a group granted security access in a policy  by a tenancy administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don't have permission or are unauthorized, verify with the tenancy administrator what type of access you have and which compartment  your access works in.

For administrators: The policy in Let users launch compute instances includes the ability to enable and disable individual plugins, as well as start and stop all plugins on an instance. If the specified group doesn't need to launch instances or attach volumes, you could simplify that policy to include only manage instance-family, and remove the statements involving volume-family and virtual-network-family. In addition, you must use the following policy to allow users to access the available plugins:

Allow group PluginUsers to read instance-agent-plugins in compartment ABC
If you're new to policies, see Managing Identity Domains and Common Policies. For reference material about writing policies for instances, cloud networks, or other Core Services API resources, see Details for Core Services.

Installing the Oracle Cloud Agent Software

Note

If you create an instance using a current platform image or a custom image that is based on a current platform image, then Oracle Cloud Agent is installed by default. No action is needed.

To manually install the Oracle Cloud Agent software on an instance that uses another supported image, use one of the following procedures appropriate to the operating system.

Managing Plugins Using the Console

Managing Plugins Using the API

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

Use these API operations to manage Oracle Cloud Agent plugins:

  • In the Core Services API:

    • LaunchInstance - enables or disables plugins, or stops all plugins, when you create an instance.
    • GetInstance and ListInstances - gets information about which plugins are enabled on an instance (or a list of instances).
    • UpdateInstance - enables or disables individual plugins, and stops or starts all plugins, for an existing instance.

  • In the Oracle Cloud Agent API:

    • ListInstanceagentAvailablePlugins - lists the plugins that are available for all instances. You can filter the results based on the image that you plan to use to launch an instance.
    • ListInstanceAgentPlugins - gets information about the plugins that are available on an existing compute instance.
    • GetInstanceAgentPlugin - gets information about a specific plugin on an existing compute instance.

Updating the Oracle Cloud Agent Software

We recommend always running the latest version of the Oracle Cloud Agent software.

If the instance can access the internet, then no action is needed. Oracle Cloud Agent periodically checks for newer versions and installs the latest version when an update is available.

If the instance does not have access to the internet, then you must manually update the Oracle Cloud Agent software. For example, a compute instance cannot access the internet if it does not have a public IP address, internet gateway, or service gateway. In this situation, Oracle Cloud Agent cannot complete its checks for newer versions.

Oracle Cloud Agent Release Notes

Uninstalling the Oracle Cloud Agent Software

You can uninstall the Oracle Cloud Agent software from an instance. After you uninstall Oracle Cloud Agent, features that depend on Oracle Cloud Agent plugins are not available for the instance.