On April 23, 2025, OS Management reaches end of life (EOL). Effective now, the service is no longer available to you in regions where you are not already using OS Management, or to new users with new tenancies. Before the EOL date, we recommend that you migrate your managed instances to the OS Management Hub service. If you are an Oracle Autonomous Linux user, see Important Maintenance Event. For more information, see the Service Change Announcement.

Oracle Cloud Infrastructure Documentation
Try Free Tier

Migrating OS Management Instances to OS Management Hub

Migrate OS Management instances to OS Management Hub by discovering the OS Management resources in use, creating the equivalent resources in OS Management Hub, and migrating instances.

OS Management Hub provides a migration assistant to help you successfully perform each stage of the migration. The migration assistant supports bulk discover, create, and migrate operations to streamline moving to OS Management Hub. Migration can also be done manually using the OCI Console on a per-instance basis.

Note

Effective April 23, 2025, the Oracle OS Management service reaches end of life (EOL). OS Management is replaced by OS Management Hub, which provides an improved user experience with new features, including patch deployments through lifecycle stages, enhanced job scheduling, and reporting capabilities.

Before the EOL date, we recommend that you migrate managed instances from OS Management to OS Management Hub.

Stages of Migration

Migrating from OS Management to OS Management Hub is a three stage process.

  • Discover: Examine your OS Management instances and determine the software sources, managed instance groups, and scheduled jobs you require for your managed instances and resolve incompatibility issues.
  • Create: Create the required resources in OS Management Hub using the information that you determined in discovery. Add vendor software sources and create custom software sources, create groups, and create registration profiles.
  • Migrate: Unregister your instances from OS Management and use a profile to register them with OS Management Hub.

Before You Begin

Before migrating OS Management instances to OS Management Hub, you must do the following:

Important

Registering an instance with OS Management Hub also gives you access to the migration assistant.

Required IAM Policy

To successfully migrate instances, you must have tenancy permissions for both OS Management and OS Management Hub. For more information, see Setting Up IAM Policies for OS Management and Required IAM Policy for OS Management Hub.

The migration assistant has additional policy requirements. To use the migration assistant, you need the following policy.

allow group group-name to inspect compartments in tenancy
allow group group-name to use tag-namespaces in tenancy
allow group group-name to use instances in tenancy
allow group group-name to inspect work-requests in tenancy
  • The first line allows the user group to list the compartments in the tenancy.
  • The second line allows the user group to update tag namespaces for resources in the tenancy. The migration assistant uses tags to track what resources have been migrated to OS Management Hub.
  • The third line allows the user group to list instances and update their tags to track migration status.
  • The fourth line allows the user group to monitor the status of the OS Management and OS Management Hub Oracle Cloud Agent plugins. The migration assistant uses this information to confirm that instance migrations are successful.

Migration Workflow

Use the following workflows for migrating OS Management instances to OS Management Hub depending on your use case:

Migrate a Single Instance Using the Console
  1. Set the required IAM policy, dynamic group, and user group for OS Management Hub.
  2. (Oracle Linux only) Identify all the vendor software sources in use by the instance and add the vendor software sources to OS Management Hub.
  3. (Oracle Linux only) Identify all the custom software sources in use by the instance, and create them in OS Management Hub.
  4. Select a profile to register the instance. If required, create a profile in OS Management Hub.
  5. Migrate the instance using the Console.
Migrate Instances in Bulk Using the Migration Assistant
  1. Set the required IAM policy, dynamic group, and user group for OS Management Hub.
  2. Register an instance with OS Management Hub and familiarize yourself with the service and how registration profiles work and get access to the migration assistant.
  3. Access and install the migration assistant utilities to help with the tasks required for migration.
  4. (Oracle Linux only) Identify all the vendor software sources in use by OS Management managed instances and add the vendor software sources to OS Management Hub.
  5. (Oracle Linux only) Identify all the custom software sources in use by OS Management managed instances, resolve incompatibility issues, and create them in OS Management Hub.
  6. Identify all the managed instance groups in OS Management, resolve incompatibility issues, and create the group resources in OS Management Hub.
  7. Identify managed instances, resolve incompatibility issues, and create profiles to register the instances with the OS Management Hub service.
  8. Migrate instances to OS Management Hub using the appropriate profile.

Migration Assistant

The migration assistant provides a set of utilities to assist you with each stage of migrating instances from OS Management to OS Management Hub. To install the migration assistant, see Installing the Migration Assistant.

Stage Migration Assistant Utilities
Discovery

Identify OS Management resources in use and highlight potential migration issues, such as incompatible software sources or managed instance groups. The utilities suggest how to remediate incompatibility issues found with a resource.

The following migration assistant utilities are available to identify OS Management resources in use:
Create

Create the required OS Management Hub resources needed to support your managed instances, including software sources, groups, scheduled jobs, and registration profiles.

The following migration assistant utilities are available to create OS Management Hub resources:
Migrate

Migrate instances from OS Management to OS Management Hub using an appropriate registration profile. The migration assistant also supports bulk migration of instances.

The following migration assistant utility is available to migrate instances:
Rollback

Return a managed instance to OS Management, if required.

The following migration assistant utility is available to rollback instances:

Installing the Migration Assistant

You can install the migration assistant using Oracle Cloud Infrastructure (OCI) Cloud Shell or using the Oracle Cloud Infrastructure (OCI) SDK on your system.

Before installing the migration assistant:

Install the migration assistant using one of the following methods:

Tip

For simplicity, we recommend that you use Cloud Shell to run the migration assistant.

Accessing the Migration Assistant

  1. Register an instance with OS Management Hub.
  2. Connect to the instance by using SSH.
  3. Navigate to the appropriate directory and copy the osms_to_osmh-<version>-py3-none-any.whl file:
    • Oracle Linux: /var/lib/oracle-cloud-agent/plugins/oci-osmh/osmh-agent/stateDir/osms_to_osmh-<version>-py3-none-any.whl
    • Windows 2016: C:\Users\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent\stateDir\osms_to_osmh-<version>-py3-none-any.whl
    • Windows 2019/2022: C:\Windows\ServiceProfiles\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent\stateDir\osms_to_osmh-<version>-py3-none-any.whl
    Note

    Use version 1.0.155 or later of the migration assistant to be compatible with the most recent updates to OS Management Hub.
  4. Install the migration using Cloud Shell or using the OCI SDK.

Using Cloud Shell

Before installing the migration assistant using Cloud Shell, ensure that the required IAM policy for using Cloud Shell and Cloud Shell Public Networking are set:

  1. Upload the osms_to_osmh-<version>-py3-none-any.whl file into Cloud Shell.
  2. Ensure the Cloud Shell Network is set to Public.
  3. Install the migration assistant in Cloud Shell. 
    /home/oci/lib/oracle-cli/bin/python3 -m pip install osms_to_osmh-<version>-py3-none-any.whl
  4. Create the required symbolic link to run the commands from your home directory in Cloud Shell. 
    ln -s /home/oci/lib/oracle-cli/bin/osms-to-osmh /home/oci/bin/osms-to-osmh

Using the OCI SDK

  1. Set up the required SSH keys to work with the OCI SDKs and developer toolkits and configure the SDKs.
    See Setup and Prerequisites in the Oracle Cloud Infrastructure Developer Guide.
  2. Upload the osms_to_osmh-<version>-py3-none-any.whl file to your system.
  3. Install the migration assistant on your system. 
    python -m pip install osms_to_osmh-<version>-py3-none-any.whl

Was this article helpful?