Protection Groups Api

This page covers the Protection Groups API for Trilio Site Recovery — the central resource you interact with to define, manage, and maintain DR-protected sets of Nova VMs. A Protection Group is the unit of DR: it binds one or more VM instances to a replication-enabled Cinder Consistency Group, tracks primary and secondary site assignments, and carries the state that drives every failover, failback, and test-failover operation. Understanding how to create, update, and populate Protection Groups correctly is a prerequisite for every other DR workflow, because all operations — including replication policy configuration, resource mapping, and site-level failover — operate against a Protection Group.

Before using the Protection Groups API, ensure the following are in place:

• Two registered OpenStack sites — a primary and a secondary site must both be registered with the Protector service using the Sites API. Retrieve their UUIDs before creating a Protection Group.
• Replication-enabled Cinder volume types on both sites — each site must have a volume type where replication_enabled='<is> True' and replication_type='<in> async' (or '<in> sync') are set. The volume type name does not need to match across sites, but the same volume_type_id must be referenced when creating the Protection Group.
• Trilio Site Recovery services running — protector-api and protector-engine must be running on both the primary and secondary sites. Verify with systemctl status protector-api protector-engine.
• A valid Keystone token with project membership — Protection Group operations are tenant-scoped. Your token must belong to the project (tenant_id) you target in the URL path.
• OSC CLI plugin installed — the protectorclient plugin must be installed in your virtual environment if you are using the openstack protector CLI interface.
• API version header — all requests must include OpenStack-API-Version: protector 1.1 (minimum). The current supported version is 1.2.
• Both sites reachable — the Protector service blocks Protection Group creation and modification when the peer site is unreachable to prevent metadata divergence. Verify connectivity before beginning.

The Protection Groups API is served by the protector-api service, which is installed as part of the standard Trilio Site Recovery deployment. No additional installation steps are required beyond the base service setup. However, you must ensure the OSC CLI plugin (protectorclient) is installed in your environment to use CLI examples on this page.

Step 1 — Verify the API service is running on both sites

# On the primary site controller
systemctl status protector-api

# On the secondary site controller
systemctl status protector-api

Both must show active (running). If either is not running, start it:

systemctl start protector-api

Step 2 — Confirm the API endpoint is reachable

curl -s http://<primary-controller>:8788/

A successful response returns a versions document. Port 8788 is the default.

Step 3 — Install the OSC CLI plugin (if not already present)

pip install protectorclient

Confirm the plugin is loaded:

openstack protector --help

Step 4 — Configure clouds.yaml for multi-site access

The CLI plugin authenticates to both sites using named cloud profiles. Create or update ~/.config/openstack/clouds.yaml:

clouds:
  site-a:
    auth:
      auth_url: http://site-a-controller:5000/v3
      project_name: production-project
      username: your-user
      password: your-password
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne

  site-b:
    auth:
      auth_url: http://site-b-controller:5000/v3
      project_name: production-project
      username: your-user
      password: your-password
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne

Step 5 — Source credentials or set environment variables for your active site

export OS_AUTH_URL=http://site-a-controller:5000/v3
export OS_PROJECT_NAME=production-project
export OS_USERNAME=your-user
export OS_PASSWORD=your-password
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_DOMAIN_NAME=Default

You are now ready to use the Protection Groups API.

Protection Groups expose the following configurable properties at creation and update time. Understanding each field and its downstream effect is important — many of these values cannot be changed after the Protection Group is active without first removing all members.

Protection Group Properties

Automatically-Managed Properties

The following properties are managed by the Protector service and reflect runtime state. You read but do not set them directly:

Metadata Synchronization Behavior

Any modification to a Protection Group — including adding or removing members — immediately triggers a metadata sync push to the peer site. If the peer site is unreachable at the time of the modification, the operation is blocked and returns an error. This is by design: allowing one-sided changes would cause version divergence that could corrupt failover behavior. The sync_status sub-resource tracks the synchronization state and version numbers across both sites.

RBAC Policy Defaults

The default policy.yaml applies rule:admin_or_owner to all Protection Group operations. Project members can only see and modify Protection Groups within their own project. Administrators have cross-project visibility.

"protector:protection_groups:index": "rule:default"
"protector:protection_groups:show": "rule:default"
"protector:protection_groups:create": "rule:default"
"protector:protection_groups:update": "rule:default"
"protector:protection_groups:delete": "rule:default"

Creating a Protection Group

