Installing on Other Supported OpenStack Distributions

This page describes how to install TrilioVault for OpenStack on non-RHOSP OpenStack distributions, including upstream OpenStack and community distributions such as Ubuntu OpenStack, SUSE OpenStack Cloud, and similar environments. You will install and configure the Workload Manager service components on your controller and compute nodes, register the service with Keystone, and verify that backup and restore operations are functional. Following this guide gives you a production-capable TrilioVault deployment that integrates with your existing OpenStack infrastructure without requiring a Red Hat-specific installation path.

Before you begin, ensure the following requirements are met:

OpenStack environment

• OpenStack release ≥ Stein
• OpenStack Keystone (identity service) operational
• OpenStack Nova (compute service) operational
• OpenStack Cinder (block storage service) operational
• OpenStack Horizon (dashboard) installed and operational — required only if you intend to use the horizon-tvault-plugin

Backup target — at least one of:

• NFS share reachable from all TrilioVault nodes and compute nodes
• S3-compatible object storage endpoint (supported from TrilioVault 3.0 onwards)
• OpenStack Swift endpoint

TrilioVault infrastructure

• One or three dedicated KVM hosts (bare-metal or hypervisor-hosted, but not VMs running under the same OpenStack cloud being protected)
• Each KVM host runs the TrilioVault QCOW2 image
• A cluster VIP (virtual IP address) allocated and routable — required even for single-node deployments; Pacemaker/HAProxy uses it and it is registered as the Keystone service endpoint
• Python ≥ 3.6 on any host used to run the workloadmgr CLI or automation scripts

Configuration management (optional, choose one or more)

• Ansible — for deploying via the playbooks bundled in triliovault-cfg-scripts
• Salt — for Salt state-based deployment
• Juju — for charm-based deployment

POSIX user alignment

• The nova user (UID and GID) must be identical across all TrilioVault cluster nodes and all OpenStack compute nodes; all backup target reads and writes are performed as nova:nova

Cinder quota headroom

• For every disk being backed up, Cinder quotas must allow for two additional Cinder snapshots and one temporary Cinder volume

RBAC

• The TrilioVault Trustee role must be assignable in Keystone; the OpenStack admin role cannot substitute for it

Credentials

• OpenStack admin credentials (admin user or equivalent) to create Keystone service and endpoint entries

The installation consists of four major phases: deploying the TrilioVault nodes, installing compute-node components, registering services with Keystone, and optionally installing the Horizon plugin and CLI. Work through every phase in order.

Phase 1 — Deploy TrilioVault nodes from the QCOW2 image

1. Obtain the TrilioVault QCOW2 image from your Trilio distribution channel and copy it to each dedicated KVM host.

2. Instantiate the VM on each KVM host. For a three-node HA cluster repeat this step on all three hosts; for a single-node deployment run it once.

   Copy

   # Example using virt-install on each KVM host
   virt-install \
     --name triliovault \
     --ram 16384 \
     --vcpus 8 \
     --disk path=/var/lib/libvirt/images/triliovault.qcow2,format=qcow2 \
     --import \
     --network bridge=br0 \
     --os-variant ubuntu20.04 \
     --noautoconsole
   

   Note: The TrilioVault node must not be instantiated as a VM under the OpenStack cloud it will protect. Use standalone KVM hosts only.

3. Log in to each TrilioVault node using the default credentials (admin / password) and change the password immediately.

   Copy

   ssh admin@<triliovault-node-ip>
   passwd admin
   

4. Configure networking on each node so that it can reach:

   • The OpenStack control plane (Keystone, Nova, Cinder endpoints)
   • All compute nodes
   • The backup target (NFS share, S3 endpoint, or Swift endpoint)
   • The cluster VIP subnet

5. Align the nova user UID and GID on each TrilioVault node to match the value on your compute nodes.

   Copy

   # Check the nova UID/GID on a compute node
   ssh <compute-node-ip> "id nova"
   
   # On each TrilioVault node, set matching values (example: UID=162, GID=162)
   usermod -u 162 nova
   groupmod -g 162 nova
   

Phase 2 — Configure the cluster using triliovault-cfg-scripts

The triliovault-cfg-scripts component provides Ansible playbooks, Salt states, and Juju charms. The steps below use the Ansible path; adapt if you use Salt or Juju.

