Oracle Cloud Infrastructure Documentation

Overview of OS Management

The Oracle Cloud Infrastructure OS Management service provides tools for common operating system management tasks for Compute instances, focusing initially on managing software packages for Oracle Linux instances.

The OS Management service is an agent-based service. The OS Management Service Agent (osms-agent) must be installed in instances in order for the service to operate.

The OS Management service enables you to monitor the packages installed on instances, to search for packages, to add or remove packages, and to update existing packages when updates become available.

A Compute instance that is managed by OS Management is referred to as a managed instance. A managed instance can be managed individually, or can be grouped for management activities. Instance groups enable you to manage instances according to your needs, for example to group instances by operating system or by their purpose, for example web servers. If you manage many instances, using instance groups is a powerful way of installing and updating packages, or managing software sources.

Note

To perform bulk operations, managed instances need to be grouped on an operational level and not a functional level. The performance of bulk operations is based on OS release and version and can only succeed if all managed instances selected for bulk operations have the same OS release and version.

Software Sources

OS Management uses software sources to provide packages to instances, and to track the available updates to those packages. A software source is simply a collection of packages. Software sources enable you to control which packages can be installed on instances without having to manually log in and configure the repositories on each instance.

As part of the OS Management service, standard software sources are provided in the root compartment of the tenancy. The standard software sources are linked to the standard upstream repositories for the operating system. When OS Management is enabled for an instance, the default software sources for the operating system are added to the instance. You can add or remove software sources as needed.

Software sources are either parent (or base) sources or child sources. An instance can only have one parent software source, but any number of child sources. The main software source for a Linux release is nominated as the parent software source and a number of child software sources are linked to the parent source. A child software source usually provides packages that are not available in the base software source.

In addition to the standard software sources, you can create your own custom software sources. Custom software sources can be derived from the standard software sources or other custom sources. Custom sources enable you to create specific sets of packages that you want to manage and apply to instances. You cannot upload your own packages to custom sources. You cannot use your own yum repositories with managed instances.

Work Requests and Scheduled Jobs

When you add, remove, or update packages on an instance or instance group, you have full control over when the action takes place.

If an action takes place immediately, the OS Management service creates a work request. Work requests enable you to track the progress of individual actions including the ability to see why an action failed. The OS Management service maintains a complete history of work requests on instances or instance groups.

If an action is to take place at a particular date and time, the OS Management service creates a scheduled job. There are two basic modes for scheduled jobs:

  • A scheduled job in which the job executes once.

  • A scheduled job in which the job executes repeatedly at a specified interval.

One-time schedule jobs are typically executed for tasks such as installing, updating, or removing a package (or a set of packages) because these tasks require that you specify the package version number. For these tasks, you typically do not want to repeat the action after the scheduled job is executed.

Recurring scheduled jobs are typically executed for tasks such as installing all available updates for a set of managed instances (or Managed instance groups) when the job executes. For example, you might create a scheduled job to install all security updates every week at a certain time.

When the scheduled date and time are reached, one or more work requests are created to perform the action. You have full control over scheduled jobs, to run them immediately, to delete them, or to skip a recurring job. The OS Management service maintains a complete history of scheduled jobs and their associated work requests.

Checking Exposure to Known Vulnerabilities

OS Management provides a search facility that you can use to check individual CVEs (Common Vulnerabilities and Exposures) to determine the level of exposure in your tenancy. CVEs provide standard names for publicly known security vulnerabilities and exposures that are cataloged in a dictionary-type format for reference. The CVE search facility enables you to search for a CVE, to see the packages and instances affected by the CVE, and to push out package updates to instances to patch them.

Getting Started with OS Management

The following sections describe how to get started with the OS Management service.

General Workflow for Setting Up Managed Instances

  1. Review the prerequisites for setting up managed instances. See Prerequisites for Setting Up Managed Instances.

  2. Set up your policies for the OS Management service.

  3. Enable OS Management on a new or existing instance. See Enabling the OS Management Service.

  4. Install the OS Management Service Agent, if required. See Installing the OS Management Service Agent in an Instance.

  5. Verify the status of the OS Management Service Agent. See Verifying the Status of the OS Management Service Agent.

Prerequisites for Setting Up Managed Instances

You must first set up the required OS Management policies. For more information about Identify Access and Management (IAM), see Overview of Oracle Cloud Infrastructure Identity and Access Management. If you are new to policies, see Getting Started with Policies and Common Policies.

You can only enable OS Management for Oracle Linux 6, 7, and 8 instances.

Important

  • You should not use the OS Management service with Autonomous Linux images at this time.

  • OS Management is not available as an Always Free service on the Oracle Cloud Free Tier. For more information about Always Free services, see Oracle Cloud Infrastructure's Free Tier.

You can only enable OS Management in a supported region.

