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.

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.

Migration can be done using the OCI console. OS Management Hub also provides a migration assistant to help you successfully perform each stage of the migration. See Migration Assistant.

Before You Begin

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

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

Perform the following tasks to successfully migrate instances to OS Management Hub.

Register an instance with OS Management Hub and familiarize yourself with the service and how registration profiles work.
Download and install the migration assistant utilities to help with the tasks required for migration.
Identify all the vendor software sources in use by OS Management managed instances and add the vendor software sources to OS Management Hub.
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	Returns 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.

Downloading 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.whl file:
- Oracle Linux: /var/lib/oracle-cloud-agent/plugins/oci-osmh/osmh-agent/stateDir/osms_to_osmh.whl
- Windows 2016: C:\Users\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent\stateDir\osms_to_osmh.whl
- Windows 2019/2022: C:\Windows\ServiceProfiles\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent\stateDir\osms_to_osmh.whl

Rename the file to osms_to_osmh-1-py3-none-any.whl.

mv osms_to_osmh.whl osms_to_osmh-1-py3-none-any.whl

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-1-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-1-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-1-py3-none-any.whl file to your system.

Install the migration assistant on your system.

python -m pip install osms_to_osmh-1-py3-none-any.whl

Oracle Cloud Infrastructure Documentation