Intended Audience

This page describes who consumes the Trilio Site Recovery for OpenStack API and what prior knowledge they are expected to bring. Understanding the intended audience helps you decide whether this documentation is the right starting point for your role — whether you are integrating DR automation into a deployment pipeline, building tooling around the openstack dr CLI, or calling the REST API directly from application code.

Who this documentation is written for

This documentation targets developers who consume the Trilio Site Recovery REST API or openstack dr CLI at an intermediate level. You are expected to be comfortable with OpenStack fundamentals — you know what Keystone tokens are, how Nova instances and Cinder volumes relate, and how to read a JSON response body. You do not need to be an OpenStack operator or storage administrator, but you should be able to work with openrc credentials and understand HTTP request/response cycles.

Primary personas

Automation and integration engineers

You are building DR automation into a CI/CD pipeline, an infrastructure-as-code workflow, or an internal operations platform. You call the REST API directly — POSTing to /v1/{tenant_id}/protection-groups/{pg_id}/action to trigger a failover, polling GET /v1/{tenant_id}/operations/{id} to track progress, and parsing the replication_health.failover_validation.can_failover flag to gate automated runbook steps. You care about exact HTTP status codes, request body shapes, and the difference between a 202 Accepted that starts a long-running operation and a 422 Unprocessable Entity that means a pre-condition failed before anything happened.

Platform and DevOps engineers

You are scripting DR workflows using the openstack dr CLI plugin. You write shell or Python scripts that invoke commands such as openstack dr failover <pg-id> --failover-type planned --wait and openstack dr replication health <pg-id>, then act on the output. You are comfortable installing the CLI plugin (pip install -e ./client or the python3-triliositerecovery Debian package) and sourcing OpenStack credentials before running commands.

Application developers integrating DR awareness

You are adding DR awareness to an application or internal tool — for example, surfacing replication lag to a dashboard, triggering a test failover on a schedule, or automating recovery point creation before a maintenance window. You consume the API through HTTP libraries rather than the CLI, and you need to understand authentication (Keystone tokens on port 5000, passed as X-Auth-Token), microversion negotiation (OpenStack-API-Version: protector 1.1, which is optional but recommended), and the structure of long-running operation responses.

What you are expected to know

You do not need to know how the Juju charm deploys the service, how protector.conf is rendered, or how the Pure Storage driver communicates with the array. Those topics are covered in the operator guide. What you do need is a clear model of the resources the API exposes — sites, protection groups, members, operations, tenant mappings, replication health — and how they relate to each other.

What this documentation covers

This documentation focuses on the API surface you interact with as a developer:

• REST endpoints — every route under /v1/{tenant_id}/, their request and response shapes, HTTP status codes, and error types from the error catalogue.
• CLI commands — the full openstack dr command set, their positional arguments, and flags.
• Authentication — how to obtain a Keystone token and pass it as X-Auth-Token; how microversion negotiation works and when the OpenStack-API-Version: protector 1.x header matters.
• Long-running operations — how to trigger an operation via POST /v1/{tenant_id}/protection-groups/{pg_id}/action, receive a 202 Accepted with an operation_id, and poll GET /v1/{tenant_id}/operations/{id} until the operation reaches a terminal state.
• Error handling — the exact exception names, HTTP status codes, and message templates the API returns, so your code can branch on them reliably.

What this documentation does not cover

• Deployment and charm operations — installing the Juju charm, configuring juju config trilio-site-recovery, or managing systemd services. See the operator guide.
• Storage array configuration — setting up Pure Storage FlashArray replication connections between sites. See your storage administrator.
• Keystone role pre-creation — the dr_operator and dr_site_admin roles must exist on both sites before any DR operation. See the deployment prerequisites guide.
• Horizon dashboard — the browser-based panel is covered in the dashboard guide.

Verify the API is reachable and discover the supported microversion

Before making authenticated calls, confirm the service is up and check what microversions it supports. The version discovery endpoint requires no authentication.

curl -s http://<protector-api-host>:8788/ | python3 -m json.tool

Expected response:

{
  "versions": [
    {
      "id": "v1.0",
      "status": "CURRENT",
      "version": "1.1",
      "min_version": "1.0",
      "links": [
        {
          "rel": "self",
          "href": "http://<protector-api-host>:8788/v1/"
        }
      ]
    }
  ]
}

The version field tells you the maximum supported microversion (1.1). Include OpenStack-API-Version: protector 1.1 in your requests to opt into all current behaviour.

Obtain a Keystone token and list protection groups

