Chapter 10. Managing an instance

You can perform management operations on an instance, such as resizing the instance or shelving the instance. For a complete list of management operations, see Instance management operations.

10.1. Resizing an instance

You can resize an instance if you need to increase or decrease the memory or CPU count of the instance. To resize an instance, select a new flavor for the instance that has the required capacity. Resizing an instance rebuilds and restarts the instance.

Procedure

  1. Retrieve the name or ID of the instance that you want to resize: 

    $ openstack server list

  2. Retrieve the name or ID of the flavor that you want to use to resize the instance: 

    $ openstack flavor list

  3. Resize the instance: 

    $ openstack server resize --flavor <flavor> \
  --wait <instance>
    • Replace <flavor> with the name or ID of the flavor that you retrieved in step 2.
    • Replace <instance> with the name or ID of the instance that you are resizing.
    Note

    Resizing can take time. The operating system on the instance performs a controlled shutdown before the instance is powered off and the instance is resized. During this time, the instance status is RESIZE: 

    $ openstack server list
+----------------------+----------------+--------+----------------------------+
| ID                   | Name           | Status | Networks                                |
+----------------------+----------------+--------+----------------------------+
| 67bc9a9a-5928-47c... | myCirrosServer | RESIZE | admin_internal_net=192.168.111.139    |
+----------------------+----------------+--------+----------------------------+

  4. When the resize completes, the instance status changes to VERIFY_RESIZE. You must now either confirm or revert the resize:

    • To confirm the resize, enter the following command: 

      $ openstack server resize confirm <instance>

    • To revert the resize, enter the following command: 

      $ openstack server resize revert <instance>

      The instance is reverted to the original flavor and the status is changed to ACTIVE.

Note

The cloud might be configured to automatically confirm instance resizes if you do not confirm or revert within a configured time frame.

10.2. Creating an instance snapshot

A snapshot is an image that captures the state of the running disk of an instance. You can take a snapshot of an instance to create an image that you can use as a template to create new instances. Snapshots allow you to create new instances from another instance, and restore the state of an instance. If you delete an instance on which a snapshot is based, you can use the snapshot image to create a new instance to the same state as the snapshot.

Procedure

  1. Retrieve the name or ID of the instance that you want to take a snapshot of: 

    $ openstack server list

  2. Create the snapshot: 

    $ openstack server image create --name <image_name> <instance>
    • Replace <image_name> with a name for the new snapshot image.
    • Replace <instance> with the name or ID of the instance that you want to create the snapshot from.

  3. Optional: To ensure that the disk state is consistent when you use the instance snapshot as a template to create new instances, enable the QEMU guest agent and specify that the filesystem must be quiesced during snapshot processing by adding the following metadata to the snapshot image: 

    $ openstack image set --property hw_qemu_guest_agent=yes \
 --property os_require_quiesce=yes <image_name>

    The QEMU guest agent is a background process that helps management applications execute instance OS level commands. Enabling this agent adds another device to the instance, which consumes a PCI slot, and limits the number of other devices you can allocate to the instance. It also causes Windows instances to display a warning message about an unknown hardware device.

10.3. Rescuing an instance

In an emergency such as a system failure or access failure, you can put an instance in rescue mode. This shuts down the instance, reboots it with a new instance disk, and mounts the original instance disk and config drive as a volume on the rebooted instance. You can connect to the rebooted instance to view the original instance disk to repair the system and recover your data.

Note

You cannot rescue an instance that was booted from a volume.

Procedure

  1. Perform the instance rescue: 

    $ openstack server rescue [--image <image>] <instance>
    • Optional: By default, the instance is booted from a rescue image provided by the cloud admin, or a fresh copy of the original instance image. Use the --image option to specify an alternative image to use when rebooting the instance in rescue mode.
    • Replace <instance> with the name or ID of the instance that you want to rescue.
  2. Connect to the rescued instance to fix the issue.

  3. Restart the instance from the normal boot disk: 

    $ openstack server unrescue <instance>

10.4. Shelving an instance

Shelving is useful if you have an instance that you are not using, but that you do not want to delete. When you shelve an instance, you retain the instance data and resource allocations, but clear the instance memory. Depending on the cloud configuration, shelved instances are moved to the SHELVED_OFFLOADED state either immediately or after a timed delay. When SHELVED_OFFLOADED, the instance data and resource allocations are deleted.

