Ansible Collection

The plakarkorp.plakar collection drives Plakar Control Plane (PCP) from Ansible playbooks. It triggers backups, restores, syncs, checks and prunes, reads job state, and declares the stores, connectors, inventories and organizations those operations run against.

Every module talks HTTPS to the PCP API. Nothing is installed on or run against the managed hosts, so plays target localhost, or use delegate_to when the surrounding play is aimed elsewhere.

PCP performs every backup, restore, sync and check itself, as it does when one of its own schedules triggers the work. The modules ask it to, and report the result.

Installing the collection

$ ansible-galaxy collection install plakarkorp.plakar

The collection requires ansible-core 2.15 or later.

For Red Hat Ansible Automation Platform, add the collection to an execution environment. The collection repository ships an execution-environment.yml for this:

$ ansible-builder build -t plakar-ee .

Point your job templates at the resulting image, and supply PLAKAR_API_URL and PLAKAR_API_KEY through a credential type or the job’s environment.

Authentication

The collection authenticates with an API key belonging to an application user, the account type intended for automation. Keys carry the pcp_ak_ prefix, are shown once when minted, and belong to the organization they were minted in. An application user cannot mint its own key, so this is done from the web interface.

Create the service account, grant it a role, and mint its key. The Operator role suits a playbook that runs work already defined in PCP.

Point the collection at the deployment with module arguments, or with the PLAKAR_API_URL and PLAKAR_API_KEY environment variables:

- hosts: localhost
  gather_facts: false
  environment:
    PLAKAR_API_URL: https://pcp.example.com
    PLAKAR_API_KEY: "{{ vault_plakar_api_key }}"

Acting on another organization

An API key is bound to one organization, and the collection acts there by default. Setting organization_id on a task re-scopes it server-side for that task, using the same key, and requires the account to be a member of the organization it names.

The organization modules also accept an organization name, which acts on a tenant beneath the key’s own organization without re-scoping.

Modules

Module names are written in full in a playbook, as plakarkorp.plakar.backup. Every option of every module is listed in the Ansible collection reference, and each module documents itself:

$ ansible-doc plakarkorp.plakar.backup

Beyond the options particular to a module, all of them take api_url, api_key, organization_id, validate_certs and timeout. The modules that trigger work also take wait, wait_timeout and edge_tags.

Objects are addressed by name

Modules refer to stores, connectors, inventories and organizations by name, and resolve those names within the organization when the task runs. Nothing has to be looked up first or carried between tasks.

The declarative modules manage only the options the playbook sets. Any other value the object holds in PCP keeps whatever it has, so removing an option from a task stops managing it rather than clearing it.

A worked example

- hosts: localhost
  gather_facts: false
  environment:
    PLAKAR_API_URL: https://pcp.example.com
    PLAKAR_API_KEY: "{{ vault_plakar_api_key }}"
  tasks:
    - name: Back up the production database
      plakarkorp.plakar.backup:
        source: Production DB
        store: S3 Store
        labels: [nightly]

    - name: Replicate the store offsite
      plakarkorp.plakar.sync:
        store: S3 Store
        to_store: Offsite S3

    - name: Report any backup that failed today
      plakarkorp.plakar.job_info:
        task_type: backup
        status: failed
      register: failed

The play targets localhost because the modules call the PCP API rather than the database being backed up. PCP reaches the source itself, from the appliance or from an edge.

Using the modules