All versioned API calls require an X-Auth-Token obtained from Keystone on port 5000.

# Obtain a token
TOKEN=$(openstack token issue -f value -c id)
TENANT_ID=$(openstack project show -f value -c id "$(openstack token issue -f value -c project_id)")

# List protection groups
curl -s \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1" \
  http://<protector-api-host>:8788/v1/${TENANT_ID}/protection-groups \
  | python3 -m json.tool

Expected response (empty tenant):

{
  "protection_groups": []
}

Trigger a planned failover and poll the operation to completion

This is the core automation pattern: POST to the action endpoint, receive an operation_id in the 202 body, then poll until the operation reaches a terminal state.

PG_ID="<your-protection-group-id>"

# Trigger planned failover
RESPONSE=$(curl -s -X POST \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1" \
  -H "Content-Type: application/json" \
  -d '{"failover": {"failover_type": "planned"}}' \
  http://<protector-api-host>:8788/v1/${TENANT_ID}/protection-groups/${PG_ID}/action)

echo "$RESPONSE" | python3 -m json.tool

Expected 202 Accepted body:

{
  "message": "Failover initiated",
  "status": "pending",
  "protection_group_id": "<pg-id>",
  "operation_id": "<operation-id>",
  "operation": { ... }
}

The initial status is "pending". Poll the operation endpoint until it transitions to "completed" or "failed":

OP_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['operation_id'])")

while true; do
  STATUS=$(curl -s \
    -H "X-Auth-Token: $TOKEN" \
    http://<protector-api-host>:8788/v1/${TENANT_ID}/operations/${OP_ID} \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['operation']['status'])")
  echo "Operation status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 10
done

The equivalent CLI invocation (blocking until completion):

openstack dr failover "$PG_ID" --failover-type planned --wait

Check replication health before a failover

Before triggering a failover in automation, check can_failover to gate the operation.

curl -s \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1" \
  http://<protector-api-host>:8788/v1/${TENANT_ID}/protection-groups/${PG_ID}/replication-health \
  | python3 -c "
import sys, json
data = json.load(sys.stdin)
health = data['replication_health']
print('can_failover:', health['failover_validation']['can_failover'])
print('blockers:', health['failover_validation']['blockers'])
"

Expected output when the protection group is ready:

can_failover: True
blockers: []

The equivalent CLI command:

openstack dr replication health "$PG_ID"

Pre-validate a member before adding it to a protection group

Use the validation endpoint to check eligibility without side effects. A VM is rejected if it does not boot from a Cinder volume (InstanceNotCinderBoot, HTTP 422) or if its volumes lack replication_enabled='<is> True' (VolumeTypeNotReplicated, HTTP 422).

curl -s -X POST \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "<nova-instance-id>"}' \
  http://<protector-api-host>:8788/v1/${TENANT_ID}/protection-groups/${PG_ID}/members/validate \
  | python3 -m json.tool

Expected response when the instance is eligible:

{
  "errors": []
}

The equivalent CLI command:

openstack dr protection group member validate "$PG_ID" --instance "<nova-instance-id>"

• API reference — Complete endpoint listing with request/response schemas, status codes, and the full error catalogue.
• Authentication — How to obtain a Keystone token on port 5000 and pass it as X-Auth-Token; microversion negotiation with OpenStack-API-Version: protector 1.x.
• Protection Groups — The core DR abstraction: how to create a Protection Group, add VM members, and understand the ACTIVE → FAILING_OVER → FAILED_OVER → FAILING_BACK → ACTIVE lifecycle.
• DR Operations — How long-running operations work: the operation_id returned in 202 responses, polling GET /v1/{tenant_id}/operations/{id}, and interpreting status and progress fields.
• Replication Health — How to read the replication_health.failover_validation.can_failover flag and interpret lag, RPO compliance, and available recovery points.
• Failover and Failback — Planned vs. unplanned failover, recovery point selection, and the failback workflow for returning workloads to the primary site.
• Test Failover — Non-disruptive DR validation: how test VMs are isolated, how to clean up with openstack dr test failover cleanup, and how to use --operation to target a specific test run.
• Tenant Mappings — Why cross-site project UUIDs differ and how to create and validate mappings with openstack dr tenant mapping create.
• CLI plugin installation — Installing python3-triliositerecovery and verifying the openstack dr command set is available.
• Deployment prerequisites — Keystone roles (dr_operator, dr_site_admin), volume type extra-specs (replication_enabled='<is> True'), and network connectivity requirements between sites.