Creating a Protection Group triggers an internal chain of operations: the service validates both sites, confirms the volume type supports replication on both ends, creates a Cinder Consistency Group on the primary site, creates a matching Consistency Group on the secondary site, and then synchronizes the new Protection Group metadata to the peer site. The Protection Group moves from creating to active only when all of these steps succeed.

CLI:

openstack protector protection-group create \
  --name prod-web-app \
  --description "Production web application" \
  --replication-type async \
  --primary-site site-a \
  --secondary-site site-b \
  --volume-type replicated-ssd

REST API:

TOKEN=$(openstack token issue -f value -c id)
TENANT_ID=$(openstack token issue -f value -c project_id)

curl -X POST http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "OpenStack-API-Version: protector 1.1" \
  -d '{
    "protection_group": {
      "name": "prod-web-app",
      "description": "Production web application",
      "replication_type": "async",
      "primary_site_id": "<site-a-uuid>",
      "secondary_site_id": "<site-b-uuid>",
      "volume_type_id": "<replicated-ssd-uuid>"
    }
  }'

Listing Protection Groups

List all Protection Groups visible to your project:

openstack protector protection-group list

curl -X GET http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

Showing a Protection Group

The show response includes the linked Consistency Group details and current replication state:

openstack protector protection-group show prod-web-app

curl -X GET http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id> \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

Updating a Protection Group

You can update name and description at any time. Immutable fields (replication_type, primary_site_id, secondary_site_id, volume_type_id) cannot be changed after creation. Every update synchronizes metadata to the peer site — the request will fail if the peer is unreachable.

curl -X PUT http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id> \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "OpenStack-API-Version: protector 1.1" \
  -d '{
    "protection_group": {
      "description": "Production web application - updated description"
    }
  }'

Deleting a Protection Group

Deletion cascades to the Consistency Group and removes all member associations. All VMs must be removed from the group before deletion, and the group must be in active status (not mid-operation). The deletion also removes the synchronized metadata copy from the peer site.

openstack protector protection-group delete prod-web-app

curl -X DELETE http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id> \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

Adding a VM to a Protection Group

Adding a member causes the service to query Nova for the instance's attached volumes, validate that every volume uses the Protection Group's configured volume type, and add each volume to the Cinder Consistency Group. The member's complete configuration (flavor, networks, security groups, keypair) is captured in metadata and synced to the peer site — this metadata is what enables VM recreation at failover time.

openstack protector protection-group member-add prod-web-app \
  --instance-id <web-server-1-uuid>

curl -X POST http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id>/members \
  -H "X-Auth-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -H "OpenStack-API-Version: protector 1.1" \
  -d '{
    "member": {
      "instance_id": "<web-server-1-uuid>",
      "volume_ids": ["<vol-1-uuid>", "<vol-2-uuid>"]
    }
  }'

Note: The volume_ids field in the REST body is optional when using the CLI. When omitted, the engine automatically discovers all volumes attached to the instance. Providing explicit volume_ids is useful when you need to protect a specific subset of a VM's volumes.

Listing Members

openstack protector protection-group member-list prod-web-app

curl -X GET http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id>/members \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

Removing a VM from a Protection Group

Removing a member detaches its volumes from the Consistency Group and deletes the member record. The volumes themselves are not deleted. Metadata is re-synced to the peer site after removal.

curl -X DELETE http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id>/members/<member-id> \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

Checking and Forcing Metadata Sync

Because Protection Group modifications are blocked when the peer site is unreachable, it is useful to check sync state before making changes:

openstack protector protection-group sync-status prod-web-app

If the peer site recovered after a period of unreachability, push a manual sync before resuming modifications:

openstack protector protection-group sync-force prod-web-app

Example 1 — Create a Protection Group with async replication

This is the standard creation flow for a production workload using async replication.

openstack protector protection-group create \
  --name prod-web-app \
  --description "Production web application" \
  --replication-type async \
  --primary-site site-a \
  --secondary-site site-b \
  --volume-type replicated-ssd

Expected output:

+------------------------+--------------------------------------+
| Field                  | Value                                |
+------------------------+--------------------------------------+
| id                     | pg-12345678-1234-1234-1234-123456789abc |
| name                   | prod-web-app                         |
| description            | Production web application           |
| status                 | active                               |
| replication_type       | async                                |
| primary_site_id        | site-a-uuid                          |
| secondary_site_id      | site-b-uuid                          |
| current_primary_site_id| site-a-uuid                          |
| consistency_group_id   | cg-87654321-4321-4321-4321-87654321  |
| failover_count         | 0                                    |
| created_at             | 2025-06-01T10:00:00Z                 |
+------------------------+--------------------------------------+

