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 Autonomous Linux`	Manages autonomous updates and collects data associated with events, including logs and stack traces, for instances managed by the Autonomous Linux service.	See Oracle Autonomous Linux.
`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.
`OS Management Service Agent`	Manage and monitor updates and patches for the operating system environment on the instance.	See 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, you must be granted security access in a policy by an 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 your administrator what type of access you have and which compartment to work 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 Getting Started with Policies 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.

To manually install Oracle Cloud Agent on a Linux instance

Connect to the instance.
To download the Oracle Cloud Agent software, do one of the following things.
Oracle Linux
1. To determine whether the Oracle Cloud Agent software is installed, run one of the following commands. On Oracle Linux:
  
  sudo yum info oracle-cloud-agent
  
  On Oracle Linux Cloud Developer:
  
  rpm -qa | grep oracle-cloud-agent
  
  The command returns the Oracle Cloud Agent version that is currently installed.
2. If Oracle Cloud Agent isn't installed, or if the installed version is not the latest version, install the latest version by running the following command:
  
  sudo yum install -y oracle-cloud-agent
  
  Note
  
  If you don't have access to the yum repository that has Oracle Cloud Agent, obtain the Oracle Cloud Agent installation file by contacting support.
CentOS
To obtain the Oracle Cloud Agent installation file, contact support. Save the Oracle Cloud Agent installation file to the instance.
Ubuntu
Note

To install Oracle Cloud Agent on instances that use Ubuntu images, Snapcraft must be installed on the instance. Install Snapcraft by running the following commands, in sequence:

sudo apt update

sudo apt install snapd
sudo snap install oracle-cloud-agent --classic
This command installs and runs the Oracle Cloud Agent software.
To run the Oracle Cloud Agent software on the instance, enter one of the following commands.
Oracle Linux
sudo yum install -y <instance-agent-filename>
CentOS
sudo yum install -y <instance-agent-filename>
Ubuntu
No further action is needed. The command in the previous step installs and runs the software.

To manually install Oracle Cloud Agent on a Windows instance

To obtain the Oracle Cloud Agent installation file, contact support.
Connect to the instance.
Save the Oracle Cloud Agent installation file to the instance.
As a user with administrative privileges, enter the following command to run the Oracle Cloud Agent software on the instance.
```
msiexec /qb /i <instance-agent-filename>
```

To install Oracle Cloud Agent using cloud-init when creating an instance

If you want to install Oracle Cloud Agent on an instance that uses an older image as part of the instance launch, you can provide a cloud-init script (cloudbase-init on Windows instances) when you create the instance.

Obtain the Oracle Cloud Agent installation file. Do one of the following things, depending on the image:

Oracle Linux
If you have access to the yum repository that has Oracle Cloud Agent, proceed to the following step. If you don't have access to the yum repository, obtain the Oracle Cloud Agent installation file by contacting support.

CentOS
Obtain the Oracle Cloud Agent installation file by contacting support.

Ubuntu
Proceed to the following step.

Windows Server
Obtain the Oracle Cloud Agent installation file by contacting support.
Follow the steps to create an instance, until the advanced options.
Click Show advanced options.
On the Management tab, in the Initialization script section, select Paste cloud-init script. Then, copy and paste one of the following scripts, depending on the image.
Oracle Linux
sudo yum install -y oracle-cloud-agent
Note

If you don't have access to the yum repository that has Oracle Cloud Agent, paste the following script.

Cloud-init script for Oracle Linux instances without access to yum repository
#!/bin/sh curl -O <URL/to/installation_file.rpm> -v yum install -y ~/<installation_file.rpm> -v
<URL/to/installation_file.rpm> is the URL of the Oracle Cloud Agent installation file provided by Oracle support.
<installation_file.rpm> is the filename of the installation file.
CentOS
#!/bin/sh curl -O <URL/to/installation_file.rpm> -v yum install -y ~/<installation_file.rpm> -v
<URL/to/installation_file.rpm> is the URL of the Oracle Cloud Agent installation file provided by Oracle support.
<installation_file.rpm> is the filename of the installation file.
Ubuntu
Note

