Rescue an instance

Instance rescue provides a mechanism for access, even if an image renders the instance inaccessible. Two rescue modes are currently provided.

Instance rescue

By default the instance is booted from the provided rescue image or a fresh copy of the original instance image if a rescue image is not provided. The root disk and optional regenerated config drive are also attached to the instance for data recovery.

Note

Rescuing a volume-backed instance is not supported with this mode.

Stable device instance rescue

As of 21.0.0 (Ussuri) an additional stable device rescue mode is available. This mode now supports the rescue of volume-backed instances.

This mode keeps all devices both local and remote attached in their original order to the instance during the rescue while booting from the provided rescue image. This mode is enabled and controlled by the presence of hw_rescue_device or hw_rescue_bus image properties on the provided rescue image.

As their names suggest these properties control the rescue device type (cdrom, disk or floppy) and bus type (scsi, virtio, ide, or usb) used when attaching the rescue image to the instance.

Support for each combination of the hw_rescue_device and hw_rescue_bus image properties is dependent on the underlying hypervisor and platform being used. For example the IDE bus is not available on POWER KVM based compute hosts.

Note

This mode is only supported when using the Libvirt virt driver.

This mode is not supported when using the LXC hypervisor as enabled by the libvirt.virt_type configurable on the computes.

Usage

Note

Pause, suspend, and stop operations are not allowed when an instance is running in rescue mode, as triggering these actions causes the loss of the original instance state and makes it impossible to unrescue the instance.

To perform an instance rescue, use the openstack server rescue command:

$ openstack server rescue SERVER

Note

On running the openstack server rescue command, an instance performs a soft shutdown first. This means that the guest operating system has a chance to perform a controlled shutdown before the instance is powered off. The shutdown behavior is configured by the shutdown_timeout parameter that can be set in the nova.conf file. Its value stands for the overall period (in seconds) a guest operating system is allowed to complete the shutdown.

The timeout value can be overridden on a per image basis by means of os_shutdown_timeout that is an image metadata setting allowing different types of operating systems to specify how much time they need to shut down cleanly.

To rescue an instance that boots from a volume you need to use the 2.87 microversion or later.

$ openstack --os-compute-api-version 2.87 server rescue SERVER

If you want to rescue an instance with a specific image, rather than the default one, use the --image parameter:

$ openstack server rescue --image IMAGE_ID SERVER

To restart the instance from the normal boot disk, run the following command:

$ openstack server unrescue SERVER