Enrollment

The enrollment subsystem registers an S3 bucket as a usable backup target by running a sequence of automated checks and then initializing a Kopia repository inside the bucket. Use enrollment whenever you add a new BackupTarget to a Domain: Abacá runs preflight conformance checks, generates a cryptographically-random repository password stored exclusively in Barbican, and calls kopia repository create (or connects to an existing repository when adopting). The result is a BackupTarget in active status, ready to accept backup jobs.

Enrollment is modelled as a standard Abacá target_enroll job and passes through the shared job state machine. In production the abaca-api casts the job to abaca-conductor via oslo.messaging; the conductor drives the state machine and a worker VM executes the Kopia operations.

The parameters below apply to execute_enroll_job (the internal orchestrator) and to the fields that must be populated on a BackupTarget before enrollment can proceed. When you trigger enrollment through the API or CLI, these fields are drawn from the target record and the associated Barbican secrets.

Dispatch configuration ([enrollment] config group)

Kopia executor configuration ([kopia] config group)

On success, execute_enroll_job returns the terminal JobState value available and produces the following side effects:

• job.state → available, job.progress → 100, job.started_at and job.ended_at populated.
• target.status → active (BucketStatus.ACTIVE).
• target.preflight_detail — a dict recording the outcome of every preflight check, suitable for operator inspection.
• target.preflight_at — UTC timestamp of the preflight run.
• target.capabilities — merged capability dict from the preflight result (e.g. object_lock_enabled, versioning_enabled, existing_repo_adoptable).
• target.kopia_key_ref — Barbican href for the repository password (written before kopia repository create is called, so the ref is durable even if the job dies mid-flight).

Repository adoption path: when preflight detects an existing Kopia repository in the bucket (capability existing_repo_adoptable: true), bootstrap calls kopia repository connect instead of kopia repository create. The resulting capabilities update records repository_adopted: true; the kopia_encryption and kopia_block_hash capability fields are set to null because Abacá did not create the repository and cannot assert its crypto profile.

On failure, execute_enroll_job returns error and mutates target.status to one of:

The job.error_category field is set to tenant_action_required or operator_action_required depending on which exception terminated the state machine (see the Throws section).

The following exceptions are raised internally by the enrollment job. They are caught by the state machine and translated into job error states; you will not see Python tracebacks in the API response, but the error_code, error_title, and error_category fields on the Job resource reflect them.

Startup guard — DispatchConfigurationError: this exception (a SystemExit subclass) is raised by validate_dispatch_config at process startup, not during a job run. It fires when [enrollment] dispatch=inline and [api] noauth=False are set simultaneously. The process exits non-zero without a stack trace. Correct this by setting dispatch=rpc in your abaca.conf.

Trigger enrollment via the OpenStack CLI

After registering a bucket as a BackupTarget, trigger enrollment by requesting the enroll action. Enrollment runs asynchronously; poll the returned job ID for completion.

# Enroll the target — returns a job ID immediately
openstack share protection target enroll <target-id>

# Poll the job until state is 'available' or 'error'
openstack share protection job show <job-id>

Expected output when enrollment succeeds:

+------------------+--------------------------------------+
| Field            | Value                                |
+------------------+--------------------------------------+
| id               | 7f3a1c2e-...                         |
| type             | target_enroll                        |
| state            | available                            |
| progress         | 100                                  |
| error_category   | None                                 |
| started_at       | 2025-03-14T09:00:00Z                 |
| ended_at         | 2025-03-14T09:01:43Z                 |
+------------------+--------------------------------------+

Expected output when preflight fails:

+------------------+--------------------------------------+
| Field            | Value                                |
+------------------+--------------------------------------+
| id               | 7f3a1c2e-...                         |
| type             | target_enroll                        |
| state            | error                                |
| error_code       | abaca.enrollment.preflight_failed    |
| error_category   | tenant_action_required               |
| error_detail     | preflight failed: lifecycle_rules -> |
|                  | bucket has lifecycle rules that      |
|                  | would delete live backup data        |
+------------------+--------------------------------------+

Check the target's preflight detail after a failed enrollment

The preflight_detail field on the target records every check result, not just the first failure. Inspect it to understand which checks passed and which failed.

openstack share protection target show <target-id> -f json | jq '.preflight_detail'

Example output:

{
  "checks": [
    {"name": "reachability",     "result": "pass", "detail": null},
    {"name": "versioning",       "result": "pass", "detail": null},
    {"name": "object_lock",      "result": "pass", "detail": null},
    {"name": "lifecycle_rules",  "result": "fail",
     "detail": "bucket has lifecycle rules that would delete live backup data",
     "category": "tenant_action_required"}
  ]
}

