Home / OCI

OCIRunbookIntermediate

OCI instance maintenance events: find scheduled reboot migrations, reschedule them and avoid surprise downtime

List upcoming OCI compute maintenance events, move the reboot window to a time you choose, prefer live migration and alert on new events before they cause downtime.

Deepak Bhardwaj7 min read

Applies toOCI Compute (VM and bare metal instances), Instance Maintenance, OCI Search, OCI Monitoring, OCI CLI 3.x

Goal

You got a notification that a production instance is due for "scheduled maintenance", or worse, an instance rebooted overnight and nobody knew why. OCI moves instances off unhealthy or retiring hosts. Most moves are invisible, but some need a reboot, and if you don't act Oracle picks the time.

This runbook does four things: find every pending maintenance event, decide what it will do to the instance, move it to your change window, and make sure the next one doesn't surprise you.

How OCI maintenance works

Action Downtime What happens
Live migration None (a pause of tens of milliseconds) The running VM moves to a healthy host
Reboot migration (scheduled maintenance) Short: a stop and start The instance stops, moves to a healthy host and starts again
Rebuild in place Long Mostly bare metal: the host is repaired with the instance on it
Manual migration Depends on you You move the workload yourself, for example from a backup or by relaunching

Each event has a time window. If the instance hasn't been handled by the end of the due date, Oracle performs the action itself. For a VM, the reboot happens within 24 hours of the due time.

Warning

Reboot migration is a real stop and start. Anything not persisted is lost: tmpfs, process state, and data on local NVMe of DenseIO shapes unless the event says local storage is preserved. Check that volumes remount after a reboot (/etc/fstab with _netdev,nofail for iSCSI volumes) before the window.

1. Find pending maintenance events

OCI Search is the fastest way to see everything scheduled, in any compartment:

oci search resource structured-search \
  --query-text "query instancemaintenanceevent resources where (timeWindowStart > 'Now' && lifecycleState = 'SCHEDULED')" \
  --query 'data.items[].{name:"display-name",id:identifier,compartment:"compartment-id"}' \
  --output table

Run it in every subscribed region; Search is regional.

Per compartment with the CLI

C=ocid1.compartment.oc1..example

oci compute instance-maintenance-event list \
  --compartment-id "$C" --all \
  --lifecycle-state SCHEDULED \
  --query 'data[].{id:id,instance:"instance-id",action:"instance-action",reason:"maintenance-reason",start:"time-window-start"}' \
  --output table

Useful filters: --instance-id for one instance, and --time-window-start-less-than-or-equal-to 2026-11-10T00:00:00Z for "what hits us this week". Lifecycle states are SCHEDULED, STARTED, PROCESSING, SUCCEEDED, FAILED and CANCELED.

Read the details of one event

oci compute instance-maintenance-event get \
  --instance-maintenance-event-id ocid1.instancemaintenanceevent.oc1..example

Look at:

  • instance-action: what will happen to the instance.
  • maintenance-category / maintenance-reason: planned (hardware refresh, firmware) or unplanned (host fault). Unplanned events usually have short windows.
  • time-window-start and time-window-end: when it can happen.
  • can-reschedule: whether you can move it.
  • alternative-resolution-actions: what you can choose instead (for example REBOOT_MIGRATION or TERMINATE).
  • can-delete-local-storage / local storage fields: whether local NVMe data survives.

Field names in the JSON output vary slightly by CLI version; check your build's output.

2. Decide what to do

Situation Action
Event is live migration, app tolerates a brief pause Nothing. Note it in the change log
Reboot migration on a single, stateful instance Reschedule into the change window, notify owners
Reboot migration on a node behind a load balancer Drain the backend, let it run (or trigger it early), re-enable
Database or cluster node (RAC, Data Guard, Kafka, etcd) Fail over or relocate services first, one node at a time
Bare metal with local NVMe data Copy data off, or confirm the event preserves it, before acting
Instance you were going to rebuild anyway Use the alternative action TERMINATE and relaunch from IaC

3. Move the window or run it now

Reschedule the event

If can-reschedule is true, set a new start time inside the allowed range:

oci compute instance-maintenance-event update \
  --instance-maintenance-event-id ocid1.instancemaintenanceevent.oc1..example \
  --time-window-start 2026-11-08T02:00:00Z

The end of the window is calculated for you from the reason and the action. If the new time is past the latest allowed date, the call fails; pick an earlier time.

Older VM workflow: reboot due date

Some VMs show a time-maintenance-reboot-due on the instance itself instead of, or as well as, an event. You can move it within the allowed range:

oci compute instance update \
  --instance-id ocid1.instance.oc1..example \
  --time-maintenance-reboot-due 2026-11-08T02:00:00Z

The field clears as soon as the instance reaches STOPPED, which is why a planned stop and start during your window counts as doing the maintenance.

Run it now, on your terms

During your window, drain the instance, then either use Reboot now on the maintenance event in the Console, or stop and start the instance:

oci compute instance action --instance-id ocid1.instance.oc1..example --action SOFTSTOP --wait-for-state STOPPED
oci compute instance action --instance-id ocid1.instance.oc1..example --action START --wait-for-state RUNNING

A plain SOFTRESET (in-place reboot) does not move the instance to a new host. Use stop and start, or the event's own action.

To choose the alternative resolution instead (for example on a bare metal host with local storage you don't need):

oci compute instance-maintenance-event update \
  --instance-maintenance-event-id ocid1.instancemaintenanceevent.oc1..example \
  --alternative-resolution-action REBOOT_MIGRATION \
  --can-delete-local-storage true

Caution

--can-delete-local-storage true means exactly that: data on local NVMe is gone after the move. TERMINATE deletes the instance. Only use either after the data is copied or the node is disposable.

Verify afterwards

oci compute instance-maintenance-event get \
  --instance-maintenance-event-id ocid1.instancemaintenanceevent.oc1..example \
  --query 'data."lifecycle-state"'

Expect SUCCEEDED. Then on the instance, check mounts (findmnt --verify, lsblk), services (systemctl --failed), and that the backend is healthy on the load balancer before draining the next node.

4. Prefer live migration and automatic recovery

The instance availability configuration controls whether OCI tries live migration and what happens after a host failure:

oci compute instance update \
  --instance-id ocid1.instance.oc1..example \
  --availability-config '{"isLiveMigrationPreferred": true, "recoveryAction": "RESTORE_INSTANCE"}'

RESTORE_INSTANCE restarts the instance on a healthy host after an unplanned failure; STOP_INSTANCE leaves it stopped for you to deal with. Not every shape supports live migration (GPU, some bare metal and DenseIO shapes don't); check the shape documentation. Set the same values in Terraform (availability_config on oci_core_instance) so a rebuild keeps them.

Prevent it next time

  • Alert on new events. The oci_compute_infrastructure_health metric namespace includes maintenance_status, instance_status and health_status. Create an alarm on maintenance_status for production compartments and send it to the on-call topic. Check the metric description in the Console for the value meanings before setting the threshold.
  • Subscribe the right people. Maintenance announcements go to the tenancy's notification contacts. Make sure that is a team mailbox, not a person who left.
  • Run the Search query weekly and paste the result into the change calendar.
  • Design for a stop and start. Two or more instances across fault domains behind a load balancer turn reboot migrations into routine drains.
  • Keep fstab safe. nofail and _netdev on attached volumes stop a maintenance reboot from becoming an emergency-mode outage.
  • Keep instances reproducible. If a node can be relaunched from Terraform and a custom image, TERMINATE and relaunch is often the fastest resolution.

Related fixes