6. Clone or extract triliovault-cfg-scripts on a workstation or jump host that has SSH access to all TrilioVault nodes and compute nodes.

   Copy

   git clone https://github.com/triliodata/triliovault-cfg-scripts.git
   cd triliovault-cfg-scripts
   

7. Create your inventory file listing the TrilioVault nodes and compute nodes.

   Copy

   # inventory/hosts
   [triliovault_nodes]
   tvault-node-1 ansible_host=192.168.10.11
   tvault-node-2 ansible_host=192.168.10.12
   tvault-node-3 ansible_host=192.168.10.13
   
   [compute_nodes]
   compute-01 ansible_host=192.168.10.21
   compute-02 ansible_host=192.168.10.22
   
   [triliovault_nodes:vars]
   cluster_vip=192.168.10.10
   

8. Edit the group variables to supply your OpenStack credentials, backup target details, and cluster VIP.

   Copy

   cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml
   vi inventory/group_vars/all.yml
   

   Key variables to set (see the Configuration section for full details):

   • openstack_auth_url
   • openstack_admin_username / openstack_admin_password / openstack_admin_project
   • backup_target_type (nfs, s3, or swift)
   • backup_target_path (NFS export path, S3 bucket URL, or Swift container)
   • cluster_vip
   • nova_uid / nova_gid

9. Run the configurator playbook. The playbook is idempotent and can be re-run at any time to apply changes.

   Copy

   ansible-playbook -i inventory/hosts site.yml
   

   The playbook will:

   • Install and configure wlm-api, wlm-scheduler, wlm-workloads, and wlm-cron on the TrilioVault nodes
   • Configure Pacemaker so that wlm-api and wlm-scheduler run on the master node only
   • Configure wlm-workloads to run on every TrilioVault node
   • Register the cluster VIP with Pacemaker/HAProxy
   • Create the Keystone service and endpoint entries pointing to the VIP

Phase 3 — Install compute-node components

10. Run the compute-node playbook to install the Nova API extension (contego) and data-mover agent on every compute node.

    Copy

    ansible-playbook -i inventory/hosts compute.yml
    

    This installs:

    • The TrilioVault Nova API extension, which exposes workload-aware snapshot hooks to wlm-workloads
    • The tvault-contego data-mover agent that reads volume data from each hypervisor and streams it to the backup target

11. Restart Nova services on each compute node to load the extension.

    Copy

    # Run on each compute node (adjust the service name to your distro)
    systemctl restart nova-compute
    

12. Verify the nova user UID/GID alignment on compute nodes matches the TrilioVault nodes (repeat the check from step 5 if needed).

Phase 4 — Register the Trustee role and assign it to users

13. Create the Trustee role in Keystone if it does not already exist.

    Copy

    openstack role create Trustee
    

14. Assign the Trustee role to every user or service account that will perform workload, snapshot, or restore operations. The OpenStack admin role is not a substitute.

    Copy

    openstack role add \
      --user <username> \
      --project <project-name> \
      Trustee
    

Phase 5 — Install the Horizon plugin (optional)

15. Run the Horizon plugin playbook on the host(s) running the OpenStack Horizon service.

    Copy

    ansible-playbook -i inventory/hosts horizon.yml
    

    This installs horizon-tvault-plugin, which adds the Workloads panel to Horizon.

16. Restart the Horizon web server to activate the plugin.

    Copy

    # Example for Apache-hosted Horizon
    systemctl restart apache2
    

Phase 6 — Install the workloadmgr CLI (optional)

17. Install workloadmanager-client on any workstation or jump host from which you want to run CLI commands.

    Copy

    pip install workloadmanager-client
    

18. Verify the installation.

    Copy

    workloadmgr --version
    

Phase 7 — Verify the deployment

19. Check service status on the master TrilioVault node.

    Copy

    # wlm-api and wlm-scheduler are cluster-controlled by Pacemaker
    pcs status
    
    # wlm-workloads runs on every node
    systemctl status wlm-workloads
    
    # wlm-cron runs on every node
    systemctl status wlm-cron
    

20. Confirm the Keystone endpoint is registered and pointing to the cluster VIP.

    Copy

    openstack endpoint list --service workloadmgr
    

