# Ansible collection reference This page lists every option of every module in the `plakarkorp.plakar` Ansible collection. For an introduction to what these modules do and how a playbook uses them, see [Ansible Collection](../../infrastructure-as-code/ansible). Module names are written in full in a playbook. The `backup` module below is `plakarkorp.plakar.backup` in a task. ## Modules > [!NOTE] > > All modules talk only to the Plakar management API over HTTPS; nothing runs on > the managed hosts, so plays typically target `localhost` or use `delegate_to`. ### backup Trigger a Plakar backup. Triggers an on-demand backup of a source connector into a store, through the Plakar management API. Connectors are addressed by name; names are resolved within the organization at run time. The run is asynchronous server-side. By default the module polls until the job stops and fails unless it succeeded. **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `edge_tags` | list of str | No | | Select a remote edge by tags (all must match) to execute the job, falling back to local execution when no edge matches. | | `ignores` | list of str | No | | Path patterns to exclude from the backup. | | `labels` | list of str | No | | Labels to attach to the resulting snapshot. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `source` | str | Yes | | Name of the source connector to back up. | | `store` | str | Yes | | Name of the store connector to back up into. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | | `wait` | bool | No | `true` | Whether to wait for the triggered job to finish. When false, the module returns as soon as the run is accepted; poll it later with `plakarkorp.plakar.job_info`. | | `wait_timeout` | int | No | `600` | Seconds to wait for the job to finish before failing. | **Returns** | Key | Type | Returned | Description | | ------- | ---- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `at_id` | str | always (except check mode) | Identifier of the one-shot run (the scheduler's `at` entry). | | `job` | dict | when available | The job the run materialized into. Only present once the scheduler picked the run up — with `wait=false` it may be absent. | | `log` | str | on job failure | Plain-text job log, fetched when the job did not succeed. | **Keys of `job`** | Key | Type | Returned | Description | | ------------ | ---- | -------- | -------------------------------------------------------------- | | `id` | str | | Job id, usable with `plakarkorp.plakar.job_info`. | | `started_at` | str | | When the job started, if it did. | | `status` | str | | One of `queued`, `running`, `canceled`, `succeeded`, `failed`. | | `stopped_at` | str | | When the job stopped, if it did. | ### check Verify the integrity of Plakar snapshots. Triggers an on-demand integrity check of the snapshots held in a store, through the Plakar management API. The store is addressed by name and resolved within the organization at run time. Without `snapshot_id` the whole store is checked. The run is asynchronous server-side. By default the module polls until the job stops and fails unless it succeeded — a failed check means the data did not verify. **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `edge_tags` | list of str | No | | Select a remote edge by tags (all must match) to execute the job, falling back to local execution when no edge matches. | | `labels` | list of str | No | | Only check snapshots carrying these labels. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `snapshot_id` | str | No | | Check only this snapshot. | | `store` | str | Yes | | Name of the store whose snapshots to verify. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | | `wait` | bool | No | `true` | Whether to wait for the triggered job to finish. When false, the module returns as soon as the run is accepted; poll it later with `plakarkorp.plakar.job_info`. | | `wait_timeout` | int | No | `600` | Seconds to wait for the job to finish before failing. | **Returns** | Key | Type | Returned | Description | | ------- | ---- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `at_id` | str | always (except check mode) | Identifier of the one-shot run (the scheduler's `at` entry). | | `job` | dict | when available | The job the run materialized into. Only present once the scheduler picked the run up — with `wait=false` it may be absent. | | `log` | str | on job failure | Plain-text job log, fetched when the job did not succeed. | **Keys of `job`** | Key | Type | Returned | Description | | ------------ | ---- | -------- | -------------------------------------------------------------- | | `id` | str | | Job id, usable with `plakarkorp.plakar.job_info`. | | `started_at` | str | | When the job started, if it did. | | `status` | str | | One of `queued`, `running`, `canceled`, `succeeded`, `failed`. | | `stopped_at` | str | | When the job stopped, if it did. | ### connector Manage Plakar source and destination connectors. Creates, updates and deletes source and destination connectors in the Plakar management API. For stores, use `plakarkorp.plakar.store` instead. Connectors are matched by name within the organization; the name is the playbook's key, so it must be unique per connector type. Only the options the playbook sets are managed on update; anything else keeps its current server-side value. **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `data_classes` | list of str | No | | Data classes the connector carries. | | `endpoints` | list of str | No | | Endpoint names the connector reaches its resource through. | | `environment` | str | No | | Environment label, for example `production`. | | `fields` | dict | No | | Integration-specific configuration, as a mapping of field name to value. A value may also be a mapping with `value` and an optional `provider_id` naming a secret provider. On update, only the fields named here are compared and replaced; other existing fields are preserved. | | `integration` | str | No | | Name of the installed integration backing the connector, for example `s3` or `sftp`. Required when creating. | | `name` | str | Yes | | Name of the connector. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `protocol` | str | No | | Protocol spoken to the resource, for example `s3` or `sftp`. Defaults to the integration name, which matches for the standard integrations; set it only when they differ. | | `resource` | str | No | | URN or name of the inventory resource the connector attaches to. Required when creating. | | `state` | str | No | `present` | Whether the connector should exist. One of `present`, `absent`. | | `temperature` | str | No | | Storage temperature. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `type` | str | Yes | | What the connector is used for. One of `source`, `destination`. | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ----------- | ----------- | ---------------------------------------- | ---------------------------------------------------------------- | | `connector` | dict | when the connector exists or was created | The connector acted on (a summary; field values are not echoed). | | `diff_keys` | list of str | on update | The option names whose values differed and drove the update. | ### grant Manage role grants in a Plakar organization. Grants a role to a member of an organization, and revokes it. A grant is one (subject, role) pair; a member can hold several. The module manages exactly the pair the playbook names and touches nothing else the subject holds. The subject must already be a member — see `plakarkorp.plakar.member`. The role names come from the server's catalogue; the standard tier is `owner`, `administrator`, `operator` and `auditor`. An unknown role fails with the catalogue's list. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `organization` | str | No | | Name of the organization the grant lives in. Defaults to the API key's own organization. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `role` | str | Yes | | Name of the role, as the catalogue spells it, for example `operator` or `backup-operator`. | | `state` | str | No | `present` | Whether the grant should exist. One of `present`, `absent`. | | `subject` | str | Yes | | Who holds the grant — a member's email address, or the name of a service account (which has no address). | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ------- | ---- | ------------------------------------ | --------------------------------------- | | `grant` | dict | when the grant exists or was created | The grant acted on (id, subject, role). | ### inventory Manage Plakar inventories. Creates, updates and deletes inventories in the Plakar management API. An inventory watches what a provider holds (AWS, Scaleway, GCP, OVH, VMware, Kubernetes) or, for the `self-managed` type, holds resources a playbook declares itself with `plakarkorp.plakar.inventory_resource`. Inventories are matched by name within the organization; the name is the playbook's key, so it must be unique. The type is immutable once created. Only the configuration keys the playbook sets are managed on update; anything else keeps its current server-side value. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `configuration` | dict | No | | Provider-specific configuration, as a flat mapping of field name to value. A value may also be a mapping with `value` and an optional `provider_id` naming a secret provider. Keys per type — `aws`: `credentials_type` (`iam` or `access_key`), `region`, `access_key`, `secret_access_key`; `scaleway`: `scw_project_id`, `scw_access_key`, `scw_secret_key`; `gcp`: `gcp_project_id`, `gcp_service_account_json`; `ovh`: `application_key`, `application_secret`, `consumer_key`, `endpoint`; `k8s`: `k8s_kubeconf`; `vmware`: `vsphere_server`, `vsphere_username`, `vsphere_password`, `vsphere_tls_skip_verify`, `vsphere_tls_ca_bundle`. The `self-managed` type takes no configuration. | | `name` | str | Yes | | Name of the inventory. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `state` | str | No | `present` | Whether the inventory should exist. One of `present`, `absent`. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `type` | str | No | | Provider backing the inventory. Required when creating; immutable afterwards. One of `aws`, `gcp`, `k8s`, `ovh`, `scaleway`, `self-managed`, `vmware`. | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ----------- | ----------- | ---------------------------------------- | ------------------------------------------------------------------------ | | `diff_keys` | list of str | on update | The configuration keys whose values differed and drove the update. | | `inventory` | dict | when the inventory exists or was created | The inventory acted on (a summary; configuration values are not echoed). | ### inventory_info Read Plakar inventories and their resources. Lists the organization's inventories, or reads one inventory by name with its coverage summary and, optionally, its resources. Configuration values (provider credentials) are never echoed. **Options** | Option | Type | Required | Default | Description | | ------------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `include_resources` | bool | No | `false` | Also return the resources of the inventory named by `name`. | | `name` | str | No | | Name of one inventory to read. Without it, all visible inventories are listed. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ------------- | ------------ | -------------------------------- | ----------------------------------------------------------- | | `inventories` | list of dict | when `name` is not set | The visible inventories, with resource counts and coverage. | | `inventory` | dict | when `name` is set | The inventory named by `name`, with coverage and summaries. | | `resources` | list of dict | when `include_resources` is true | The inventory's resources. | ### inventory_resource Manage resources in a self-managed Plakar inventory. Declares, updates and deletes resources in a self-managed inventory (see `plakarkorp.plakar.inventory`). Provider-backed inventories are read-only; their resources come from synchronization. Resources are matched by URN within the inventory; the URN is the playbook's key and is immutable. Only the options the playbook sets are managed on update; anything else keeps its current server-side value. **Options** | Option | Type | Required | Default | Description | | ------------------------ | ----------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `class` | str | No | | Resource class, for example `object-storage` or `virtual-machine`. Required when creating. | | `endpoints` | list of str | No | | Endpoints the resource is reachable at, as hostnames or IP addresses. | | `excluded_from_coverage` | bool | No | | Whether the resource is left out of coverage accounting. | | `inventory` | str | Yes | | Name of the self-managed inventory holding the resource. | | `name` | str | No | | Display name of the resource. Required when creating. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `service` | str | No | | Service the resource belongs to. | | `state` | str | No | `present` | Whether the resource should exist. One of `present`, `absent`. | | `subclass` | str | No | | Resource subclass, for example `s3`. | | `tags` | list of str | No | | Tags on the resource. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `urn` | str | Yes | | URN identifying the resource, for example `urn:res-web-tier`. | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ----------- | ----------- | --------------------------------------- | ------------------------------------------------------------ | | `diff_keys` | list of str | on update | The option names whose values differed and drove the update. | | `resource` | dict | when the resource exists or was created | The resource acted on (a summary). | ### inventory_sync Synchronize a Plakar inventory against its provider. Triggers a synchronization of an inventory, re-reading what its provider holds and updating the resource set accordingly. The call is synchronous and returns once the provider has been consulted. A sync always re-reads the provider, so the task always reports changed. Self-managed inventories hold only what playbooks declare (`plakarkorp.plakar.inventory_resource`); syncing one succeeds without effect. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `name` | str | Yes | | Name of the inventory to synchronize. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ----------- | ---- | -------- | ------------------------------------ | | `inventory` | dict | always | The inventory that was synchronized. | ### job_info Query Plakar job state. Reads job state from the Plakar management API, either one job by id or a filtered list. Never changes anything. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `at_id` | str | No | | Return the job of this one-shot run, as returned in `at_id` by `plakarkorp.plakar.backup` and `plakarkorp.plakar.restore`. While the scheduler has not yet materialized the run into a job, the module returns an empty `jobs` list — poll with `until`. | | `include_log` | bool | No | `false` | Also fetch each returned job's plain-text log. Meant for a single job or a narrow filter; logs are fetched one request per job. | | `job_id` | str | No | | Return exactly this job. Mutually exclusive with the list filters. | | `limit` | int | No | `50` | Maximum number of jobs to return. | | `offset` | int | No | `0` | Pagination offset. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `status` | str | No | | Only jobs in this state. One of `queued`, `running`, `canceled`, `succeeded`, `failed`. | | `task_type` | str | No | | Only jobs of this task type. One of `backup`, `restore`, `sync`, `check`, `prune`, `rm`, `maintenance`. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ------- | ------------ | ------------ | ------------------------------------------------------------ | | `jobs` | list of dict | always | The matching jobs, newest first (server ordering). | | `total` | int | when listing | Total number of jobs matching the filter, before pagination. | **Keys of `jobs`** | Key | Type | Returned | Description | | ------------- | ---- | ----------------------- | -------------------------------------------------------------- | | `created_at` | str | | When the job row was created. | | `id` | str | | Job id. | | `log` | str | when `include_log=true` | Plain-text job log. | | `schedule_at` | str | | When the job was scheduled to run. | | `started_at` | str | | When the job started, if it did. | | `status` | str | | One of `queued`, `running`, `canceled`, `succeeded`, `failed`. | | `stopped_at` | str | | When the job stopped, if it did. | | `task_type` | str | | Type of the task that produced the job. | ### member Manage the members of a Plakar organization. Adds people and service accounts to an organization, and removes them. A membership carries no permission — what a member may do is a grant, managed with `plakarkorp.plakar.grant`. Adding a person goes through the admin invitation path. A brand-new address gets an account with a one-time generated password, returned once in `generated_password`; an address that already has an account simply gains the membership. A service account (`service=true`) is an application user — no email, no interactive login; its address is minted server-side. Mint its API key in the Plakar UI (an application user cannot mint its own). Removing a member removes the membership, not the person's account. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `email` | str | No | | Email address of the person. The playbook's key for people. | | `name` | str | No | | Display name. The playbook's key for service accounts, which have no address; optional decoration for people. | | `organization` | str | No | | Name of the organization the membership belongs to. Defaults to the API key's own organization. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `service` | bool | No | `false` | Add an application user rather than a person. | | `state` | str | No | `present` | Whether the membership should exist. One of `present`, `absent`. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | -------------------- | ---- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_created` | bool | on creation | Whether a brand-new account was registered for the address. | | `generated_password` | str | on creation | The one-time must-change password the server minted for a brand-new account. Shown exactly once — relay it or lose it. `null` when the address already had an account. A service account gets one too, but it is inert — an application user has no interactive login, and mints its API key in the Plakar UI. | | `member` | dict | when the membership exists or was created | The member acted on (user_id, email, account, name, is_service). | ### organization Manage Plakar organizations. Creates and deletes organizations under the API key's organization. Organizations are matched by name across the badge organization's subtree; the name is the playbook's key, so it must be unique there. There is no update — the name is the key, and `info` and `type` are set at creation. An organization that already exists is left as it is. Membership is managed with `plakarkorp.plakar.member`, permissions with `plakarkorp.plakar.grant`. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `info` | dict | No | | Free-form key/value information attached at creation. | | `name` | str | Yes | | Name of the organization. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `parent` | str | No | | Name of the parent organization. Defaults to the API key's own organization. | | `state` | str | No | `present` | Whether the organization should exist. One of `present`, `absent`. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `type` | str | No | `enterprise` | Organization type. Only `enterprise` organizations can be created as sub-organizations today. | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | -------------- | ---- | ------------------------------------------- | ------------------------------------------------------ | | `organization` | dict | when the organization exists or was created | The organization acted on (id, name, type, parent_id). | ### organization_info Read a Plakar organization, its members and its grants. Reads one organization by name (the API key's own by default), with its children and, on request, its members and grants. **Options** | Option | Type | Required | Default | Description | | ----------------- | ---- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `include_grants` | bool | No | `false` | Also return the grants. | | `include_members` | bool | No | `false` | Also return the members. | | `name` | str | No | | Name of the organization, anywhere in the badge organization's subtree. Defaults to the API key's own organization. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | -------------- | ------------ | ------------------------------ | -------------------------------------------------------- | | `children` | list of dict | always | The direct sub-organizations. | | `grants` | list of dict | when `include_grants` is true | The grants (id, subject, role). | | `members` | list of dict | when `include_members` is true | The members (user_id, email, account, name, is_service). | | `organization` | dict | always | The organization (id, name, type, parent_id). | ### prune Prune snapshots from a Plakar store by retention rule. Applies a retention rule to a store's snapshots and deletes what falls outside it, through the Plakar management API. Snapshots under legal hold are never deleted and are reported separately. In check mode nothing is deleted — the API's prune preview reports what would be deleted, kept and held. The module is `changed` only when snapshots were actually deleted (or, in check mode, would be). **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `filters` | dict | No | | Further narrowing, passed to the API's locate filters — a mapping of `ignore_tags`, `before`, `since`, `name`, `category`, `environment`, `perimeter`, `job`, `dataset`, `latest`, `ids`, `types`, `origins`, `roots`, `data_classes`. `tags` is shorthand for `filters.tags`; both may be set and merge. | | `group_by` | str | No | | Partition the matched snapshots before applying the rule, so retention is honored per group instead of across the whole store — for example `dataset` keeps the rule per source instead of globally. One of `name`, `category`, `environment`, `perimeter`, `job`, `dataset`, `data-class`, `tag`, `origin`, `type`, `root`. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `retention` | dict | Yes | | The retention rule, as a mapping of bucket options — `minute`, `hour`, `day`, `week`, `month`, `year` say how many recent buckets of that unit to keep, and `per_minute`, `per_hour`, `per_day`, `per_week`, `per_month`, `per_year` how many snapshots to keep in each. For example `{day: 7, per_day: 1, month: 12, per_month: 1}` keeps one snapshot a day for a week and one a month for a year. | | `store` | str | Yes | | Name of the store to prune. | | `tags` | list of str | No | | Only consider snapshots carrying these tags. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | | `wait` | bool | No | `true` | Whether to wait for the deletion job to finish when there is something to delete. | | `wait_timeout` | int | No | `600` | Seconds to wait for the deletion job before failing. | **Returns** | Key | Type | Returned | Description | | --------- | ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `at_ids` | list of str | when a deletion ran | Identifiers of the deletion runs, when something was deleted. A long delete list may be split over several runs. | | `deleted` | list of str | always | Snapshot ids the run deleted (in check mode, would delete). | | `floored` | list of str | always | Snapshot ids the rule would delete but the organization's retention floor keeps anyway. | | `held` | list of str | always | Snapshot ids excluded because they are under legal hold. | | `jobs` | list of dict | when a deletion ran and was waited on | The deletion jobs, when something was deleted and `wait=true`. | | `kept` | list of str | in check mode | Snapshot ids the rule keeps. Only the preview reports this. | ### restore Trigger a Plakar restore. Triggers an on-demand restore of a snapshot from a store onto a destination connector, through the Plakar management API. Connectors are addressed by name. When no `snapshot_id` is given, the newest snapshot in the store is restored. The run is asynchronous server-side. By default the module polls until the job stops and fails unless it succeeded. **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `destination` | str | Yes | | Name of the destination connector to restore onto. | | `edge_tags` | list of str | No | | Select a remote edge by tags (all must match) to execute the job, falling back to local execution when no edge matches. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `snapshot_id` | str | No | | Identifier of the snapshot to restore. When omitted, the newest snapshot in the store (by creation time) is restored. | | `store` | str | Yes | | Name of the store connector holding the snapshot. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | | `wait` | bool | No | `true` | Whether to wait for the triggered job to finish. When false, the module returns as soon as the run is accepted; poll it later with `plakarkorp.plakar.job_info`. | | `wait_timeout` | int | No | `600` | Seconds to wait for the job to finish before failing. | **Returns** | Key | Type | Returned | Description | | ------------- | ---- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `at_id` | str | always (except check mode) | Identifier of the one-shot run (the scheduler's `at` entry). | | `job` | dict | when available | The job the run materialized into. Only present once the scheduler picked the run up — with `wait=false` it may be absent. | | `log` | str | on job failure | Plain-text job log, fetched when the job did not succeed. | | `snapshot_id` | str | always | The snapshot that was restored. | **Keys of `job`** | Key | Type | Returned | Description | | ------------ | ---- | -------- | -------------------------------------------------------------- | | `id` | str | | Job id, usable with `plakarkorp.plakar.job_info`. | | `started_at` | str | | When the job started, if it did. | | `status` | str | | One of `queued`, `running`, `canceled`, `succeeded`, `failed`. | | `stopped_at` | str | | When the job stopped, if it did. | ### store Manage Plakar stores. Creates, updates and deletes stores — where Plakar keeps backup data — in the Plakar management API, initializing the underlying storage on creation. Stores are matched by name within the organization; the name is the playbook's key, so it must be unique among stores. Only the options the playbook sets are managed on update; anything else keeps its current server-side value. **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `compression` | str | No | | Compression for the store at initialization. Unset keeps the engine's own default. One of `GZIP`, `LZ4`, `ZSTD`. | | `data_classes` | list of str | No | | Data classes the store accepts. | | `endpoints` | list of str | No | | Endpoint names the store reaches its resource through. | | `environment` | str | No | | Environment label, for example `production`. | | `fields` | dict | No | | Integration-specific configuration, as a mapping of field name to value. A value may also be a mapping with `value` and an optional `provider_id` naming a secret provider. On update, only the fields named here are compared and replaced; other existing fields are preserved. Must carry a non-empty `passphrase` when the store is initialized here, since it encrypts the store at rest. A field backed by a secret provider counts as set, because the provider supplies the value. | | `initialize` | bool | No | `true` | Whether to initialize the underlying storage right after creating the store. Initialization only happens on creation, never on update. Set it to false when the storage is already initialized elsewhere, which also lifts the passphrase requirement. | | `integration` | str | No | | Name of the installed integration backing the store. Required when creating. | | `name` | str | Yes | | Name of the store. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `protocol` | str | No | | Protocol spoken to the resource, for example `s3` or `sftp`. Defaults to the integration name, which matches for the standard integrations; set it only when they differ. | | `resource` | str | No | | URN or name of the inventory resource the store attaches to. Required when creating. | | `state` | str | No | `present` | Whether the store should exist. `absent` removes the store from Plakar; the data in the underlying storage is not touched. One of `present`, `absent`. | | `temperature` | str | No | | Storage temperature. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | **Returns** | Key | Type | Returned | Description | | ----------- | ----------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `connector` | dict | when the store exists or was created | The store acted on (a summary; field values are not echoed). Carries `initialized` when the module created it. | | `diff_keys` | list of str | on update | The option names whose values differed and drove the update. | ### sync Sync snapshots between Plakar stores. Triggers an on-demand synchronization of snapshots from one store into another — offsite replication, hot-to-cold tiering — through the Plakar management API. Stores are addressed by name; names are resolved within the organization at run time. The run is asynchronous server-side. By default the module polls until the job stops and fails unless it succeeded. **Options** | Option | Type | Required | Default | Description | | ----------------- | ----------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | str | No | | API key of a service account, as minted by the Plakar API (`pcp_ak_...`). API keys authenticate without a second factor and are bound to one organization. The service account must hold a role in the organization (the `operator` role suffices for running backups and restores); without a grant the API answers with empty lists rather than errors. Falls back to the `PLAKAR_API_KEY` environment variable. | | `api_url` | str | No | | Base URL of the Plakar management API, for example `https://plakar.example.com`. Falls back to the `PLAKAR_API_URL` environment variable. | | `edge_tags` | list of str | No | | Select a remote edge by tags (all must match) to execute the job, falling back to local execution when no edge matches. | | `labels` | list of str | No | | Only sync snapshots carrying these labels. | | `organization_id` | str | No | | UUID of the organization to operate in, when different from the one the API key is bound to. The badge is re-scoped once per organization and cached for the duration of the task. | | `store` | str | Yes | | Name of the store holding the snapshots to sync. | | `timeout` | int | No | `30` | Timeout in seconds for each individual API request (not for job completion; the action modules have `wait_timeout` for that). | | `to_store` | str | Yes | | Name of the store to sync the snapshots into. | | `validate_certs` | bool | No | `true` | Whether to validate TLS certificates when talking to the API. | | `wait` | bool | No | `true` | Whether to wait for the triggered job to finish. When false, the module returns as soon as the run is accepted; poll it later with `plakarkorp.plakar.job_info`. | | `wait_timeout` | int | No | `600` | Seconds to wait for the job to finish before failing. | **Returns** | Key | Type | Returned | Description | | ------- | ---- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `at_id` | str | always (except check mode) | Identifier of the one-shot run (the scheduler's `at` entry). | | `job` | dict | when available | The job the run materialized into. Only present once the scheduler picked the run up — with `wait=false` it may be absent. | | `log` | str | on job failure | Plain-text job log, fetched when the job did not succeed. | **Keys of `job`** | Key | Type | Returned | Description | | ------------ | ---- | -------- | -------------------------------------------------------------- | | `id` | str | | Job id, usable with `plakarkorp.plakar.job_info`. | | `started_at` | str | | When the job started, if it did. | | `status` | str | | One of `queued`, `running`, `canceled`, `succeeded`, `failed`. | | `stopped_at` | str | | When the job stopped, if it did. |