diff --git a/docs/source/module/routes/index.rst b/docs/source/module/routes/index.rst index 5adfbe1c6cb099b483d972cb274019b3aa3a7ab3..12555477a7e5f22aeedb7d6eb9062a155034b335 100644 --- a/docs/source/module/routes/index.rst +++ b/docs/source/module/routes/index.rst @@ -13,5 +13,4 @@ Submodules :titlesonly: default - ip_trunk - router + playbook diff --git a/docs/source/module/routes/ip_trunk.rst b/docs/source/module/routes/playbook.rst similarity index 50% rename from docs/source/module/routes/ip_trunk.rst rename to docs/source/module/routes/playbook.rst index c6c2e88566e4488e5720cbd2a9e87e85ef57c342..7a3da3c57df5828d47cd5be6630214ccafd9ca19 100644 --- a/docs/source/module/routes/ip_trunk.rst +++ b/docs/source/module/routes/playbook.rst @@ -1,6 +1,6 @@ -``lso.routes.ip_trunk`` +``lso.routes.playbook`` ======================= -.. automodule:: lso.routes.ip_trunk +.. automodule:: lso.routes.playbook :members: :show-inheritance: diff --git a/docs/source/module/routes/router.rst b/docs/source/module/routes/router.rst deleted file mode 100644 index 2f10a490b0f79bd255bd3b198e1fcbe5de362b03..0000000000000000000000000000000000000000 --- a/docs/source/module/routes/router.rst +++ /dev/null @@ -1,6 +0,0 @@ -``lso.routes.router`` -====================== - -.. automodule:: lso.routes.router - :members: - :show-inheritance: diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index f906ccbaae06a10b42025c9aa6dc70f732fd1f33..ed6fe5d16f2a04c99ab1da961ec8ce7927d340b3 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -3,14 +3,44 @@ Quick start This is a quick setup guide for running standalone on your local machine. +As a Docker container +--------------------- +To run LSO as a Docker container, build an image using the ``Dockerfile`` as an example. Be sure to update +``ansible-galaxy-requirements.yaml`` accordingly, depending on your specific Ansible collection and -role needs. + +An example Docker compose file is presented below: + +.. code-block:: yaml + + version: "3.5" + services: + lso: + image: goat-lso:$LSO_VERSION_TAG + environment: + SETTINGS_FILENAME: /app/config.json + volumes: + - "/home/user/config.json:/app/config.json:ro" + - "/home/user/ansible_inventory:/opt/ansible_inventory:ro" + - "~/.ssh/id_ed25519.pub:/root/.ssh/id_rsa.pub:ro" + - "~/.ssh/id_ed25519:/root/.ssh/id_rsa:ro" + restart: unless-stopped + +This will expose the API on port 8080. The container requires some additional files to be mounted: + +* A ``config.json`` that references to the location where the Ansible playbooks are stored **inside the container**. +* An Ansible inventory for all host and group variables that are used in the playbooks +* A public/private key pair for SSH authentication on external machines that are targeted by Ansible playbooks. + Install the module ------------------ +Alternatively, below are a set of instructions for installing and running LSO directly on a machine. + *One of these should be what you're looking for:* * Install the latest module snapshot -.. code-block:: +.. code-block:: bash python3 -m venv my-venv-directory . my-venv-directory/bin/activate @@ -19,12 +49,12 @@ Install the module * Install the source code -.. code-block:: +.. code-block:: bash python3 -m venv my-venv-directory . my-venv-directory/bin/activate - git clone https://gitlab.geant.org/goat/gap/lso.git + git clone https://gitlab.software.geant.org/goat/gap/lso.git cd lso pip install -e . @@ -50,4 +80,4 @@ Examples curl http://localhost:44444/api/version -* View the docs by loading <http://localhost:44444/docs> in your browser +* View the docs by loading http://localhost:44444/docs in your browser diff --git a/lso/playbook.py b/lso/playbook.py index df3e0383fcbd7de84be66909e6e83b3820aac53e..0ada50b35af83487686d739442bd0397892ad7b3 100644 --- a/lso/playbook.py +++ b/lso/playbook.py @@ -88,9 +88,8 @@ def run_playbook( :param Path playbook_path: playbook to be executed. :param dict[str, Any] extra_vars: Any extra vars needed for the playbook to run. :param dict[str, Any] | str inventory: The inventory that the playbook is executed against. - :param :class:`HttpUrl` callback: Callback URL where the playbook should send a status update when execution is - completed. This is used for workflow-orchestrator to continue with the next step - in a workflow. + :param HttpUrl callback: Callback URL where the playbook should send a status update when execution is completed. + This is used for workflow-orchestrator to continue with the next step in a workflow. :return: Result of playbook launch, this could either be successful or unsuccessful. :rtype: :class:`fastapi.responses.JSONResponse` """ diff --git a/lso/routes/playbook.py b/lso/routes/playbook.py index 0257cc45b455ff29a776570c9974f6169a3ea6da..43808874035d247e2fb5b38270807f63a6ca9d5d 100644 --- a/lso/routes/playbook.py +++ b/lso/routes/playbook.py @@ -67,9 +67,8 @@ def run_playbook_endpoint(params: PlaybookRunParams) -> JSONResponse: The response will contain either a job ID, or error information. - :param params :class:`PlaybookRunParams`: Parameters for executing a playbook. - :return: Response from the Ansible runner, including a run ID. - :rtype: :class:`fastapi.responses.JSONResponse` + :param PlaybookRunParams params: Parameters for executing a playbook. + :return JSONResponse: Response from the Ansible runner, including a run ID. """ return run_playbook( playbook_path=get_playbook_path(params.playbook_name),