21. List workloads using the CLI to confirm end-to-end connectivity.

    Copy

    workloadmgr workload-list
    

    A successful response (empty list or existing workloads) confirms that wlm-api is reachable and Keystone authentication is working.

After initial deployment you can tune TrilioVault behavior by editing configuration variables and re-running the Ansible configurator. Because the configurator is idempotent, re-running it with updated variables applies changes safely without disrupting existing workloads.

Backup target

Cluster and networking

OpenStack integration

Snapshot and retention behavior

Snapshot schedules and retention rules are defined per workload as Snapshot Policies rather than as global configuration. Each policy specifies:

• Frequency — how often wlm-cron triggers an automatic snapshot
• Retention count — how many snapshots to keep before the oldest is deleted

You set these through the Horizon Workloads panel or the workloadmgr CLI when creating or modifying a workload.

Email notifications

Email notifications are configured per tenant. Two conditions must be met:

1. The tenant user must have a valid email address on their OpenStack account.
2. An SMTP server must be configured by the backup administrator in the TrilioVault Dashboard.

Log in to the TrilioVault Dashboard at the cluster VIP (default credentials admin / password — change on first login) and navigate to Settings → SMTP to enter your mail server details.

File Recovery Manager image

To enable file-level (granular) restores from the Horizon UI, you must upload the File Recovery Manager Glance image and tag it correctly.

openstack image set \
  --property tvault_recovery_manager=yes \
  <file-recovery-manager-image-id>

Without this property, the image will not appear as a valid mount target in the Horizon UI.

Once TrilioVault is installed and services are running, your primary day-to-day workflows are: creating workloads, taking snapshots, restoring workloads or files, and managing snapshot policies. All workflows are available through either the Horizon Workloads panel or the workloadmgr CLI.

Creating a workload

A workload is the unit of protection — it groups one or more VMs and their attached volumes so they are backed up and restored as a consistent application unit. Each VM may belong to only one workload at a time.

Using the CLI:

workloadmgr workload-create \
  --name "my-application" \
  --instances <instance-id-1>,<instance-id-2> \
  --description "Production web tier"

Using Horizon: Navigate to Project → Workloads → Create Workload, select the VMs to include, and click Create.

Attaching a snapshot policy

Attach a snapshot policy to the workload to enable automatic, scheduled backups. The policy defines how often snapshots are taken and how many to retain.

workloadmgr workload-modify \
  --workload-id <workload-id> \
  --fullbackup-interval 7 \
  --retention-policy-value 30

This example schedules a full snapshot every 7 days and retains up to 30 snapshots. Older snapshots are deleted automatically by wlm-cron when the retention limit is reached.

Taking an on-demand snapshot

You can trigger a snapshot immediately outside of any schedule.

workloadmgr snapshot-create \
  --workload-id <workload-id> \
  --name "pre-upgrade-snapshot" \
  --description "Taken before package upgrade"

wlm-scheduler assigns the job to the appropriate node, and wlm-workloads executes the data capture. Incremental snapshots capture only changed blocks since the last backup; full snapshots capture all data committed to storage volumes, skipping zeroed or empty blocks.

Restoring a full workload

Restore an entire workload from a snapshot, either in-place or into a different OpenStack project.

workloadmgr workload-restore \
  --snapshot-id <snapshot-id> \
  --restore-type restore_to_new

Important: If the snapshot includes network topology data (all snapshots taken with TrilioVault 3.0 or later capture this automatically), the target project's network space must be completely empty of networking components before the restore begins. After the restore completes, you must manually connect the restored private networks to the public network.

Performing a file-level restore

When you need to recover only specific files rather than an entire VM, use the File Recovery Manager. Ensure the Glance image has the tvault_recovery_manager=yes property set (see Configuration).

In Horizon, navigate to Project → Workloads → Snapshots, select the snapshot, and choose File Recovery to mount the snapshot and browse its contents.

Monitoring snapshot jobs

List recent snapshots for a workload to check their status:

workloadmgr snapshot-list --workload-id <workload-id>

Snapshot statuses you will see:

• available — snapshot completed successfully
• in-progress — snapshot is actively running
• error — snapshot failed (see the Troubleshooting section)

