Rebuilding Instances from Images in OpenStack

Rebuilding an instance in OpenStack allows you to start fresh with a new operating system image while maintaining your instance's identity, network configuration, and IP addresses. This operation is particularly useful for OS upgrades, disaster recovery, and applying major system changes without the complexity of migrating to a new instance.

What is Instance Rebuild?

Instance rebuild is a Nova compute operation that re-images an existing instance from a different image while preserving key attributes such as the instance UUID, fixed and floating IP addresses, network ports, and attached volumes. The rebuild process shuts down the instance, applies the new image, and reboots the server on the same compute host.

Unlike creating a new instance, rebuild maintains your existing networking configuration and attached resources, which simplifies the process of changing operating systems or applying major updates.

When to Use Instance Rebuild

OS Upgrades and Major Updates

Rebuild is ideal when you need to upgrade to a new operating system version or apply major system changes that require starting from a clean base image. For example, upgrading from Ubuntu 20.04 to Ubuntu 22.04 or moving from CentOS 7 to Rocky Linux 9.

Disaster Recovery

When an instance becomes corrupted or unstable due to software issues, misconfigurations, or failed updates, rebuilding from a known-good image restores functionality while preserving network identity and attached storage.

Configuration Reset

If an instance has accumulated configuration drift or unwanted changes over time, rebuilding from the original image provides a clean slate while maintaining the same IP addresses and network connectivity.

Security Remediation

After a security incident, rebuilding an instance from a trusted base image ensures all compromised system files are replaced while preserving attached data volumes for forensic analysis.

When NOT to Use Rebuild

Rebuild is not appropriate in all situations. Consider these scenarios where alternative approaches work better:

Compute Host Failures: If the physical host has failed, use the evacuate command instead to move instances to healthy hosts.

Minor Updates: For routine package updates or small configuration changes, standard update procedures are more efficient than a full rebuild.

Instance Migration: If you need to move an instance to a different compute host for performance or maintenance reasons, use live migration or cold migration instead.

Preserving Local Disk Data: Rebuild replaces the root disk entirely. If you have critical data on the ephemeral disk, back it up first or use the --preserve-ephemeral option.

How to Rebuild an Instance in Horizon Dashboard

OpenStack provides two methods for rebuilding instances: the Horizon web interface and the command line interface. Most users find the Horizon dashboard easier for interactive operations, while the CLI provides automation capabilities for scripting and batch operations.

Step 1: Access the Instances Page

Log into the Horizon dashboard and navigate to Project > Compute > Instances from the left navigation menu. This displays a table showing all instances in your current project.

Step 2: Locate the Target Instance

Find the instance you want to rebuild in the instances list. You can use the search filter or scroll through the table. Verify you have identified the correct instance by checking its name, IP address, and current status before proceeding.

Step 3: Open the Actions Menu

In the Actions column on the right side of the instance row, click the dropdown arrow to reveal available actions for that instance. The dropdown displays all operations you can perform on the instance based on its current state.

Step 4: Select Rebuild Instance

From the actions dropdown, select Rebuild Instance. This opens the Rebuild Instance dialog box showing configuration options for the rebuild operation.

Step 5: Choose the Target Image

In the rebuild dialog, locate the Select Image dropdown menu. This dropdown displays all images available in your project, including public distribution images, shared images, and snapshots you have created.

Select the image you want to use for the rebuild. The image name typically indicates the operating system and version, such as Ubuntu 22.04 LTS or Rocky Linux 9. Ensure the image you select is compatible with your instance's flavor and architecture.

Step 6: Review Preservation Warnings

The rebuild dialog displays important information about what will be preserved and what will be replaced during the operation:

Preserved during rebuild:

• Instance UUID and identity
• Fixed and floating IP addresses
• Network ports and security groups
• Attached Cinder volumes
• Instance metadata and flavor

Replaced during rebuild:

• Root disk contents (completely replaced with new image)
• Ephemeral disk contents (unless preserve option is checked)
• SSH host keys (new keys generated)
• All installed software and configuration

If you need to preserve data on ephemeral disks, check the Preserve Ephemeral Partition option before proceeding. This option only appears if your instance has ephemeral storage configured.

