CLI Reference

openstack dr <resource> <action> [<positional-args>] [--flags]

openstack dr site list
openstack dr site show <site>
openstack dr site create <name> --site-type <PRIMARY|SECONDARY> --auth-url <url> [flags]
openstack dr site set <site> [flags]
openstack dr site delete [<site...>]
openstack dr site failover <site> [flags]
openstack dr failover to this site [flags]
openstack dr site operation list [flags]
openstack dr site operation show <operation>

openstack dr protection group list [--all-projects]
openstack dr protection group show <protection_group> [--all-projects]
openstack dr protection group create <name> --primary-site <site> --secondary-site <site> [flags]
openstack dr protection group set <protection_group> [flags]
openstack dr protection group delete [<protection_group...>] [--force]
openstack dr protection group member add <protection_group> --instance <id> [--boot-order <n>]
openstack dr protection group member set <protection_group> --member <id> --boot-order <n>
openstack dr protection group member remove <protection_group> --member <id>
openstack dr protection group member list <protection_group>
openstack dr protection group member validate <protection_group> --instance <id>
openstack dr protection group sync <protection_group> [flags]
openstack dr protection group mapping list <protection_group> [flags]
openstack dr protection group mapping create <protection_group> --resource-type <type> --primary-resource-id <id> --secondary-resource-id <id>
openstack dr protection group mapping delete <protection_group> <mapping>
openstack dr protection group reconcile <protection_group>

openstack dr replication health <protection_group>
openstack dr recovery point list <protection_group> [--limit <n>]
openstack dr recovery point create <protection_group> [--suffix <string>]

openstack dr failover <protection_group> [flags]
openstack dr failback <protection_group> [flags]
openstack dr test failover <protection_group> [flags]
openstack dr test failover cleanup <protection_group> [flags]

openstack dr operation list [flags]
openstack dr operation show <operation>
openstack dr operation cancel <operation>
openstack dr metadata sync <protection_group> [--force]

openstack dr tenant mapping list [flags]
openstack dr tenant mapping show <mapping>
openstack dr tenant mapping create --local-tenant <id> --remote-site <id> --remote-tenant <id> [flags]
openstack dr tenant mapping delete [<mapping...>] [--no-sync-remote]
openstack dr tenant mapping validate <mapping>

openstack dr usage summary
openstack dr usage report [flags]

# From the repository root — installs only the CLI, not the server
pip install -e ./client

openstack --help | grep '^ *dr'

  dr failover
  dr failback
  dr metadata sync
  ...

# Obtain the service user ID from the primary site's Keystone
PRIMARY_SVC_USER_ID=$(openstack user show protector -f value -c id)

# Register the primary site
openstack dr site create primary-site \
  --site-type PRIMARY \
  --auth-url https://keystone.primary.example.com:5000 \
  --region RegionOne \
  --service-username protector \
  --service-password "${PRIMARY_SVC_PASS}" \
  --service-project-name service \
  --service-user-domain-name Default \
  --service-project-domain-name Default \
  --service-user-id "${PRIMARY_SVC_USER_ID}"

+--------------------+--------------------------------------+
| Field              | Value                                |
+--------------------+--------------------------------------+
| id                 | a1b2c3d4-e5f6-7890-abcd-ef1234567890 |
| name               | primary-site                         |
| site_type          | PRIMARY                              |
| status             | active                               |
| auth_url           | https://keystone.primary.example.com:5000 |
| region_name        | RegionOne                            |
| created_at         | 2025-01-15T10:00:00Z                 |
+--------------------+--------------------------------------+

# Source secondary-site credentials to look up its service user
source secondary-site-openrc.sh
SECONDARY_SVC_USER_ID=$(openstack user show protector -f value -c id)

# Switch back to primary and register the secondary
source primary-site-openrc.sh

openstack dr site create secondary-site \
  --site-type SECONDARY \
  --auth-url https://keystone.secondary.example.com:5000 \
  --region RegionOne \
  --service-username protector \
  --service-password "${SECONDARY_SVC_PASS}" \
  --service-project-name service \
  --service-user-domain-name Default \
  --service-project-domain-name Default \
  --service-user-id "${SECONDARY_SVC_USER_ID}"

