Parameters

Request

When posting to the API endpoint to start an Ansible playbook, the following attributes can be set.

lso.routes.playbook.PlaybookRunParams

Bases: pydantic.BaseModel

Parameters for executing an Ansible playbook.

Attributes: playbook_name (PlaybookName): The filename of a playbook that’s executed. It should be present inside the directory defined in the configuration option ANSIBLE_PLAYBOOKS_ROOT_DIR. callback (HttpUrl, optional): The address where LSO should call back to upon completion. progress (HttpUrl, optional): The address where LSO should send progress updates as the playbook executes. progress_is_incremental (bool, optional): Whether progress updates should be incremental or not. inventory (PlaybookInventory): The inventory to run the playbook against. This inventory can also include any host vars, if needed. When including host vars, it should be a dictionary. Can be a simple string containing host names when no host vars are needed. In the latter case, multiple hosts should be separated with a \n newline character only. extra_vars (dict[str, Any]): Extra variables that should get passed to the playbook. This includes any required configuration objects from the workflow orchestrator, commit comments, whether this execution should be a dry run, a trouble ticket number, etc. Which extra vars are required solely depends on what inputs the playbook requires.

Inventory format

Note the fact if the collection of all hosts is a dictionary, and not a list of strings, Ansible expects each host to be a key-value pair. The key is the FQDN of a host, and the value always null. This is not the case when providing the inventory as a list of strings.

Inventory validation

The submitted inventory is validated against the static inventory format described here, using Ansible’s built-in YAML inventory plugin in a pinned environment. The machine’s own ansible.cfg deliberately plays no part in it, so what the API accepts is identical on every deployment; playbook execution itself still honours the deployer’s Ansible configuration. A malformed inventory is rejected with a 422 whose body is an InventoryProblem; a 503 or 504 means validation itself could not run (no ansible-inventory command, or it timed out) rather than that the inventory is invalid.

Example

{
    "playbook_name": "hello_world.yaml",
    "callback": "https://wfo.company.cool:8080/api/resume-workflow/",
    "progress": "https://logging.awesome.yeah:8080/playbooks/",
    "progress_is_incremental": false,
    "inventory": {
        "all": {
            "hosts": {
                "host1.local": {
                    "foo": "bar"
                },
                "host2.local": {
                    "key": "value"
                },
                "host3.local": null
            }
        }
    },
    "extra_vars": {
        "weather": {
            "today": "Sunny",
            "tomorrow": "Overcast"
        }
    }
}

Source code in .venv/lib/python3.14/site-packages/lso/routes/playbook.py

class PlaybookRunParams(BaseModel):
    r"""Parameters for executing an Ansible playbook.

    Attributes:
        playbook_name (PlaybookName): The filename of a playbook that's executed. It should be present inside the
            directory defined in the configuration option ``ANSIBLE_PLAYBOOKS_ROOT_DIR``.
        callback (HttpUrl, optional): The address where LSO should call back to upon completion.
        progress (HttpUrl, optional): The address where LSO should send progress updates as the playbook executes.
        progress_is_incremental (bool, optional): Whether progress updates should be incremental or not.
        inventory (PlaybookInventory): The inventory to run the playbook against. This inventory can also include any
            host vars, if needed. When including host vars, it should be a dictionary. Can be a simple string containing
            host names when no host vars are needed. In the latter case, multiple hosts should be separated with a `\n`
            newline character only.
        extra_vars (dict[str, Any]): Extra variables that should get passed to the playbook.
            This includes any required configuration objects from the workflow orchestrator, commit comments, whether
            this execution should be a dry run, a trouble ticket number, etc. Which extra vars are required solely
            depends on what inputs the playbook requires.

    !!! danger "Inventory format"
        Note the fact if the collection of all hosts is a dictionary, and not a list of strings, Ansible expects each
        host to be a key-value pair. The key is the FQDN of a host, and the value always `null`. This is not the case
        when providing the inventory as a list of strings.

    !!! note "Inventory validation"
        The submitted inventory is validated against the static inventory format described here, using Ansible's
        built-in YAML inventory plugin in a pinned environment. The machine's own `ansible.cfg` deliberately plays
        no part in it, so what the API accepts is identical on every deployment; playbook execution itself still
        honours the deployer's Ansible configuration. A malformed inventory is rejected with a 422 whose body is an
        `InventoryProblem`; a 503 or 504 means validation itself could not run (no `ansible-inventory` command, or
        it timed out) rather than that the inventory is invalid.

    ??? example
        ```JSON
        {
            "playbook_name": "hello_world.yaml",
            "callback": "https://wfo.company.cool:8080/api/resume-workflow/",
            "progress": "https://logging.awesome.yeah:8080/playbooks/",
            "progress_is_incremental": false,
            "inventory": {
                "all": {
                    "hosts": {
                        "host1.local": {
                            "foo": "bar"
                        },
                        "host2.local": {
                            "key": "value"
                        },
                        "host3.local": null
                    }
                }
            },
            "extra_vars": {
                "weather": {
                    "today": "Sunny",
                    "tomorrow": "Overcast"
                }
            }
        }
        ```

    """

    playbook_name: PlaybookName
    callback: HttpUrl | None = None
    progress: HttpUrl | None = None
    progress_is_incremental: bool = True
    inventory: PlaybookInventory
    extra_vars: dict[str, Any] = {}

Response

Once the API request is received, it returns a response that contains the following attributes.

lso.routes.playbook.PlaybookRunResponse

Bases: pydantic.BaseModel

PlaybookRunResponse domain model schema.

Attributes: job_id (UUID): The UUID generated for a Playbook execution.

Source code in .venv/lib/python3.14/site-packages/lso/routes/playbook.py

class PlaybookRunResponse(BaseModel):
    """`PlaybookRunResponse` domain model schema.

    Attributes:
        job_id (UUID): The UUID generated for a Playbook execution.

    """

    job_id: UUID