Oracle Cloud Infrastructure Documentation

Unregistering an Instance

Unregister an instance from OS Management Hub to no longer have it managed by the service.

Using the Console

  1. Review What happens to the instance when it's unregistered?
  2. For OCI instances, verify you have the required policy in place before unregistering.
  3. Open the navigation menu and select Observability & Management. Under OS Management Hub, select Instances.
  4. Under List scope, select the compartment that contains the instance.
  5. Select the name of the instance.
  6. (Optional) Review the instance's job history and reports. This information won't be available after you unregister the instance. See the following:
  7. Select Unregister.
  8. (Optional) For on-premises or third-party cloud instances, if you no longer need to use the Management Agent service, remove the mgmt_agent package.
    Oracle Linux 8 or 9
    sudo dnf remove oracle.mgmt_agent
    Oracle Linux 7
    sudo yum remove oracle.mgmt_agent

    To remove the corresponding Management Agent resource from the Management Agent Cloud Service (MACS) in OCI, see Remove Management Agents.

What happens to the instance when it's unregistered?

For Oracle Linux instances, unregistering restores the yum or dnf repository files to their state before the instance was registered with the service.

Unregistering an OCI instance without the required policy in place creates a blocker file (osmh-agent-unregister) to prevent the instance from automatically re-registering with the service. You must remove this file if you want to re-register the instance. See Troubleshooting: Instance was previously unregistered.

The blocker file is located at:

  • Oracle Linux

    /var/lib/oracle-cloud-agent/plugins/oci-osmh/osmh-agent-unregister

  • Windows 2019 and 2022

    C:\Windows\ServiceProfiles\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent-unregister

  • Windows 2016

    C:\Users\OCAOSMH\AppData\Local\OracleCloudAgent\plugins\oci-osmh\osmh-agent-unregister

Unregistering a non-OCI instance removes the OS Management Hub agent plugin from the instance. You can also optionally remove the Management Agent software from the system. If you don't remove the Management Agent and want to re-register the instance, you must manually deploy the OS Management Hub plugin. See Troubleshooting: Instance was previously unregistered.

Policy requirements for unregistering an OCI instance

Ensure you have one of the following policy statements in place before unregistering an OCI instance. Without the following policy, OS Management Hub creates a blocking file (osmh-agent-unregister) to prevent the instance from automatically re-registering with the service.

allow dynamic-group <dynamic-group> to use instance in compartment <compartment>

or

allow dynamic-group <dynamic-group> to {INSTANCE_UPDATE} in compartment <compartment>
With the policy:
  • OS Management Hub OCA plugin is disabled.
  • No registration blocker file is created.
  • You can re-register the instance by re-enabling the OS Management Hub OCA plugin.
Without the policy:
  • OS Management Hub OCA plugin remains enabled.
  • Registration blocker file (osmh-agent-unregister) is created to prevent the agent from checking in with the service.
  • To re-register the instance, you must manually remove the blocker file. See Troubleshooting: Instance was previously unregistered

What's the difference between unregistering and disabling the OCA plugin?

For OCI instances, disabling the OS Management Hub OCA plugin within the Compute service isn't the same as unregistering the instance. Although they have similar effects, unregistering removes the instance from the service, disabling the plugin causes the instance to remain in the service but stop checking in.

When unregistering an instance (either by using the Console or with the DeleteManagedInstance API operation):

  • The osmh-agent no longer checks in with the service.

  • The instance is removed from OS Management Hub.

  • If the required policy is in place, the OS Management Hub OCA plugin is disabled.

  • You will need to re-register the instance to use OS Management Hub again.

When disabling the OS Management Hub OCA plugin within the Compute service:

  • The osmh-agent no longer checks in with the service.

  • The instance remains in OS Management Hub. It will be in 'Inactive' and then 'Offline' state.

  • Re-enabling the plugin allows the instance to check in with OS Management Hub. You don't need to re-register to use OS Management Hub again.