The status: active confirms both Cinder Consistency Groups were created (on both sites) and metadata was successfully synchronized to the peer site.

Example 2 — Add multiple VMs to a Protection Group

After creation, populate the group with VMs. Each member-add call independently syncs metadata to the peer site.

# Add the web server
openstack protector protection-group member-add prod-web-app \
  --instance-id a1b2c3d4-0001-0001-0001-000000000001

# Add the application server
openstack protector protection-group member-add prod-web-app \
  --instance-id a1b2c3d4-0002-0002-0002-000000000002

# Add the database server
openstack protector protection-group member-add prod-web-app \
  --instance-id a1b2c3d4-0003-0003-0003-000000000003

Expected output (per member add):

+------------------------+--------------------------------------+
| Field                  | Value                                |
+------------------------+--------------------------------------+
| id                     | member-aabbccdd-1234-1234-1234-aabbccdd1234 |
| protection_group_id    | pg-12345678-1234-1234-1234-123456789abc |
| instance_id            | a1b2c3d4-0001-0001-0001-000000000001 |
| instance_name          | web-server-1                         |
| status                 | protected                            |
| volumes_added          | 2                                    |
+------------------------+--------------------------------------+

Then verify all members are listed:

openstack protector protection-group member-list prod-web-app

+-------------+-------------------+-----------+-----------+
| id          | instance_name     | status    | volumes   |
+-------------+-------------------+-----------+-----------+
| member-aa.. | web-server-1      | protected | 2         |
| member-bb.. | app-server-1      | protected | 2         |
| member-cc.. | db-server-1       | protected | 3         |
+-------------+-------------------+-----------+-----------+

Example 3 — Verify metadata sync status after adding members

After populating the group, confirm both sites are at the same metadata version before proceeding to configure the replication policy.

openstack protector protection-group sync-status prod-web-app

Expected output (healthy state):

Sync Status: ✅ IN SYNC

Local Metadata:
  Version: 4
  Current Site: Site A
  Last Modified: 2025-06-01T10:15:00Z

Remote Sync:
  Status: SYNCED
  Remote Version: 4
  Last Sync: 2025-06-01T10:15:05Z (5 seconds ago)

Validation:
  ✅ Versions match (4 = 4)
  ✅ Sync status is 'synced'
  ✅ Last sync is recent

Both sites have identical metadata.

Example 4 — Recover from a sync failure and force-sync

If the peer site was temporarily unreachable during a modification, the local version will be ahead of the remote version. Once the peer recovers, force a sync before making further changes.

# Check current status
openstack protector protection-group sync-status prod-web-app

Sync Status: ❌ OUT OF SYNC

Local Metadata:
  Version: 5
  Current Site: Site A
  Last Modified: 2025-06-01T10:20:00Z

Remote Sync:
  Status: FAILED
  Remote Version: 4
  Last Sync: 2025-06-01T10:15:05Z (5 minutes ago)
  Error: Connection timeout

Action Required:
  1. Check remote site connectivity
  2. Force sync once remote site is available

# Once the peer site is back online, force sync
openstack protector protection-group sync-force prod-web-app

Force Sync Initiated...

Checking remote site connectivity...
  ✅ Site B is reachable

Syncing metadata (version 5)...
  Gathering current metadata... ✓
  Calculating checksum... ✓
  Pushing to Site B... ✓

Remote Site Response:
  Status: success
  Version: 5
  Duration: 312ms

✅ Sync completed successfully
Both sites now at version 5

Example 5 — Remove a member and verify consistency group update

# Remove the web server from the Protection Group
curl -X DELETE \
  http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id>/members/<member-id> \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

Expected response (204 No Content) — no body is returned on successful deletion.

Verify the Consistency Group volume count decreased:

curl -X GET \
  http://<primary-controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id>/consistency-group \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

{
  "consistency_group": {
    "id": "cg-87654321-4321-4321-4321-87654321",
    "protection_group_id": "pg-12345678-1234-1234-1234-123456789abc",
    "name": "pg-prod-web-app-cg",
    "volume_type_id": "<replicated-ssd-uuid>",
    "volume_type_name": "replicated-ssd",
    "backend_name": "pure@backend-a",
    "primary_cg_id": "<cinder-cg-uuid-primary>",
    "secondary_cg_id": "<cinder-cg-uuid-secondary>",
    "status": "active",
    "volume_count": 5
  }
}