When you shelve an instance, the Compute service generates a snapshot image that captures the state of the instance, and allocates a name to the image in the following format: <instance>-shelved. This snapshot image is deleted when the instance is unshelved or deleted.

If you no longer need a shelved instance, you can delete it. You can shelve more than one instance at a time.

Procedure

  1. Retrieve the name or ID of the instance or instances that you want to shelve: 

    $ openstack server list

  2. Shelve the instance or instances: 

    $ openstack server shelve <instance> [<instance> ...]

    Replace <instance> with the name or ID of the instance that you want to shelve. You can specify more than one instance to shelve, as required.

  3. Verify that the instance has been shelved: 

    $ openstack server list

    Shelved instances have status SHELVED_OFFLOADED.

10.5. Instance management operations

After you create an instance, you can perform the following management operations.

Table 10.1. Management operations

OperationDescriptionCommand

Stop an instance

Stops the instance.

openstack server stop

Start an instance

Starts a stopped instance.

openstack server start

Pause a running instance

Immediately pause a running instance. The state of the instance is stored in memory (RAM). The paused instance continues to run in a frozen state. You are not prompted to confirm the pause action.

openstack server pause

Resume running of a paused instance

Immediately resume a paused instance. You are not prompted to confirm the resume action.

openstack server unpause

Suspend a running instance

Immediately suspend a running instance. The state of the instance is stored on the instance disk. You are not prompted to confirm the suspend action.

openstack server suspend

Resume running of a suspended instance

Immediately resume a suspended instance. The state of the instance is stored on the instance disk. You are not prompted to confirm the resume action.

openstack server resume

Delete an instance

Permanently destroy the instance. You are not prompted to confirm the destroy action. Deleted instances are not recoverable unless the cloud has been configured to enable soft delete.

Note

Deleting an instance does not delete its attached volumes. You must delete attached volumes separately. For more information, see Deleting a Block Storage service volume in the Storage Guide.

openstack server delete

Edit the instance metadata

You can use instance metadata to specify the properties of an instance. For more information, see Creating a customized instance.

openstack server set --property <key=value> [--property <key=value>] <instance>

Add security groups

Adds the specified security group to the instance.

openstack server add security group

Remove security groups

Removes the specified security group from the instance.

openstack remove security group

Rescue an instance

In an emergency such as a system failure or access failure, you can put an instance in rescue mode. This shuts down the instance and mounts the root disk to a temporary server. You can connect to the temporary server to repair the system and recover your data.

It is also possible to reboot a running instance into rescue mode. For example, this operation might be required if a filesystem of an instance becomes corrupted.

Note

You cannot rescue an instance that was booted from a volume.

openstack server rescue

Restore a rescued instance

Reboots the rescued instance.

openstack server unrescue

View instance logs

View the most recent section of the instance console log.

openstack console log show

Shelve an instance

When you shelve an instance you retain the instance data and resource allocations, but clear the instance memory. Depending on the cloud configuration, shelved instances are moved to the SHELVED_OFFLOADED state either immediately or after a timed delay. When an instance is in the SHELVED_OFFLOADED state, the instance data and resource allocations are deleted. The state of the instance is stored on the instance disk. If the instance was booted from volume, it goes to SHELVED_OFFLOADED immediately. You are not prompted to confirm the shelve action.

openstack server shelve

Unshelve an instance

Restores the instance using the disk image of the shelved instance.

openstack server unshelve

Lock an instance

Lock an instance to prevent non-admin users from executing actions on the instance.

openstack server lock

openstack server unlock

Soft reboot an instance

Gracefully stop and restart the instance. A soft reboot attempts to gracefully shut down all processes before restarting the instance. By default, when you reboot an instance it is a soft reboot.

openstack server reboot --soft <server>

Hard reboot an instance

Stop and restart the instance. A hard reboot shuts down the power to the instance and then turns it back on.

openstack server reboot --hard <server>

Rebuild an instance

Use new image and disk-partition options to rebuild the instance, which involves an instance shut down, re-image, and reboot. Use this option if you encounter operating system issues, rather than terminating the instance and starting over.

openstack server rebuild