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:

Review and understand OS Management Hub service.
Complete the getting started tasks for OS Management Hub.
Verify that your OS Management instances are using Oracle Cloud Agent version 1.40 or later before you migrate. OS Management Hub requires minimum Oracle Cloud Agent version 1.40.
Create a new OCI instance and register it with OS Management Hub to familiarize yourself with the service by performing these tasks:
1. (Oracle Linux only) Add vendor software sources.
2. Create a registration profile to register the instance.
3. Register the instance with OS Management Hub.

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:

If you are migrating a single OCI instance, migrate the OCI instance using the Console.
If you are migrating multiple OCI instances, migrate the instances in bulk using the migration assistant.

Migrate a Single Instance Using the Console

Set the required IAM policy, dynamic group, and user group for OS Management Hub.
(Oracle Linux only) Identify all the vendor software sources in use by the instance and add the vendor software sources to OS Management Hub.
(Oracle Linux only) Identify all the custom software sources in use by the instance, and create them in OS Management Hub.
Select a profile to register the instance. If required, create a profile in OS Management Hub.
Migrate the instance using the Console.

Migrate Instances in Bulk Using the Migration Assistant

Set the required IAM policy, dynamic group, and user group for OS Management Hub.
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.
Access and install the migration assistant utilities to help with the tasks required for migration.
(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.
(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.
Identify all the managed instance groups in OS Management, resolve incompatibility issues, and create the group resources in OS Management Hub.
Identify managed instances, resolve incompatibility issues, and create profiles to register the instances with the OS Management Hub service.
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: `osms-to-osmh discover vendor-software-source` `osms-to-osmh discover custom-software-source` `osms-to-osmh discover managed-instance-group` `osms-to-osmh discover managed-instance`
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: `osms-to-osmh create vendor-software-source` `osms-to-osmh create custom-software-source` `osms-to-osmh create managed-instance-group` `osms-to-osmh create profile`
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: `osms-to-osmh migrate managed-instance`
Rollback	Return a managed instance to OS Management, if required. The following migration assistant utility is available to rollback instances: `osms-to-osmh rollback managed-instance`

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:

Ensure your environment meets the following requirements:
- OCI SDK 2.126 or later.
- Python 3.8 or later. Use the python --version command to check the version on your system.
Download 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

Register an instance with OS Management Hub.
Connect to the instance by using SSH.
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.
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:

Required IAM policy to use Cloud Shell.
Required IAM policy for Cloud Shell managed Public Network to install the migration assistant utilities.

Upload the osms_to_osmh-<version>-py3-none-any.whl file into Cloud Shell.
Ensure the Cloud Shell Network is set to Public.

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

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

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.
Upload the osms_to_osmh-<version>-py3-none-any.whl file to your system.

Install the migration assistant on your system.

python -m pip install osms_to_osmh-<version>-py3-none-any.whl

Oracle Cloud Infrastructure Documentation