The volume_count reflects the volumes associated with the remaining members.

Issue: Protection Group creation fails with volume_type not replication-enabled

Symptom: The POST /v1/{tenant_id}/protection-groups request returns a 400 error stating the volume type does not support replication.

Likely cause: The Cinder volume type referenced by volume_type_id is missing the replication_enabled='<is> True' property, or the replication_type property is absent or misspelled.

Fix: Inspect the volume type on the primary site and correct the properties:

openstack volume type show replicated-ssd

# If missing, set the required properties:
openstack volume type set replicated-ssd \
  --property replication_enabled='<is> True' \
  --property replication_type='<in> async'

Repeat the check on the secondary site — the volume type must be correctly configured on both sites.

Issue: Protection Group creation fails with secondary site unreachable

Symptom: Creation returns an error indicating the secondary site cannot be contacted.

Likely cause: The protector-api service on the secondary site is down, or there is a network connectivity issue between the control planes.

Fix:

1. Confirm the secondary site's API service is running: systemctl status protector-api on the secondary controller.
2. Test reachability: curl http://<secondary-controller>:8788/
3. Check firewall rules — port 8788 must be open between the sites.
4. Verify the secondary site's auth_url in the site registration record is correct: openstack protector site show site-b

Issue: member-add fails with volume type mismatch

Symptom: Adding an instance to a Protection Group returns an error that one or more of the instance's volumes use an incompatible volume type.

Likely cause: The instance has volumes that were not created with the replication-enabled volume type referenced by the Protection Group.

Fix: All volumes attached to any member VM must use the same volume_type_id that was specified at Protection Group creation time. You have two options:

1. Migrate the non-compliant volumes to the correct volume type before adding the VM.
2. Retype the volumes using Cinder: openstack volume set --type replicated-ssd --retype-policy on-demand <volume-id>

Verify volume types before adding a VM:

openstack volume list --server <instance-id> -c ID -c Name -c Type

Issue: Modification blocked with remote site unreachable — cannot modify protection group

Symptom: An update, member-add, or member-remove operation fails with an error stating the remote site is unreachable and the operation is blocked.

Likely cause: This is expected behavior. The Protector service requires both sites to be reachable before allowing any modification, to prevent metadata version divergence between sites.

Fix:

1. Identify and resolve the connectivity issue to the peer site.
2. Once connectivity is restored, check the sync status: openstack protector protection-group sync-status <pg-name>
3. If the local version is ahead of the remote (from a failed sync), force-sync first: openstack protector protection-group sync-force <pg-name>
4. Retry the original modification.

Issue: Protection Group stuck in creating or deleting status

Symptom: A Protection Group has been in creating or deleting state for an extended period without transitioning.

Likely cause: The protector-engine service may have encountered an error during Cinder Consistency Group creation or deletion, or the engine service itself is not running.

Fix:

1. Check engine logs on the primary site: journalctl -u protector-engine -n 100 --no-pager
2. Check if the engine is running: systemctl status protector-engine
3. Look for Cinder errors — verify the Cinder Consistency Group exists or was removed as expected: check Cinder CG state via the OpenStack Cinder API.
4. If the engine has crashed, restart it: systemctl restart protector-engine — the engine will attempt to reconcile state on startup.

Issue: API returns 409 Conflict when deleting a Protection Group

Symptom: A DELETE request on a Protection Group returns HTTP 409.

Likely cause: The Protection Group still has active members, or it is currently in a non-active status (e.g., failed_over, failing_over, error).

Fix:

1. List and remove all members first:

openstack protector protection-group member-list <pg-name>
# For each member:
curl -X DELETE http://<controller>:8788/v1/$TENANT_ID/protection-groups/<pg-id>/members/<member-id> \
  -H "X-Auth-Token: $TOKEN" \
  -H "OpenStack-API-Version: protector 1.1"

2. If the group is in failed_over state, complete a failback first to return the group to active before deleting.
3. If the group is in error state, review the error details from the last DR operation: openstack protector operation list and resolve the underlying issue before retrying the delete.

Issue: sync-status shows OUT OF SYNC after failover

Symptom: Following an unplanned failover where the primary site was down, the sync status shows the remote version is behind.

Likely cause: This is expected. During an unplanned failover, the primary site was unreachable, so the post-failover metadata update could not be pushed. The local version on the secondary (now active) site is ahead.

Fix: Once the primary site recovers, push the current metadata:

openstack protector protection-group sync-force <pg-name>

You must complete this sync before making any modifications to the Protection Group or attempting a failback.