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.
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:
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: |
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:
- 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:
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
- Oracle Linux:
- 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.