To install the OS Management Service Agent on instances, you must have SSH access to the instance.

The instance must be attached to a virtual cloud network (VCN) that has one of the following:

  • A private subnet with a service gateway that uses the All <region> Services in Oracle Services Network CIDR label.

  • A private subnet with a NAT gateway.

  • A public subnet with an Internet gateway.

To validate whether your instance can reach the OS Management ingestion service:

curl https://ingestion.osms.<region>.oci.oraclecloud.com/

For <region>, specify the region identifier (for example, us-phoenix-1). See Region and Availability Domains for more information about region identifiers.

For example, the following sample output indicates that the instance could resolve the hostname and that it reached the server, but the server rejected the request because it did not include authorization information.

<html>
<head><title>403 Forbidden</title></head>
<body bgcolor="white">
<center><h1>403 Forbidden</h1></center>
<hr><center>nginx/1.14.2</center>
</body>
</html>

Creating a Policy to Allow Instances to Use the OS Management Service

For an instance to be registered with the OS Management service, you must first create policies that allow the instances to be managed by OS Management. For more information about setting up policies for the OS Management service, see Details for the OS Management Service

Note

The policies can be set at the tenancy or compartment level. You must have the required privileges to create the policy. If you do not have required privileges, you should work with the administrator for your tenancy to either obtain the privileges to create the policies or to have the policies created for you.

  1. Create a dynamic group that contains the set of instances to be managed by the OS Management service; for example, OsmsManagedInstance.

    For more information about creating dynamic groups, see Managing Dynamic Groups

  2. Add a rule defining the set of instances to be permitted in the policy.

    For example:

    ANY {instance.compartment.id = 'ocidv1:compartment:oc1:phx:exampleuniqueid', instance.compartment.id = 'ocidv1:compartment:oc1:phx:exampleuniqueid'}

    You can add one or more rules to define the instances to be permitted in the policy.

  3. Create a policy granting instances that are members of the dynamic group which you created in Step 1 access to the OS Management service.

    • For example, to create this policy in a tenancy:

      ALLOW dynamic-group <dynamic_group_name> to use osms-managed-instances in tenancy 
    • For example, to create this policy in a compartment inside the tenancy:

      ALLOW dynamic-group <dynamic_group_name> to use osms-managed-instances in compartment <compartment_name>
  4. Create a policy granting instances of that dynamic group permission to retrieve their details for authorization purposes.

    • For example, to create this policy in a tenancy:

      ALLOW dynamic-group <dynamic_group_name> to read instance-family in tenancy 
    • For example, to create this policy in a compartment inside the tenancy:

      ALLOW dynamic-group <dynamic_group_name> to read instance-family in compartment <compartment_name>

Creating a Policy to Allow the OS Management Service to Emit Metrics

For a managed instance to emit metrics, you must first create a policy to allow the OS Management service permission to read instance information in the tenancy.

For example:

ALLOW service osms to read instances in tenancy

For more information about metrics for OS Management, see OS Management Metrics.

Enabling the OS Management Service

When enabling OS Management on a new or existing Compute instance, Oracle Cloud Agent Management must be enabled.

  1. Enable Oracle Cloud Agent Management.

    • When creating a new Compute instance, ensure that the Use Oracle Cloud Agent to manage this instance checkbox is selected when creating the new Compute instance. For more information, see Creating an Instance.

    • To enable Oracle Cloud Agent Management to manage an existing Compute instance:

      1. Open the navigation menu. Under Core Infrastructure, go to Compute and click the existing instance to be enabled for Oracle Cloud Agent Management.

      2. In the Instance Information section, next to Oracle Cloud Agent Management: Disabled, click Enable.

  2. Perform one of the following procedures, depending on whether the OS Management Service Agent is installed on the image:

    Note

    The following Oracle Linux platform images include the OS Management Service Agent (osms-agent) installed on the image:

    • Oracle-Linux-6.10-2020.01.29-0 and later.

    • Oracle-Linux-7.7-2020.01.28-0 and later.

    For more information, see All Image Families.

Important

  • When registering with the OS Management service, the instance subscribes to the default channel list and all other channel subscriptions are disabled. If you need to reenable any of these channels, you can do so using the Console, CLI, or REST APIs.

  • When a Compute instance is first created in a new tenancy or region, it may take as long as 60 to 90 minutes before the instance is registered as a managed instance and the OS Management features are available. During this time, you may receive a message stating that the instance is not a managed instance.

Installing the OS Management Service Agent in an Instance

For Oracle Linux platform images that were released before January 29, 2020 (or if this instance uses a custom image), this procedure is required. For more information, see Enabling the OS Management Service