Step 7: Optional Configuration Changes

The rebuild dialog allows you to optionally modify the instance name during the rebuild. You can also specify a disk partition type if required by your use case, though the default setting works for most scenarios.

Review all settings carefully before proceeding. There is no undo operation for a rebuild once initiated.

Step 8: Initiate the Rebuild

Click the Rebuild button at the bottom of the dialog to start the rebuild operation. Horizon closes the dialog and returns you to the instances list.

Step 9: Monitor Rebuild Progress

The instance status changes to Rebuild in the instances list. The status column shows the current state as the rebuild progresses through these phases:

1. Rebuild - Nova prepares the instance for rebuild
2. Rebuilding - The new image is being applied
3. Active - Rebuild completed and instance is booting

The rebuild process typically completes within 5 to 15 minutes depending on the image size and compute host performance. The instance status updates automatically without needing to refresh the page.

Step 10: Verify Rebuild Completion

Once the status returns to Active, verify the rebuild completed successfully:

Check instance details: Click the instance name to view its details page. Verify that the Image Name field shows the new image you selected.

Verify network connectivity: The IP Address tab should show the same fixed and floating IPs that existed before the rebuild.

Test SSH access: Attempt to connect via SSH using your key pair. Note that you will need to remove the old SSH host key from your known_hosts file since the rebuild generates new host keys:

1ssh-keygen -R <instance-ip>
Copy

Confirm boot status: Check the Log tab in the instance details to review boot messages and confirm the instance started correctly with the new image.

If the rebuild fails or the instance does not return to Active status within 20 minutes, check the instance console log from the Console tab or contact support for assistance.

How to Rebuild an Instance Using OpenStack CLI

For users who prefer command-line operations or need to automate rebuild tasks, the OpenStack CLI provides flexible control over the rebuild process.

The openstack server rebuild command provides the most flexibility and control. The basic syntax is:

1openstack server rebuild --image <image> <server>
Copy

Example:

1openstack server rebuild --image ubuntu-22.04-x86_64 my-web-server
Copy

Common Options:

1openstack server rebuild \
2  --image <image> \
3  --name <new-name> \
4  --preserve-ephemeral \
5  --wait \
6  <server>
Copy

Option Descriptions:

• --image: The image to rebuild from (required)
• --name: Optionally rename the instance during rebuild
• --preserve-ephemeral: Keep data on ephemeral disks (if applicable)
• --wait: Wait for the rebuild operation to complete before returning
• --property: Set or update instance properties

What Gets Preserved During Rebuild

Understanding what remains unchanged during a rebuild helps you plan the operation effectively.

Preserved Attributes:

• Instance UUID (unique identifier)
• Fixed IP addresses
• Floating IP addresses
• Network ports and security group associations
• Attached Cinder volumes
• Instance metadata and properties
• Resource flavor (vCPUs, RAM, disk allocation)
• Availability zone placement

What Changes:

• Root disk contents (replaced with new image)
• Ephemeral disk contents (unless --preserve-ephemeral is used)
• Installed software and configuration files
• SSH host keys (new keys generated)
• Temporary files and caches

Preparing for a Rebuild

Proper preparation ensures a smooth rebuild process and minimizes downtime.

Backup Critical Data

Before rebuilding, back up any critical data that exists on the instance's root disk or ephemeral storage. Attached Cinder volumes are not affected by rebuild, but data on the root disk will be replaced.

1# Example: Create a snapshot before rebuilding
2openstack server image create --name my-server-backup my-web-server
Copy

Document Current Configuration

Record your current configuration details, including installed packages, configuration files, firewall rules, and application settings. This documentation helps you quickly restore your customizations after the rebuild.

Notify Users

If the instance hosts services used by others, schedule the rebuild during a maintenance window and notify affected users about the expected downtime.

Verify Image Compatibility

Ensure the new image is compatible with your instance's flavor and attached resources. Check that the image supports the same architecture (x86_64, ARM) and has appropriate drivers for your network configuration.

After the Rebuild

Once the rebuild completes, the instance boots with the new image. Complete these post-rebuild steps:

Verify Connectivity

Confirm that the instance boots successfully and that network connectivity works as expected:

