Intended Audience

This page describes who Trilio Share Protection for OpenStack (Abacá) is built for, what each audience is expected to know before using it, and which parts of the documentation are most relevant to their work. Understanding the intended audience helps you navigate to the right starting points and set accurate expectations about the knowledge and access rights the documentation assumes.

Abacá serves two distinct audiences. Their responsibilities, required background knowledge, and points of contact with the service differ significantly, so this page treats them separately before describing the small area where their concerns overlap.

OpenStack operators

Operators are the people responsible for deploying, configuring, and maintaining Abacá on a RHOSO 18 or later cluster. If you are an operator, you will:

• Run the bash install scripts under deploy/rhoso/ to register Abacá's Keystone identity, provision its dedicated MySQL/MariaDB database and RabbitMQ broker, upload the worker VM image to Glance, and deploy the abaca-api and abaca-conductor pods into the abaca OpenShift namespace using kustomize.
• Manage the control-plane configuration through oslo.config INI files, tuning options across sections such as [conductor], [worker], [kopia], and [database].
• Build and register worker VM images using deploy/rhoso/worker/20-worker-image.sh, which installs Kopia, NFS utilities, and the abaca-worker-agent into a RHEL base cloud image and uploads it to Glance with the abaca_worker_image=1 property.
• Use abaca-manage for database schema migrations (db_sync) and disaster-recovery operations such as rebuild-from-repository, which reconstructs the Abacá database catalog from Kopia repositories in S3 when the database is lost.
• Register Keystone Domains and their associated service projects, configure access-control policy overrides via policy.yaml, and monitor worker fleet health and backup coverage through the Admin panel in abaca-dashboard or directly through the API.
• Diagnose degraded or stuck jobs by inspecting job state machine transitions, reconciliation loop output from abaca-conductor, and worker agent logs.

Operators are expected to be comfortable with OpenShift and Kubernetes workloads, OpenStack service deployment conventions (Keystone catalog registration, oslo.config, oslo.policy), and basic S3 object storage administration. You do not need to understand Kopia internals to operate Abacá, but you should understand that the Kopia repositories in S3 are the durable source of truth for backup data — the MySQL database holds only metadata pointers.

Operators are responsible for infrastructure decisions that tenants cannot change after the fact, most importantly whether an S3 bucket was created with versioning and S3 Object Lock enabled. Object Lock must be enabled at bucket creation time; it cannot be retrofitted. This makes pre-enrollment bucket validation a critical operator responsibility even when tenants supply their own buckets.

Developers integrating with the API

Developers are people who build automation, scripts, or applications that call the Abacá API programmatically. If you are a developer, you will interact with Abacá through one or more of the three supported surfaces:

• The openstack share protection CLI, provided by the python-abacaclient package, which adds openstack share protection … subcommands to the standard OpenStack CLI.
• The REST API under /v1, which is Keystone-authenticated and follows OpenStack conventions including service catalog discovery, token-based auth, and consistent JSON error envelopes with an error_category field of either tenant_action_required or operator_action_required.
• The Python SDK in python-abacaclient, a thin HTTP client that wraps the REST API and is suitable for use in scripts and automation.

Developers are expected to be familiar with OpenStack authentication (Keystone tokens, domain-scoped tokens, trusts), the OpenStack CLI conventions, and how to discover service endpoints from the service catalog. You do not need to know how worker VMs are provisioned or how Kopia repositories are structured internally to call the API effectively.

Developers who are building tenant-facing integrations should pay particular attention to the concept of a BackupTarget and the Enrollment process, since creating a usable backup target requires a worker VM to run conformance preflight checks against the S3 bucket before the target is ready. This means target creation is an asynchronous operation that produces a Job you must poll to completion before attaching a Policy to a share.

Developers who are building operator tooling — for example, a chargeback system reading the usage API, or a monitoring system tracking job states across a fleet — should also understand the Domain owner role (abaca_domain_owner), which gates access to Domain-level resources such as target templates and per-Domain service project registrations.

