Failover Segments

Overview

Failover segments group compute hosts into logical fault domains. Each segment has its own recovery method — determining how instances are relocated when a host fails. Creating well-designed segments is the most important administrative task for Instance HA. Incorrect segment design (too few hosts, wrong recovery method) is the primary cause of failed automatic recovery.

Segment configuration changes take effect immediately and affect all active recovery workflows. Plan segment structure carefully before production deployment.

Prerequisites

Administrator role in Polystack Identity
Compute hosts registered and reachable
Instance HA service deployed via the deployment console

Segment Design Principles

Match Physical Topology

Group hosts that share a failure domain — the same power circuit, network switch, or rack. Hosts in the same fault domain should not be in the same segment.

Reserve Enough Headroom

For auto recovery, maintain 20–30% unused capacity across all hosts in the segment. For reserved_host, the reserved node must absorb all instances from the largest host.

Separate Critical Workloads

Place SLA-critical instances in segments with reserved_host recovery. Use auto segments for standard workloads where recovery capacity is shared.

Single-Segment Host Membership

A compute host can belong to only one segment. Plan segment boundaries before registering hosts to avoid re-registration overhead.

Create a Failover Segment

Dashboard
CLI

Navigate to Instance HA administration

Navigate to Instance-HA > Segments (admin view).

Create the segment

Click Create Segment and complete the form:

Field	Description	Example
Name	Unique identifier	`prod-zone-a`
Recovery Method	Evacuation algorithm	`auto`
Enabled	Activate immediately	Checked
Description	Optional documentation note	`Production AZ-A hosts`

Save

Click Create Segment. The segment appears in the list with status ENABLED.

Segment created and ready for host registration.

Authenticate as admin

Load admin credentials

source openrc.sh

Create the segment

Create failover segment

openstack segment create \
  --recovery_method auto \
  --enabled True \
  --description "Production Zone A" \
  prod-zone-a

Recovery method options:

Method	Behaviour
`auto`	Evacuate to any healthy host in the segment
`reserved_host`	Evacuate only to pre-designated reserved hosts
`rh_priority`	Prefer reserved; fall back to `auto`

Verify

Show segment

openstack segment show prod-zone-a

Segment shows enabled: True and the correct recovery_method.

Register Hosts in a Segment

Dashboard
CLI

Open the segment

Navigate to Instance-HA > Segments (admin view) and click the segment name.

Add host

Click Add Host and fill in:

Field	Description
Name	Compute hostname — must match the hostname registered in the Compute service
Type	`COMPUTE` for compute nodes
Control Attributes	JSON object with IPMI or SSH connection parameters
On Maintenance	Temporarily exclude host from recovery targets
Reserved	Designate as a standby node for `reserved_host` / `rh_priority` methods

Confirm registration

The host appears in the segment host list with ON_MAINTENANCE: False.

Host registered and available as a recovery target.

openstack segment host create \
  --type COMPUTE \
  --control_attributes '{"host": "compute-01.polystack.local"}' \
  --on_maintenance False \
  --reserved False \
  <segment-uuid>

Designate a reserved standby host

openstack segment host update \
  --reserved True \
  <segment-uuid> <host-uuid>

List hosts in segment

openstack segment host list <segment-uuid>

Reserved hosts must be in the same segment as the instances they recover. A host cannot belong to more than one segment.

Manage Segment Lifecycle

Disable a Segment
Place Host on Maintenance
Delete a Segment

Temporarily disable a segment to suppress recovery during maintenance windows.

Disable segment

openstack segment update --enabled False <segment-uuid>

Re-enable after maintenance is complete:

Re-enable segment

openstack segment update --enabled True <segment-uuid>

Disabling a segment suppresses all automatic recovery for hosts in that segment. Any host failure during the window requires manual evacuation.

Flag a specific host as on maintenance to exclude it from recovery targets without affecting the rest of the segment.

Set host maintenance flag

openstack segment host update \
  --on_maintenance True \
  <segment-uuid> <host-uuid>

Clear the flag when maintenance is complete:

Clear maintenance flag

openstack segment host update \
  --on_maintenance False \
  <segment-uuid> <host-uuid>

Deleting a segment removes all host registrations and historical notification data associated with it. Instances on registered hosts will no longer be automatically recovered.

Delete segment

openstack segment delete <segment-uuid>

Deregister all hosts from the segment before deletion:

Delete a host from segment

openstack segment host delete <segment-uuid> <host-uuid>

Validation

Dashboard
CLI

Navigate to Instance-HA > Segments (admin view). Verify:

All production segments have Status: ENABLED
Each segment lists the expected compute hosts
Reserved hosts are correctly flagged for reserved_host segments

Segments are enabled and all compute hosts are registered.

List all segments

openstack segment list

Verify host registration for each segment

for seg in $(openstack segment list -f value -c uuid); do
  echo "=== Segment: $seg ==="
  openstack segment host list $seg
done

All segments show enabled: True and expected hosts are listed.

Next Steps

Host Monitors

Configure IPMI and SSH monitors for hosts registered in your segments.

Recovery Methods

Deep-dive into recovery method selection and reserved host configuration.

Engine Configuration

Tune detection timeouts, retry intervals, and engine behaviour.

Architecture

Review the full Instance HA component architecture and deployment topology.

Core Services

Other Services

Overview

Segment Design Principles

Match Physical Topology

Reserve Enough Headroom

Separate Critical Workloads

Single-Segment Host Membership

Create a Failover Segment

Navigate to Instance HA administration

Create the segment

Save

Authenticate as admin

Create the segment

Verify

Register Hosts in a Segment

Open the segment

Add host

Confirm registration

Manage Segment Lifecycle

Validation

Next Steps

Host Monitors

Recovery Methods

Engine Configuration

Architecture

​Overview

​Segment Design Principles

Match Physical Topology

Reserve Enough Headroom

Separate Critical Workloads

Single-Segment Host Membership

​Create a Failover Segment

Navigate to Instance HA administration

Create the segment

Save

Authenticate as admin

Create the segment

Verify

​Register Hosts in a Segment

Open the segment

Add host

Confirm registration

​Manage Segment Lifecycle

​Validation

​Next Steps

Host Monitors

Recovery Methods

Engine Configuration

Architecture

Overview

Segment Design Principles

Create a Failover Segment

Register Hosts in a Segment

Manage Segment Lifecycle

Validation

Next Steps