To install the OS Management Service Agent in an instance:

  1. Log in to your instance. See Connecting to an Instance.

  2. Install the OS Management Service Agent (osms-agent) package.

    # sudo yum install osms-agent

    Once the OS Management Service Agent software is installed, the default software sources for the OS are added to the instance. If you prefer, you can select the software sources you want to use.

    If the osms-agent package is not available, check to see if the oci_included channel is there and enabled. If it is not there, you must enable this channel.

    • For Oracle Linux 6:

      # sudo yum-config-manager --enable ol6_oci_included
      # cat /etc/yum.repos.d/oci-included-ol6.repo
      [ol6_oci_included]
      name=Oracle Software for OCI users on Oracle Linux $releasever ($basearch)
      baseurl=http://yum$ociregion.oracle.com/repo/OracleLinux/OL6/oci/included/$basearch/
      gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
      gpgcheck=1
    • For Oracle Linux 7:

      # sudo yum-config-manager --enable ol7_oci_included
      # cat /etc/yum.repos.d/oci-included-ol7.repo
      [ol7_oci_included]
      name=Oracle Software for OCI users on Oracle Linux $releasever ($basearch)
      baseurl=http://yum$ociregion.oracle.com/repo/OracleLinux/OL7/oci/included/$basearch/
      gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
      gpgcheck=1
    • For Oracle Linux 8:

      # sudo dnf-config-manager --enable ol8_oci_included
      # cat /etc/yum.repos.d/oci-included-ol8.repo
      [ol8_oci_included]
      name=Oracle Software for OCI users on Oracle Linux $releasever ($basearch)
      baseurl=http://yum$ociregion.oracle.com/repo/OracleLinux/OL8/oci/included/$basearch/
      gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle
      gpgcheck=1
    Important

    When you install the OS Management Service Agent, the existing yum repository configuration is disabled and the *.repo files in the /etc/yum.repos.d directory are backed up to *.repo.osms-backup in the same directory.

Proceed to Verifying the Status of the OS Management Service Agent.

Verifying the Status of the OS Management Service Agent

To verify the status of the OS Management Service Agent on the instance:

  1. Log in to your instance. See Connecting to an Instance.

  2. Verify the yum configuration by checking that the existing yum repository configuration is disabled and the *.repo files in the /etc/yum.repos.d directory are backed up to *.repo.osms-backup in the same directory.

    For example:

    # ls /etc/yum.repos.d
    ksplice-ol7.repo.osms-backup                oracle-linux-ol7.repo.osms-backup
    ksplice-uptrack.repo.osms-backup            oracle-softwarecollection-ol7.repo.osms-backup
    oci-included-ol7.repo.osms-backup           uek-ol7.repo.osms-backup
    oracle-epel-ol7.repo.osms-backup            virt-ol7.repo.osms-backup
    oraclelinux-developer-ol7.repo.osms-backup
  3. Verify the status is active (running).

    • For Oracle Linux 6, run the sudo initctl status osms-agent command.

    • For Oracle Linux 7 and 8, run the sudo systemctl status osms-agent command.

      For example:

      # sudo systemctl status osms-agent
      osms-agent.service - OS Management Service Agent
          Loaded: loaded (/etc/systemd/system/osms-agent.service; enabled; 
      vendor preset: disabled)
          Active: active (running) since Mon 2019-12-16 05:27:06 GMT; 2 
      days ago
            Docs: https://docs.cloud.oracle.com/iaas/
        Main PID: 11728 (osms-agent)
          CGroup: /system.slice/osms-agent.service
                  11728 /usr/libexec/osms-agent/osms-agent
                  11729 /usr/libexec/osms-agent/osms-agent
      
      Note

      When the OS Management Service Agent is active, the following line displays in the output of commands such as sudo yum repolist: This system is receiving updates from OSMS.

To verify the status of the OS Management Service Agent using the Console:

  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.

  2. Find the instance and click its name.

  3. On the instance detail page, under Resources, click OS Management.

    When the OS Management Service Agent is installed, the OS Management section displays information about available updates, scheduled jobs, work requests, and so on.

    When the OS Management is not installed, the OS Management section displays a message indicating that no OS Management information is available for this resource, that OS Management must be enabled, and that the OS Management Agent Service (osms-agent) must be installed from yum, if the instance is using a platform image that predates the OS Management service.

Once the OS Management Service Agent is active (running), you have completed the getting started tasks for setting up managed instances. Proceed to Using the Console.

Disabling the OS Management Service Agent in an Instance

You can perform the following procedure to disable the OS Management Service Agent in an instance and revert the yum configuration files back to their state prior to the OS Management service being enabled.

Note

Follow the steps listed in this procedure in order. For example, if you do not stop the agent before restoring the yum configuration (sudo osms unregister), the Agent automatically registers again.

Important