openstack dr site list

+--------------------------------------+----------------+-----------+--------+
| ID                                   | Name           | Type      | Status |
+--------------------------------------+----------------+-----------+--------+
| a1b2c3d4-...                         | primary-site   | PRIMARY   | active |
| b2c3d4e5-...                         | secondary-site | SECONDARY | active |
+--------------------------------------+----------------+-----------+--------+

LOCAL_PROJECT_ID=$(openstack project show myproject -f value -c id)

# Obtain the remote project ID (requires credentials on the secondary)
REMOTE_PROJECT_ID="<uuid-of-myproject-on-secondary-site>"
SECONDARY_SITE_ID=$(openstack dr site show secondary-site -f value -c id)

openstack dr tenant mapping create \
  --local-tenant "${LOCAL_PROJECT_ID}" \
  --remote-site "${SECONDARY_SITE_ID}" \
  --remote-tenant "${REMOTE_PROJECT_ID}" \
  --description "myproject DR mapping"

+---------------------+--------------------------------------+
| Field               | Value                                |
+---------------------+--------------------------------------+
| id                  | c3d4e5f6-...                         |
| local_tenant_name   | myproject                            |
| remote_site_name    | secondary-site                       |
| remote_tenant_name  | myproject                            |
| status              | active                               |
| created_at          | 2025-01-15T10:05:00Z                 |
+---------------------+--------------------------------------+

openstack volume type show replicated-vol-type -f json | \
  python3 -c "import sys,json; \
    specs=json.load(sys.stdin)['extra_specs']; \
    print(specs.get('replication_enabled'))"
# Should print: <is> True

PG_ID=$(openstack dr protection group create prod-pg \
  --primary-site primary-site \
  --secondary-site secondary-site \
  --replication-type async \
  --volume-type replicated-vol-type \
  --description "Production workloads" \
  -f value -c id)

echo "Protection Group ID: ${PG_ID}"

VM_ID=$(openstack server show my-app-vm -f value -c id)

openstack dr protection group member validate "${PG_ID}" \
  --instance "${VM_ID}"

+------------------------+----------------------------------------+
| Field                  | Value                                  |
+------------------------+----------------------------------------+
| valid                  | True                                   |
| errors                 | []                                     |
| warnings               | []                                     |
| details.volume_count   | 2                                      |
| details.backend_name   | pure                                   |
+------------------------+----------------------------------------+

openstack dr protection group member add "${PG_ID}" \
  --instance "${VM_ID}" \
  --boot-order 1

# Add a dependent VM that should start after the first
DB_VM_ID=$(openstack server show my-db-vm -f value -c id)
openstack dr protection group member add "${PG_ID}" \
  --instance "${DB_VM_ID}" \
  --boot-order 2

openstack dr protection group member list "${PG_ID}"

openstack dr replication health "${PG_ID}"

+----------------------------------------+-------------------+
| Field                                  | Value             |
+----------------------------------------+-------------------+
| protection_group_id                    | <pg-uuid>         |
| protection_group_name                  | prod-pg           |
| replication_health.health_report.state | healthy           |
| replication_health.health_report.lag_seconds | 45          |
| replication_health.health_report.rpo_compliant | True      |
| replication_health.health_report.recovery_points | 12     |
| replication_health.failover_validation.can_failover | True |
| replication_health.failover_validation.warnings | []     |
| replication_health.failover_validation.blockers | []     |
+----------------------------------------+-------------------+

CAN_FAILOVER=$(openstack dr replication health "${PG_ID}" \
  -f json | python3 -c \
  "import sys,json; h=json.load(sys.stdin); \
   print(h['replication_health']['failover_validation']['can_failover'])")

[ "${CAN_FAILOVER}" = "True" ] && echo "Ready" || echo "Not ready"