1# Check instance status
2openstack server show my-web-server
3
4# Test SSH connectivity
5ssh ubuntu@<floating-ip>
Copy

Reapply Configuration

Reinstall required packages, restore configuration files, and reapply any customizations that existed before the rebuild. Using configuration management tools like Ansible, Puppet, or Chef streamlines this process.

Mount Attached Volumes

If you have Cinder volumes attached to the instance, verify they are mounted correctly and contain your data:

1# List attached volumes
2lsblk
3
4# Mount volume if needed
5sudo mount /dev/vdb /mnt/data
Copy

Update SSH Known Hosts

Since the rebuild generates new SSH host keys, update your local known_hosts file to avoid SSH warnings:

1ssh-keygen -R <instance-ip>
Copy

Test Application Functionality

Verify that all applications and services function correctly with the new image. Test database connections, web services, and any integrations with other systems.

Rebuild vs Evacuate vs Create New

OpenStack provides several operations that may seem similar but serve different purposes.

Rebuild changes an instance's image while keeping it on the same compute host. Use rebuild when the host is healthy but you need to change the instance's operating system or apply major updates.

Evacuate moves instances from a failed compute host to a healthy host. Evacuate is an administrative operation performed during host failures and requires shared storage or Cinder volumes. Use evacuate when the compute host itself has failed.

Create New Instance provisions a completely new instance with a new UUID, new network configuration, and new IP addresses. Use this approach when you need a fresh instance without the constraints of the existing one.

Troubleshooting Common Issues

Rebuild Fails with "Image Not Found"

Verify that the image exists and that you have permission to use it:

1openstack image list
Copy

Ensure you're using the correct image name or UUID in your rebuild command.

Instance Stuck in "REBUILD" Status

If an instance remains in the REBUILD state for an extended period, check the compute service logs:

1# On the compute node
2sudo journalctl -u openstack-nova-compute -f
Copy

You may need to reset the instance state or contact your administrator if the rebuild process has stalled.

Network Connectivity Lost After Rebuild

Verify that security groups and network ports remain properly configured:

1openstack server show <instance>
2openstack port list --server <instance>
Copy

Check that the new image has appropriate network drivers and that the network configuration matches your environment.

Ephemeral Data Lost

If you needed to preserve ephemeral disk data but forgot to use the --preserve-ephemeral flag, you'll need to restore from backup. Always back up critical data before rebuilding.

Best Practices

Test rebuilds in development environments before performing them on production instances to identify any compatibility issues or configuration requirements.

Use configuration management tools to automate post-rebuild configuration. This reduces manual work and ensures consistency across rebuilds.

Document rebuild procedures specific to your environment, including required images, configuration steps, and verification tests.

Schedule rebuilds during maintenance windows to minimize impact on users and applications.

Monitor rebuild operations through the Horizon dashboard or command line to catch issues early.

Keep base images updated with security patches and required software to minimize post-rebuild configuration work.

Frequently Asked Questions

Can I rebuild an instance with a different flavor?

No, rebuild does not change the instance flavor. To change vCPUs, RAM, or disk size, use the resize operation instead.

Will attached Cinder volumes be affected?

No, Cinder volumes remain attached and unchanged during rebuild. Only the root disk is replaced.

Can I rebuild a shelved instance?

You must unshelve the instance before rebuilding. Rebuild only works on active instances.

How long does a rebuild take?

Rebuild time depends on image size and compute host performance. Most rebuilds complete within 5 to 15 minutes.

Can I automate rebuilds?

Yes, you can script rebuild operations using the OpenStack CLI or APIs. This is useful for disaster recovery automation or scheduled maintenance.

Additional Resources

For more information about OpenStack instance management, explore these resources:

• OpenStack Nova documentation on server rebuild
• Managing IP addresses in OpenStack
• OpenStack Compute Admin Guide - Comprehensive instance management documentation

Rebuilding instances in OpenStack provides a powerful way to refresh or upgrade instances while maintaining network identity and attached resources. By understanding when to use rebuild, following proper preparation steps, and applying best practices, you can leverage this operation effectively for OS upgrades, disaster recovery, and system maintenance.