Do not uninstall the OS Management Service Agent prior to performing this procedure. Because some of the commands required for this procedure are available only with the OS Management Service Agent (osms-agent) RPM package (such as the osms unregister command), uninstalling this package prevents you from performing the procedure. If you have uninstalled the osms-agent package, then you have to manually revert the repository files under /etc/yum.repos.d/*.osms-backup back to their prior state.

  1. Stop the OS Management Service Agent.

    • For Oracle Linux 6, run the sudo initctl stop osms-agent command.

    • For Oracle Linux 7 and 8, run the sudo systemctl stop osms-agent command.

    For example:

    # sudo systemctl stop osms-agent
    # sudo systemctl status osms-agent
      osms-agent.service - OS Management Service Agent
       Loaded: loaded (/etc/systemd/system/osms-agent.service; enabled; vendor preset: disabled)
       Active: inactive (dead) since Tue 2020-01-28 15:35:16 GMT; 1min 9s ago
         Docs: https://docs.cloud.oracle.com/iaas/
      Process: 8195 ExecStart=/usr/libexec/osms-agent/osms-agent (code=exited, status=0/SUCCESS)
     Main PID: 8195 (code=exited, status=0/SUCCESS)
    
    Jan 28 15:35:00 ol7-test2 systemd[1]: Started OS Management Service Agent.
    Jan 28 15:35:01 ol7-test2 osms-agent[8195]: 1|1|unix|/var/lib/osms-agent/osms-agent.sock|grpc
    Jan 28 15:35:15 ol7-test2 systemd[1]: Stopping OS Management Service Agent...
    Jan 28 15:35:16 ol7-test2 systemd[1]: Stopped OS Management Service Agent.
  2. Remove the managed instance from any managed instance groups in the Console (if applicable).

    If you have any scheduled jobs for this instance, you should also delete them.

  3. Revert the yum configuration files back to the state prior to the OS Management service being enabled.

    # sudo osms unregister
    Note

    After executing this command, the OS Management Service Agent is disabled for the instance and the yum repository is restored. In effect, the OS Management service is no longer managing the instance; however, the OS Management service is not completely disabled on the backend. As a result, in the Console, the Instance Information section still displays Oracle Cloud Agent Management: Enabled for the instance and under Resources the OS Management section still displays the latest status of the inventory for the instance.

  4. Verify that the yum configuration has been restored.

    For example:

    # ls /etc/yum.repos.d
    ksplice-ol7.repo       oracle-epel-ol7.repo            oracle-softwarecollection-ol7.repo
    ksplice-uptrack.repo   oraclelinux-developer-ol7.repo  uek-ol7.repo
    oci-included-ol7.repo  oracle-linux-ol7.repo           virt-ol7.repo
Tip

If you need to reenable the OS Management Service Agent, you can simply restart the Agent.

  • For Oracle Linux 6, run the sudo initctl start osms-agent command.

  • For Oracle Linux 7 and 8, run the sudo systemctl start osms-agent command.

Using the Console

To access the Console, you must use a supported browser.

You can perform basic administrative tasks for OS Management in the Oracle Cloud Infrastructure Console, including:

  • Creating managed instances and groups

  • Selecting software sources

  • Searching for packages

  • Checking for exposures to known CVEs

  • Installing, updating, and removing packages

  • Creating custom software sources

You can also use the Console to view alarms and metrics. For more information, see Using the Console.

To create a managed instance group
To add managed instances to a managed instance group
To select software sources for a managed instance
To select software sources for a managed instance group
To check the status of a managed instance
To search for packages
To install packages on a managed instance
To remove packages from a managed instance
To update packages on a managed instance
To install new packages on a managed instance group
To remove packages from a managed instance group
To update packages from a managed instance group
To check exposure to known vulnerabilities
To create a custom software source
To select packages for a custom software source
To delete a custom software source
To manage scheduled jobs

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use these API operations for working with managed instances and managed instance groups:

Details for the OS Management Service

This topic covers details for writing policies to control access to the OS Management service.

About Permissions for Managed Instances

Because a managed instance is a Compute Instance that is actively being managed by the OS Management service, all operations that operate on managed instaces require that users have read permission on the underlying Compute instance. A managed instance, moreover, does not have a separate Oracle Cloud ID (OCID). To determine which Compute instances are available to users, calls are made to the Compute service to retrieve the instance information. If you do not have read access to the Compute instance details, then you are not able to manage that Compute instance with the OS Management service.

About Permissions for Software Sources

The default set of software sources is created in the root compartment. To read those software sources, users must be granted read permissions.

The permissions on software sources in the root compartment should be restricted to prevent users from accidentally deleting or removing these packages. These packages are intended to be used as is or as the basis for creating customized software sources, but should not be modified directly.

When creating a software source, it can only be populated with packages from existing software sources that the user has permissions to access. If you want to limit the packages that can be used, you can create a new software source in a different compartment (or with a policy granting different permissions) and populate that new software source with only the packages that you want users to be able to use.

Compartment Considerations

If you would like the OS Management service to manage all instances in your tenancy, then you should set the policies at the root compartment level; however, if you would like the OS Management service to manage only a subset of your instances, which are in a compartment or its sub-compartments, then you could consider creating the policy at that compartment level. Setting policies at the root compartment level is the simplest way to create OS Management service policies but is also dependent on what polices are allowed by the administrator of your tenancy.

All the base software sources are in the root compartment. When setting policies, ensure that the permissions for the policy are not too narrow or the user may run into authorization errors when trying to install packages or updates from root compartment software sources if the user only has subcompartment access.

For example:

 ALLOW group group-name to manage osms-family in compartment ABC

To ensure the user has proper access, the user must be granted OSMS_SOFTWARE_SOURCE_READ permissions in the root compartment.

Resources

Aggregate Resource-Type

  • osms-family

Individual Resource Types

  • osms-managed-instances

  • osms-managed-instance-groups

  • osms-software-sources

  • osms-errata

  • osms-scheduled-jobs

  • osms-work-requests

Details for Verb and Resource-Type Combinations

Oracle Cloud Infrastructure offers a standard set of verbs to define permissions across Oracle Cloud Infrastructure resources (Inspect, Read, Use, Manage). These tables list the OS Management service permissions associated with each verb. The level of access is cumulative as you go from Inspect to Read to Use to Manage.

INSPECT

Resource- Type INSPECT Permission
  • osms-managed-instances

  • OSMS_MANAGED_INSTANCE_INSPECT

  • osms-managed-instance-groups

  • OSMS_MANAGED_INSTANCE_GROUP_INSPECT

  • osms-software-sources

  • OSMS_SOFTWARE_SOURCE_INSPECT

  • osms-errata

  • OSMS_ERRATA_INSPECT

  • osms-scheduled-jobs

  • OSMS_SCHEDULED_JOB_INSPECT

  • osms-work-requests

  • OSMS_WORK_REQUEST_INSPECT

READ

Resource- Type READ Permission
  • osms-managed-instances

  • OSMS_MANAGED_INSTANCE_READ

  • osms-managed-instance-groups

  • OSMS_MANAGED_INSTANCE_GROUP_READ

  • osms-software-sources

  • OSMS_SOFTWARE_SOURCE_READ

  • osms-errata

  • OSMS_ERRATA_READ

  • osms-scheduled-jobs

  • OSMS_SCHEDULED_JOB_READ

  • osms-work-requests

  • OSMS_WORK_REQUEST_READ

USE

Resource- Type USE Permission
  • osms-managed-instances

  • OSMS_MANANGED_INSTANCE_ACCESS

  • osms-managed-instance-groups

  • OSMS_MANAGED_INSTANCE_GROUP_INSTALL_UPDATE

  • OSMS_MANAGED_INSTANCE_GROUP_INSTALL_PACKAGE

  • OSMS_MANAGED_INSTANCE_GROUP_REMOVE_PACKAGE

  • OSMS_MANAGED_INSTANCE_GROUP_UPDATE

  • osms-software-sources

  • OSMS_SOFTWARE_SOURCE_UPDATE

  • osms-errata

  • N/A

  • osms-scheduled-jobs

  • OSMS_SCHEDULED_JOB_UPDATE

  • osms-work-requests

  • N/A

MANAGE

Resource- Type MANAGE Permission
  • osms-managed-instances

  • OSMS_MANAGED_INSTANCE_UPDATE

  • OSMS_MANAGED_INSTANCE_INSTALL_UPDATE

  • OSMS_MANAGED_INSTANCE_INSTALL_PACKAGE

  • OSMS_MANAGED_INSTANCE_REMOVE_PACKAGE

  • OSMS_MANAGED_INSTANCE_ADD_SOFTWARE_SOURCE

  • OSMS_MANAGED_INSTANCE_REMOVE_SOFTWARE_SOURCE

  • osms-managed-instance-groups

  • OSMS_MANAGED_INSTANCE_GROUP_ADD_INSTANCE

  • OSMS_MANAGED_INSTANCE_GROUP_REMOVE_INSTANCE

  • OSMS_MANAGED_INSTANCE_GROUP_CREATE

  • OSMS_MANAGED_INSTANCE_GROUP_DELETE

  • OSMS_MANAGED_INSTANCE_GROUP_MOVE

  • OSMS_MANAGED_INSTANCE_GROUP_ADD_SOFTWARE_SOURCE

  • OSMS_MANAGED_INSTANCE_GROUP_REMOVE_SOFTWARE_SOURCE

  • osms-software-sources

  • OSMS_SOFTWARE_SOURCE_CREATE

  • OSMS_SOFTWARE_SOURCE_DELETE

  • OSMS_SOFTWARE_SOURCE_MOVE

  • OSMS_SOFTWARE_SOURCE_ADD_PACKAGES

  • OSMS_SOFTWARE_SOURCE_REMOVE_PACKAGES

  • osms-errata

  • N/A

  • osms-scheduled-jobs

  • OSMS_SCHEDULED_JOB_CREATE

  • OSMS_SCHEDULED_JOB_DELETE

  • OSMS_SCHEDULED_JOB_MOVE

  • osms-work-requests

  • OSMS_WORK_REQUEST_CANCEL

Permissions Required for Each API Operation

The following table lists the API operations in a logical order, grouped by resource type. For information about permissions, see Permissions.

API Operation Permissions Required to Use the Operation
ListManagedInstances OSMS_MANAGED_INSTANCE_INSPECT
GetManagedInstance OSMS_MANAGED_INSTANCE_READ
ListPackagesInstalledOnManagedInstance OSMS_MANAGED_INSTANCE_READ
ListAvailablePackagesForManagedInstance OSMS_MANAGED_INSTANCE_READ
ListAvailableUpdatesForManagedInstance OSMS_MANAGED_INSTANCE_READ
ListAvailableSoftwareSourcesForManagedInstance OSMS_MANAGED_INSTANCE_READ and OSMS_SOFTWARE_SOURCE_INSPECT
InstallPackageOnManagedInstance OSMS_MANAGED_INSTANCE_INSTALL_PACKAGE and OSMS_SOFTWARE_SOURCE_READ
RemovePackageFromManagedInstance OSMS_MANAGED_INSTANCE_REMOVE_PACKAGE
InstallPackageUpdateOnManagedInstance OSMS_MANAGED_INSTANCE_INSTALL_UPDATE and OSMS_SOFTWARE_SOURCE_READ
AttachParentSoftwareSourceToManagedInstance OSMS_MANAGED_INSTANCE_ADD_SOFTWARE_SOURCE and OSMS_SOFTWARE_SOURCE_READ
AttachChildSoftwareSourceToManagedInstance OSMS_MANAGED_INSTANCE_ADD_SOFTWARE_SOURCE and OSMS_SOFTWARE_SOURCE_READ
DetachParentSoftwareSourceFromManagedInstance OSMS_MANAGED_INSTANCE_REMOVE_SOFTWARE_SOURCE
DetachChildSoftwareSourceFromManagedInstance OSMS_MANAGED_INSTANCE_REMOVE_SOFTWARE_SOURCE
ListManagedInstanceGroups OSMS_MANAGED_INSTANCE_GROUP_INSPECT
GetManagedInstanceGroup OSMS_MANAGED_INSTANCE_GROUP_READ
UpdateManagedInstanceGroup OSMS_MANAGED_INSTANCE_GROUP_UPDATE
CreateManagedInstanceGroup OSMS_MANAGED_INSTANCE_GROUP_CREATE
DeleteManagedInstanceGroup OSMS_MANAGED_INSTANCE_GROUP_DELETE
ChangeManagedInstanceGroupComparment OSMS_MANAGED_INSTANCE_GROUP_MOVE
AttachManagedInstanceToManagedInstanceGroup OSMS_MANAGED_INSTANCE_GROUP_ADD_INSTANCE and OSMS_MANAGED_INSTANCE_UPDATE
DetachManagedInstanceFromManagedInstanceGroup OSMS_MANAGED_INSTANCE_GROUP_REMOVE_INSTANCE and OSMS_MANAGED_INSTANCE_UPDATE
ListSoftwareSources OSMS_SOFTWARE_SOURCE_INSPECT
GetSoftwareSource OSMS_SOFTWARE_SOURCE_READ
UpdateSoftwareSource OSMS_SOFTWARE_SOURCE_UPDATE
CreateSoftwareSource OSMS_SOFTWARE_SOURCE_CREATE
DeleteSoftwareSource OSMS_SOFTWARE_SOURCE_DELETE
ChangeSoftwareSourceCompartment OSMS_SOFTWARE_SOURCE_MOVE
AddPackagesToSoftwareSource OSMS_SOFTWARE_SOURCE_ADD_PACKAGES
RemovePackagesFromSoftwareSource OSMS_SOFTWARE_SOURCE_REMOVE_PACKAGES
ListSoftwarePackages OSMS_SOFTWARE_SOURCE_READ
GetSoftwarePackage OSMS_SOFTWARE_SOURCE_READ
SearchSoftwarePackages OSMS_SOFTWARE_SOURCE_READ
ChangeSoftwareSourceComparment OSMS_SOFTWARE_SOURCE_MOVE
ListScheduledJobs OSMS_SCHEDULED_JOB_INSPECT
GetScheduledJob OSMS_SCHEDULED_JOB_READ
UpdateScheduledJob OSMS_SCHEDULED_JOB_UPDATE
CreateScheduledJob

OSMS_SCHEDULED_JOB_CREATE and one or more of the following permissions:

  • OSMS_MANAGED_INSTANCE_GROUP_INSTALL_PACKAGE and OSMS_SOFTWARE_SOURCE_READ

  • OSMS_MANAGED_INSTANCE_GROUP_INSTALL_UPDATE and OSMS_SOFTWARE_SOURCE_READ

  • OSMS_MANAGED_INSTANCE_GROUP_REMOVE_PACKAGE

  • OSMS_MANAGED_INSTANCE_INSTALL_PACKAGE and OSMS_SOFTWARE_SOURCE_READ

  • OSMS_MANAGED_INSTANCE_INSTALL_UPDATE and OSMS_SOFTWARE_SOURCE_READ

  • OSMS_MANAGED_INSTANCE_REMOVE_PACKAGE

DeleteScheduledJob OSMS_SCHEDULED_JOB_DELETE
ChangeScheduledJobCompartment OSMS_SCHEDULED_JOB_MOVE
ListWorkRequests OSMS_WORK_REQUEST_INSPECT
GetWorkRequest OSMS_WORK_REQUEST_READ
CancelWorkRequest OSMS_WORK_REQUEST_CANCEL

OS Management Metrics

You can monitor the health, capacity, and performance of your managed instances by using (Monitoring service) A measurement related to health, capacity, or performance of a given resource. Example: CpuUtilization, The trigger rule and query to evaluate and related configuration, such as notification details to use when the trigger is breached. Alarms passively monitor your cloud resources using metrics in Monitoring., and Notifications.

You must first create a policy that allows instances to emit metrics. For more information, see Creating a Policy to Allow Instances to Emit Metrics.

This topic describes the metrics emitted by the OS Management service in the oci_osms metric namespace.

Resources: managed instances.

Overview of Metrics for an Instance and Related Resources

The OS Management service metrics help you measure the number of active and inactive managed instances, the number of managed instances with available security updates, and the number of managed instances with available updates.

Prerequisites

  • IAM policies: To monitor resources, you must be given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. The policy must give you access to the monitoring services and the resources being monitored. If you try to perform an action and get a message that you don't have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. For more information on user authorizations for monitoring, see the Authentication and Authorization section for the related service: Monitoring or Notifications.
  • The metrics listed on this page are automatically available for any managed instance you create. You do not need to enable monitoring on the resource to get these metrics.

Available Metrics: oci_osms

OS Management service metrics include the following (Monitoring service) A qualifier provided in a metric definition. Example: Resource identifier (resourceId), provided in the definitions of oci_computeagent metrics.:

resourceId
The An Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID). This ID is included as part of the resource's information in both the Console and API for the tenancy.
Metric Metric Display Name Unit Interval Description Dimensions
ActiveManagedInstances Active Managed Instances Mean 1 hour Number of active managed instances.

resourceId

InactiveManagedInstances Inactive Managed Instances Mean 1 hour Number of inactive managed instances.
UnsecuredManagedInstances Unsecured Managed Instances Mean 1 hour Number of managed instances with available security updates.
UpdatableManagedInstances Updatable Managed Instances Mean 1 hour Number of managed instances with available updates.

Using the API

Use the following APIs for monitoring:

Using the Console

To view metrics and alarms

Creating Automation with Events

You can create automation based on state changes for your Oracle Cloud Infrastructure resources by using event types, rules, and actions. For more information, see Overview of Events.

OS Management resources that emit events:

Events are also emitted for other OS Management service resources, such as Errata and WorkRequest resources. No event schemas, however, are defined for these resources because only list and get operations can be performed on them.

Managed Instance Event Types

These are the event types that the managed instance resource emits:

Friendly Name Event Type
Attach Child Software Source
com.oraclecloud.osms.attachchildsoftwaresourcetomanagedinstance
Attach Parent Software Source
com.oraclecloud.osms.attachparentsoftwaresourcetomanagedinstance
Detach Child Software Source
com.oraclecloud.osms.detachchildsoftwaresourcefrommanagedinstance
Detach Parent Software Source
com.oraclecloud.osms.detachparentsoftwaresourcefrommanagedinstance
Install All Package Updates
com.oraclecloud.osms.installallpackageupdatesonmanagedinstance
Install Package
com.oraclecloud.osms.installpackageonmanagedinstance
Install Package Update
com.oraclecloud.osms.installpackageupdateonmanagedinstance
Remove Package
com.oraclecloud.osms.removepackagefrommanagedinstance

Managed Instance Example

This is a reference event for managed instance:

{
    "eventType": "com.oraclecloud.osms.installallpackageupdatesonmanagedinstance",
    "cloudEventsVersion": "0.1",
    "eventTypeVersion": "2.0",
    "eventID": "<unique_ID>",
    "source": "OSMS",
    "eventTime": "2019-10-16T19:16:38.543Z",
    "contentType": "application/json",
    "extensions": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>"
    },
    "data": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>",
      "compartmentName": "example_compartment",
      "resourceName": "example_name",
      "resourceId": "ocid1.instance.oc1.phx.<unique_ID>",
      "availabilityDomain": "<availability_domain>",
      "additionalDetails": {
        "softwarePackageName": "example_packageName"
      }
    }
  },
 

Managed Instance Group Event Types

These are the event types that managed instance group resource emits:

Friendly Name Event Type
Attach Managed Instance
com.oraclecloud.osms.attachmanagedinstancetomanagedinstancegroup
Change Compartment
com.oraclecloud.osms.changemanagedinstancegroupcompartment
Create
com.oraclecloud.osms.createmanagedinstancegroup
Delete
com.oraclecloud.osms.deletemanagedinstancegroup
Detach Managed Instance
com.oraclecloud.osms.detachmanagedinstancefrommanagedinstancegroup
Update
com.oraclecloud.osms.updatemanagedinstancegroup

Managed Instance Group Example

This is a reference event for managed instance groups:

{
    "eventType": "com.oraclecloud.osms.createmanagedinstancegroup",
    "cloudEventsVersion": "0.1",
    "eventTypeVersion": "2.0",
    "eventID": "<unique_ID>",
    "source": "OSMS",
    "eventTime": "2019-10-16T19:16:38.543Z",
    "contentType": "application/json",
    "extensions": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>"
    },
    "data": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>D",
      "compartmentName": "example_compartment",
      "resourceName": "example_name",
      "resourceId": "ocid1.osmsmanagedinstancegroup.realm_name.<unique_ID>",
      "availabilityDomain": "<availability_domain>",
      "freeFormTags": {
        "example_tag": "value"
      },
      "definedTags": {
        "example_tag": {
          "example_tag": "value"
        }
      }
    }
  },
 

Scheduled Job Event Types

These are the event types that the scheduled job resource emits:

Friendly Name Event Type
Change Compartment
com.oraclecloud.osms.changescheduledjobcompartment
Create
com.oraclecloud.osms.createscheduledjob
Delete
com.oraclecloud.osms.deletescheduledjob
Run Now
com.oraclecloud.osms.runscheduledjobnow
Skip Next Execution
com.oraclecloud.osms.skipnextscheduledjobexecution
Update
com.oraclecloud.osms.updatescheduledjob

Scheduled Job Example

This is a reference event for scheduled jobs:

{
    "eventType": "com.oraclecloud.osms.createscheduledjob",
    "cloudEventsVersion": "0.1",
    "eventTypeVersion": "2.0",
    "eventID": "<unique_ID>",
    "source": "OSMS",
    "eventTime": "2019-10-16T19:16:38.543Z",
    "contentType": "application/json",
    "extensions": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>"
    },
    "data": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>",
      "compartmentName": "example_compartment",
      "resourceName": "example_name",
      "resourceId": "ocid1.osmsscheduledjob.realm_name.<unique_ID>",
      "availabilityDomain": "<availability_domain>",
      "freeFormTags": {
        "example_tag": "value"
      },
      "definedTags": {
        "example_tag": {
          "example_tag": "value"
        }
      }
    }
  },
 

Software Source Event Types

These are the event types that the software source resource emits:

Friendly Name Event Type
Add Packages
com.oraclecloud.osms.addpackagestosoftwaresource
Change Compartment
com.oraclecloud.osms.changesoftwaresourcecompartment
Create
com.oraclecloud.osms.createsoftwaresource
Delete
com.oraclecloud.osms.deletesoftwaresource
Remove Packages
com.oraclecloud.osms.removepackagesfromsoftwaresource
Update
com.oraclecloud.osms.updatesoftwaresource

Software Source Example

This is a reference event for software sources:

{
    "eventType": "com.oraclecloud.osms.updatesoftwaresource",
    "cloudEventsVersion": "0.1",
    "eventTypeVersion": "2.0",
    "eventID": "<unique_ID>",
    "source": "OSMS",
    "eventTime": "2019-10-17T13:35:50.676Z",
    "contentType": "application/json",
    "extensions": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>"
    },
    "data": {
      "compartmentId": "ocid1.compartment.oc1..<unique_ID>",
      "compartmentName": "example_compartment",
      "resourceName": "Test Software Source",
      "resourceId": "ocid1.osmssoftwaresource.realm_name.<unique_ID>",
      "availabilityDomain": "<availability_domain>",
      "freeFormTags": {
        "test_tag_2": "testgroup"
      },
      "definedTags": {
        "osms_tag_test": {
          "test_tag_2": "testgroup"
        }
      }
    }
  },