Where the two audiences overlap

Both operators and developers need to understand the Job state machine: the sequence queued → provisioning_network → provisioning_source → connecting_repository → transferring → finalizing → releasing → available | error applies to every backup, restore, enrollment, and maintenance run. Operators use this to diagnose stuck or failed jobs; developers use it to write correct polling logic and to interpret the error_category field that signals whether a failure requires tenant action or operator intervention.

Both audiences also need to understand the trust model: Abacá never stores S3 credentials or Kopia repository passwords in its own database. All secret material lives in OpenStack Barbican as secret references (hrefs). Keystone trusts allow the Abacá service user to act on behalf of tenants for specific, revocable operations — a design choice that lets tenants revoke access at any time without requiring operator involvement.

The following examples illustrate the two primary interaction patterns — one for operators managing the service, one for developers calling the API.

Operator: verify control-plane pod status after deployment

After running the RHOSO install scripts, confirm that the API and conductor pods are running in the abaca namespace:

oc get pods -n abaca

Expected output (names will include generated suffixes):

NAME                               READY   STATUS    RESTARTS   AGE
abaca-api-7d8f9b6c4-xkqpz          1/1     Running   0          4m
abaca-conductor-5b7c9d8f6-rzlmn    1/1     Running   0          4m

Operator: run a database schema migration

Schema migrations are applied by running abaca-manage db_sync before the service pods start. In a kustomize deployment this runs as a Kubernetes Job automatically; you can also invoke it manually for verification:

oc exec -n abaca deploy/abaca-api -- abaca-manage db_sync

Developer: list available backup targets using the CLI

With python-abacaclient installed and your OpenStack credentials sourced, list backup targets registered in the current project's Domain:

openstack share protection target list

Expected output:

+--------------------------------------+----------+-----------+
| ID                                   | Name     | Status    |
+--------------------------------------+----------+-----------+
| a1b2c3d4-e5f6-7890-abcd-ef1234567890 | primary  | available |
+--------------------------------------+----------+-----------+

Developer: request an on-demand backup using the REST API

Using a Keystone token obtained via standard OpenStack authentication, request a backup of a share:

curl -s -X POST https://<abaca-api-endpoint>/v1/backups \
  -H "X-Auth-Token: $OS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_id": "<manila-share-uuid>", "target_id": "<backup-target-uuid>"}'

The API returns a Job record. Poll the job until it reaches a terminal state:

curl -s https://<abaca-api-endpoint>/v1/jobs/<job-uuid> \
  -H "X-Auth-Token: $OS_TOKEN"

A successful backup job reaches state available. A failed job reaches error and includes an error_category field — tenant_action_required or operator_action_required — to direct the response.

• Architecture overview — explains how the control plane (abaca-api, abaca-conductor), worker VMs, and Kopia repositories relate to one another, and why the S3 repository is the source of truth rather than the MySQL database.
• Deployment guide (RHOSO) — step-by-step instructions for operators deploying the control plane using kustomize and the deploy/rhoso/ scripts.
• Building and registering the worker VM image — covers deploy/rhoso/worker/20-worker-image.sh, the abaca_worker_image=1 Glance property, and why worker VMs must not fetch packages from the internet at boot.
• Backup targets and enrollment — describes the BackupTarget and BackupTargetTemplate concepts, the preflight conformance check, S3 Object Lock requirements, and the asynchronous enrollment job.
• Protection policies — explains how to bind a Manila share to a target template with a cron schedule and retention rules.
• Job state machine — reference for the lifecycle states every backup, restore, and enrollment job passes through, including how to interpret error_category in failure responses.
• API reference — complete reference for all /v1 endpoints, request/response schemas, and authentication requirements.
• openstack share protection CLI reference — full listing of openstack share protection … subcommands provided by python-abacaclient.
• Access control and policy — documents the abaca_domain_owner role, default oslo.policy rules, and how operators override them via policy.yaml.
• Monitoring and chargeback — describes the usage API surface and job statistics available to operators building metering or alerting integrations.