# Start the test — use --auto-network or provide --network-mapping
TEST_OP_ID=$(openstack dr test failover "${PG_ID}" \
  --auto-network \
  --recovery-point "$(openstack dr recovery point list "${PG_ID}" \
      --limit 1 -f value -c id)" \
  -f value -c operation_id)

echo "Test failover operation: ${TEST_OP_ID}"

# Poll until complete
while true; do
  STATUS=$(openstack dr operation show "${TEST_OP_ID}" -f value -c status)
  PROGRESS=$(openstack dr operation show "${TEST_OP_ID}" -f value -c progress)
  echo "Status: ${STATUS} (${PROGRESS})"
  [ "${STATUS}" = "completed" ] || [ "${STATUS}" = "failed" ] && break
  sleep 15
done

# Inspect test VMs on the secondary site, then clean up
openstack dr test failover cleanup "${PG_ID}" \
  --operation "${TEST_OP_ID}"

# Verify readiness first
openstack dr replication health "${PG_ID}"

# Trigger planned failover and wait for completion
OP_ID=$(openstack dr failover "${PG_ID}" \
  --failover-type planned \
  --wait \
  -f value -c operation_id)

openstack dr operation show "${OP_ID}"

+---------------------+--------------------------------------+
| Field               | Value                                |
+---------------------+--------------------------------------+
| id                  | <operation-uuid>                     |
| protection_group_id | <pg-uuid>                            |
| operation_type      | failover                             |
| failover_type       | planned                              |
| status              | pending                              |
| source_site         | primary-site                         |
| target_site         | secondary-site                       |
+---------------------+--------------------------------------+

# List available recovery points on the secondary
openstack dr recovery point list "${PG_ID}"

# Fail over to a specific point
openstack dr failover "${PG_ID}" \
  --failover-type unplanned \
  --recovery-point "protector-pg-prod-pg-2025-01-14T08:00:00" \
  --force

OP_ID=$(openstack dr failback "${PG_ID}" \
  --wait \
  -f value -c operation_id)

openstack dr operation show "${OP_ID}"

# Fail over all PGs at primary-site to secondary
openstack dr site failover primary-site \
  --failover-type unplanned \
  --yes

# Monitor site-level progress
openstack dr site operation list --status running
openstack dr site operation show <site-operation-id>

#!/bin/bash
# Polls all Protection Groups and alerts if any cannot fail over

PGs=$(openstack dr protection group list -f value -c id)

for pg in ${PGs}; do
  HEALTH=$(openstack dr replication health "${pg}" -f json 2>/dev/null)
  CAN_FAILOVER=$(echo "${HEALTH}" | python3 -c \
    "import sys,json; h=json.load(sys.stdin); \
     print(h['replication_health']['failover_validation']['can_failover'])")
  PG_NAME=$(openstack dr protection group show "${pg}" -f value -c name)

  if [ "${CAN_FAILOVER}" != "True" ]; then
    BLOCKERS=$(echo "${HEALTH}" | python3 -c \
      "import sys,json; h=json.load(sys.stdin); \
       print(h['replication_health']['failover_validation']['blockers'])")
    echo "ALERT: ${PG_NAME} (${pg}) cannot fail over: ${BLOCKERS}"
  else
    echo "OK: ${PG_NAME} (${pg})"
  fi
done

# Extract a single value for use in scripts
PG_ID=$(openstack dr protection group create prod-pg \
  --primary-site primary-site \
  --secondary-site secondary-site \
  --volume-type replicated-vol-type \
  -f value -c id)

# JSON output for programmatic parsing
openstack dr operation show "${OP_ID}" -f json

# YAML output
openstack dr protection group show "${PG_ID}" -f yaml

# Select specific columns
openstack dr protection group list \
  -c id -c name -c status

# Filter operations by type
openstack dr operation list \
  --operation-type failover \
  --status completed

# Debug mode
openstack --debug dr replication health "${PG_ID}"

# List all dr commands
openstack help dr

# Command-specific help
openstack dr site create --help
openstack dr failover --help
openstack dr test failover cleanup --help