To install Oracle Cloud Agent on instances that use Ubuntu images, Snapcraft must be installed on the instance. Install Snapcraft by running the following commands, in sequence:

sudo apt update

sudo apt install snapd
sudo snap install oracle-cloud-agent --classic
Windows Server
#ps1_sysnative md c:\temp cd \temp Invoke-WebRequest -Uri "<URL/to/installation_file.msi>" -OutFile "c:\temp\OracleCloudAgentSetup.msi" msiexec /i "c:\temp\OracleCloudAgentSetup.msi" /quiet /L*V "c:\temp\OracleCloudAgentSetup.log"
<URL/to/installation_file.msi> is the URL of the Oracle Cloud Agent installation file provided by Oracle support.
Note

For legacy versions of Windows images, ensure that cloudbase-init is supported. See WinRM and cloudbase-init on Windows images.
Click Create.

Managing Plugins Using the Console

To see which plugins are enabled for an instance

Open the navigation menu and click Compute. Under Compute, click Instances.
Click the instance that you're interested in.
Click the Oracle Cloud Agent tab.

The list of plugins is displayed. Enabled plugins can have the following statuses:
- RUNNING: The plugin is running.
- STOPPED: The plugin is stopped.
- NOT_SUPPORTED: The plugin is not supported on this platform.
- INVALID: The plugin status is not recognizable by the service.

To enable or disable a plugin

Open the navigation menu and click Compute. Under Compute, click Instances.
Click the instance that you're interested in.
Click the Oracle Cloud Agent tab.
Toggle the Enabled or Disabled switch for the plugin.

Caution

Functionality that depends on the plugin, such as monitoring, autoscaling, or OS management, will not work when the plugin is disabled.

It takes up to 10 minutes for the change to take effect.
If you enabled a plugin, if necessary, perform any configuration tasks that are required before you can use the plugin. For information about how to configure each plugin, see the documentation for each plugin in Available Plugins.

To stop all plugins on an instance

You can stop all of the plugins that are running on an instance. Any individual plugins that are enabled on the instance remain enabled, but the plugin processes stop running. The plugin processes will only start running again after you restart all plugins.

For example, if you want to troubleshoot plugins, you can stop all plugins and then disable the plugins that you think might have an error. Reenable the plugins one-by-one, restarting the plugins after you enable each plugin, to determine which plugin has an issue. For more information about troubleshooting plugins, see Troubleshooting Oracle Cloud Agent.

To stop all plugins on an instance:

Open the navigation menu and click Compute. Under Compute, click Instances.
Click the instance that you're interested in.
Click the Oracle Cloud Agent tab.
Click Stop plugins.

Caution

Functionality that depends on plugins, such as monitoring, autoscaling, and OS management, will not work when all plugins are stopped.
Click Stop plugins.

It might take several minutes for all plugins to stop. Oracle Cloud Agent continues to run when plugins are stopped.

To start all plugins on an instance

Open the navigation menu and click Compute. Under Compute, click Instances.
Click the instance that you're interested in.
Click the Oracle Cloud Agent tab.
Click Start plugins.

It takes up to 10 minutes for the plugins to restart.

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.

To see which version of Oracle Cloud Agent is installed

Connect to the instance and then do one of the following things:

For Oracle Linux and CentOS, run the following command:
```
sudo yum info oracle-cloud-agent
```
For Oracle Linux Cloud Developer, run the following command:
```
rpm -qa | grep oracle-cloud-agent
```
For Ubuntu, run the following command:
```
snap info oracle-cloud-agent
```

For Windows, do one of the following things:

In Control Panel, select Programs and Features and then find the version number provided for "Oracle Cloud Agent."

In PowerShell, run the following command:

Get-WmiObject -Class Win32_Product | Where-Object { $_.Name -eq "Oracle Cloud Agent" }

Example output:

IdentifyingNumber : {exampleuniqueidentifer}
Name              : Oracle Cloud Agent
Vendor            : Oracle Corporation
Version           : 0.0.10.0
Caption           : Oracle Cloud Agent

To manually update Oracle Cloud Agent on a compute instance

Do one of the following things:

Temporarily allow the instance to access the internet so that Oracle Cloud Agent can update itself.
Redo the installation steps, using the latest version.