Re-enroll after correcting a preflight failure

Fix the underlying issue (for example, remove conflicting S3 lifecycle rules) and then re-enroll. Abacá runs the full preflight again from the start.

# After fixing the bucket, re-enroll
openstack share protection target enroll <target-id>

# Confirm the target reaches 'active' status
openstack share protection target show <target-id> -f value -c status
# active

Repository adoption (disaster recovery)

If you are rebuilding the control plane from database loss and pointing Abacá at a bucket that already contains a Kopia repository, enrollment detects the existing repository (via the existing_repo_adoptable capability) and calls kopia repository connect instead of kopia repository create. You must have previously stored the repository password in Barbican under the target's kopia_key_ref; if that Barbican secret is lost, enrollment fails with RepositoryPasswordRequired and there is no recovery path (Kopia repositories are client-side encrypted).

# Adoption is automatic when preflight detects an existing Kopia repo.
# Trigger enrollment the same way:
openstack share protection target enroll <target-id>

# Verify the adopted capability on success:
openstack share protection target show <target-id> -f json | jq '.capabilities.repository_adopted'
# true

Inspect enrollment dispatch configuration (operator)

Verify that your deployment uses rpc dispatch. The inline mode is a unit-test harness and will be refused at startup if [api] noauth=False.

# /etc/abaca/abaca.conf
[enrollment]
dispatch = rpc

[kopia]
# Must be 'http' in production — credentials stay inside worker VMs.
executor = http

If you see the following in the API pod logs at startup, the configuration is unsafe and the process has exited:

REFUSE TO START: [enrollment] dispatch=inline is a unit-test harness, not a
deployment mode. This process has [api] noauth=False (real auth) — inline
dispatch would bypass the conductor / worker separation that the R1 threat
model depends on. Set [enrollment] dispatch=rpc or run with --noauth
(dev/test only).

State machine mapping for enrollment jobs

Enrollment reuses the shared JobStateMachine. The provisioning_network and provisioning_source stages are no-ops (enrollment involves no Manila share and no network attachment). All meaningful work happens in the later stages:

Repository password is written before Kopia runs. The kopia_key_ref Barbican href is persisted to the database (via on_password_stored) before kopia repository create is called. This ordering is intentional: if the job dies between creating the repository and returning, a retry can re-read the same password from Barbican and call kopia repository connect rather than generating a new password and failing because the bucket already has a repository. If the order were reversed, a mid-flight crash would leave an encrypted repository whose password exists nowhere durable.

Secret material never travels through the conductor process in production. The [kopia] executor = http setting means S3 credentials and the repository password are fetched inside the worker VM, not in the conductor. Setting executor = ephemeral_container causes a startup warning and MUST NOT be used in production; it would cause credentials to enter the conductor process, violating the threat model.

dispatch=inline is refused in production. validate_dispatch_config is called explicitly from every process entry point (abaca-api and abaca-conductor). It raises DispatchConfigurationError (a SystemExit subclass) if dispatch=inline and [api] noauth=False are both set. There is no import-time check — the validation is intentionally visible in the main functions of each entry point.

Error categories guide who must act. Every enrollment error carries an error_category of either tenant_action_required or operator_action_required. Preflight failures inherit their category from the specific failing check: a missing IAM permission or a lifecycle rule that would delete backup data is tenant_action_required; an S3 backend outage is operator_action_required. Post-preflight failures (Kopia repository create) are operator_action_required.

target.status transitions on failure are distinct. A target that fails during preflight (or because inputs are missing) moves to preflight_failed. A target that passes preflight but fails during or after repository creation moves to enroll_failed. This distinction prevents an operator from misreading a Kopia failure as a bucket-conformance issue when inspecting the Dashboard or the openstack share protection target show output.

Adopted repositories do not carry a FIPS profile assertion. When enrollment connects to an existing Kopia repository (adoption path), capabilities.kopia_encryption and capabilities.kopia_block_hash are set to null. Abacá cannot assert that a repository it did not create uses FIPS-approved algorithms. If FIPS compliance is a requirement, create a fresh bucket and enroll it from scratch.

executed_by field records which path ran. After a successful enrollment job, job.executed_by is set to conductor:<hostname> for the production RPC path. The value inline:<hostname> indicates the unit-test harness ran the job on the API thread. The worker: prefix is reserved for a future release and is not set by any production code path today.