Example 1 — Create a workload and verify it was registered

# Create the workload with two VMs
workloadmgr workload-create \
  --name "ecommerce-app" \
  --instances a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  --description "E-commerce frontend and database"

Expected output:

+------------------+--------------------------------------+
| Property         | Value                                |
+------------------+--------------------------------------+
| id               | 9f8e7d6c-5b4a-3210-fedc-ba9876543210 |
| name             | ecommerce-app                        |
| status           | available                            |
| description      | E-commerce frontend and database     |
| instances        | a1b2c3d4..., b2c3d4e5...            |
+------------------+--------------------------------------+

Example 2 — Take an on-demand snapshot and poll until complete

# Trigger the snapshot
workloadmgr snapshot-create \
  --workload-id 9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  --name "ecommerce-snapshot-$(date +%Y%m%d)"

Expected output immediately after submission:

+------------------+--------------------------------------+
| Property         | Value                                |
+------------------+--------------------------------------+
| id               | 1a2b3c4d-5e6f-7890-abcd-ef0123456789 |
| name             | ecommerce-snapshot-20240601          |
| status           | in-progress                          |
| workload_id      | 9f8e7d6c-5b4a-3210-fedc-ba9876543210 |
+------------------+--------------------------------------+

# Poll until status changes to 'available'
workloadmgr snapshot-show 1a2b3c4d-5e6f-7890-abcd-ef0123456789

Expected output when complete:

+------------------+--------------------------------------+
| Property         | Value                                |
+------------------+--------------------------------------+
| id               | 1a2b3c4d-5e6f-7890-abcd-ef0123456789 |
| name             | ecommerce-snapshot-20240601          |
| status           | available                            |
| size             | 42 GB                                |
| created_at       | 2024-06-01T14:32:00Z                 |
+------------------+--------------------------------------+

Example 3 — List all snapshots for a workload

workloadmgr snapshot-list \
  --workload-id 9f8e7d6c-5b4a-3210-fedc-ba9876543210

Expected output:

+--------------------------------------+------------------------------+-----------+---------------------+
| ID                                   | Name                         | Status    | Created At          |
+--------------------------------------+------------------------------+-----------+---------------------+
| 1a2b3c4d-5e6f-7890-abcd-ef0123456789 | ecommerce-snapshot-20240601  | available | 2024-06-01T14:32:00Z|
| 2b3c4d5e-6f7a-8901-bcde-f01234567890 | ecommerce-snapshot-20240525  | available | 2024-05-25T09:10:00Z|
+--------------------------------------+------------------------------+-----------+---------------------+

Example 4 — Restore a workload from a snapshot

workloadmgr workload-restore \
  --snapshot-id 1a2b3c4d-5e6f-7890-abcd-ef0123456789 \
  --restore-type restore_to_new \
  --name "ecommerce-restore-test"

Expected output:

+------------------+--------------------------------------+
| Property         | Value                                |
+------------------+--------------------------------------+
| id               | 3c4d5e6f-7a8b-9012-cdef-012345678901 |
| status           | in-progress                          |
| snapshot_id      | 1a2b3c4d-5e6f-7890-abcd-ef0123456789 |
+------------------+--------------------------------------+

Example 5 — Verify that the Keystone endpoint is registered at the cluster VIP

openstack endpoint list --service workloadmgr

Expected output:

+----------------------------------+-----------+--------------+--------------+---------+-----------+-----------------------------+
| ID                               | Region    | Service Name | Service Type | Enabled | Interface | URL                         |
+----------------------------------+-----------+--------------+--------------+---------+-----------+-----------------------------+
| abc123...                        | RegionOne | workloadmgr  | workloadmgr  | True    | public    | http://192.168.10.10:8780/v1|
| def456...                        | RegionOne | workloadmgr  | workloadmgr  | True    | internal  | http://192.168.10.10:8780/v1|
+----------------------------------+-----------+--------------+--------------+---------+-----------+-----------------------------+

The URL must point to your cluster VIP (192.168.10.10 in this example), not to an individual node IP.

Use the following log files as your primary diagnostic sources:

• wlm-api log: /var/log/workloadmgr/workloadmgr-api.log
• wlm-workloads log: /var/log/workloadmgr/workloadmgr-workloads.log
• Data-mover log: /var/log/nova/tvault-contego.log
• Nova API extension log: /var/log/nova/nova-api.log

Issue: workloadmgr workload-list returns a 401 Unauthorized error

Symptom: CLI commands fail with HTTP 401 or Authentication required.

Likely cause: The user does not have the Trustee role assigned in the target project, or the OpenStack credentials in the shell environment are incorrect.

Fix:

1. Confirm the Trustee role exists: openstack role list | grep Trustee
2. Assign it to the user: openstack role add --user <username> --project <project> Trustee
3. Verify your environment variables (OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME) are sourced correctly.
4. The admin OpenStack role cannot substitute for Trustee — both steps above are required.

Issue: Snapshot status stuck in in-progress and never transitions to available

Symptom: A snapshot remains in in-progress for an extended period with no progress.

Likely cause 1: wlm-workloads is not running on a TrilioVault node.

Fix: On each TrilioVault node run systemctl status wlm-workloads. If stopped, start it: systemctl start wlm-workloads. Check /var/log/workloadmgr/workloadmgr-workloads.log for errors.

Likely cause 2: The tvault-contego data-mover agent is not running on the compute node hosting the VM.

Fix: SSH to the relevant compute node and check: systemctl status tvault-contego. Restart if stopped: systemctl restart tvault-contego. Check /var/log/nova/tvault-contego.log.

Likely cause 3: Cinder quotas are exhausted — TrilioVault requires two Cinder snapshots and one temporary volume per disk per backup.

Fix: Check quota usage: openstack quota show <project>. Increase limits: openstack quota set --snapshots <new-limit> --volumes <new-limit> <project>.

Issue: Snapshot fails with an error related to the backup target

Symptom: Snapshot transitions to error status; the wlm-workloads log shows mount or permission errors against the backup target path.

Likely cause 1 (NFS): The NFS share is not mounted or the nova user UID/GID on the TrilioVault node does not match the NFS export's allowed UID.

Fix: Verify the NFS share is mounted and accessible as the nova user: sudo -u nova ls <backup_target_path>. Confirm UID/GID alignment: id nova on TrilioVault nodes versus compute nodes.

Likely cause 2 (S3): Incorrect s3_access_key or s3_secret_key, or the endpoint is unreachable from TrilioVault nodes.

Fix: Test connectivity: curl -v <s3-endpoint>. Re-run the Ansible configurator with corrected credentials.

Issue: Network topology restore fails immediately

Symptom: A restore operation that includes network topology data fails at start with a conflict error.

Likely cause: The target project already has networking components (networks, subnets, routers, ports, or floating IPs) present.

Fix: Completely clear the target project's network space before retrying — remove all ports, floating IPs, router interfaces, routers, subnets, and networks in that project. Then re-run the restore. After a successful restore, manually connect the restored private networks to the public network, as TrilioVault does not perform this final step automatically.

Issue: Horizon Workloads panel does not appear after plugin installation

Symptom: The Horizon dashboard does not show a Workloads panel after running the horizon.yml playbook.

Likely cause: The Horizon web server was not restarted after the horizon-tvault-plugin was installed, or the plugin files were not installed in the expected Horizon plugin directory.

Fix:

1. Restart the web server: systemctl restart apache2 (or nginx/httpd depending on your distribution).
2. Confirm the plugin is installed: pip show horizon-tvault-plugin.
3. Clear the browser cache and reload Horizon.
4. Check the Horizon error log for import errors related to the plugin.

Issue: wlm-api or wlm-scheduler is not running after node reboot

Symptom: API calls return connection refused; Pacemaker shows wlm-api or wlm-scheduler as stopped.

Likely cause: These services are cluster-controlled by Pacemaker and run only on the master node. A failover or quorum issue may prevent them from starting.

Fix:

1. Check cluster status: pcs status
2. Look for quorum or fencing errors in Pacemaker logs: journalctl -u pacemaker
3. If the cluster has quorum and the resource is in a failed state, clean and restart it:
   Copy

   pcs resource cleanup wlm-api
   pcs resource cleanup wlm-scheduler
   

4. Do not attempt to start wlm-api or wlm-scheduler directly with systemctl — always let Pacemaker manage them.