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 hostnames 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.

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.12/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
            hostnames 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.

    ??? 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.12/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