orchestrator-lso 1.0.0__tar.gz

orchestrator_lso-1.0.0/.bumpversion.cfg

@@ -0,0 +1,16 @@
+[bumpversion]
+current_version = 1.0.0
+commit = False
+tag = False
+parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(rc(?P<build>\d+))?
+serialize =
+	{major}.{minor}.{patch}rc{build}
+	{major}.{minor}.{patch}
+
+[bumpversion:file:lso/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"
+
+[bumpversion:file:Dockerfile.example]
+search = RUN pip install orchestrator-lso=="{current_version}"
+replace = RUN pip install orchestrator-lso=="{new_version}"

orchestrator_lso-1.0.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

orchestrator_lso-1.0.0/.github/styles/config/vocabularies/Sphinx/accept.txt

@@ -0,0 +1 @@
+param

orchestrator_lso-1.0.0/.github/styles/config/vocabularies/jargon/accept.txt

@@ -0,0 +1,10 @@
+(LSO|lso)
+[Ss]ubpackages
+Vereniging
+against
+BASIS
+A(NY|ny)
+KIND
+Ansible
+[Uu]nprocessable
+[Hh]ostnames?

orchestrator_lso-1.0.0/.github/workflows/publish-package.yaml

@@ -0,0 +1,26 @@
+name: Publish package on PyPI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flit
+      env:
+        FLIT_ROOT_INSTALL: 1
+    - name: Build and publish
+      env:
+        FLIT_USERNAME: ${{ secrets.FLIT_USERNAME }}
+        FLIT_PASSWORD: ${{ secrets.FLIT_PASSWORD }}
+      run: flit publish

orchestrator_lso-1.0.0/.github/workflows/run-linting-tests.yaml

@@ -0,0 +1,43 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Linting tests
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  build:
+    name: Linting Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flit
+          flit install --deps develop --symlink
+        env:
+          FLIT_ROOT_INSTALL: 1
+      - name: Check formatting with ruff
+        run: |
+          ruff format --respect-gitignore --preview --check .
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff check --respect-gitignore --preview .
+      - name: Check with mypy
+        run: |
+          mypy .

orchestrator_lso-1.0.0/.github/workflows/run-unit-tests.yaml

@@ -0,0 +1,30 @@
+name: Unit tests
+on:
+  push:
+  workflow_call:
+
+jobs:
+  container_job:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+      fail-fast: false
+    container: python:${{ matrix.python-version }}-slim
+    steps:
+      # Downloads a copy of the code in your repository before running CI tests
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flit
+          flit install --deps develop --symlink
+        env:
+          FLIT_ROOT_INSTALL: 1
+      - name: Run Unit tests
+        run: pytest
+        env:
+          SETTINGS_FILENAME: dummy.json

orchestrator_lso-1.0.0/.github/workflows/sphinx.yaml

@@ -0,0 +1,43 @@
+name: "Sphinx: render docs"
+
+on:
+  push:
+    branches:
+      - develop
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python environment
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Install requirements
+        run: |
+          python -m pip install --upgrade pip
+          pip install flit
+          flit install --deps develop --symlink
+        env:
+          FLIT_ROOT_INSTALL: 1
+      - name: Build documentation
+        run: TZ=UTC sphinx-build -b html docs/source docs/build
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: "docs/source/,lso/"
+          separator: ','
+          fail_on_error: true
+          vale_flags: "--glob=*.{rst,py}"
+      - uses: peaceiris/actions-gh-pages@v3
+        if: ${{ !env.ACT }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/
+          enable_jekyll: false

orchestrator_lso-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__
+.coverage
+.idea
+.vscode
+coverage.xml
+*.egg-info
+
+dist/
+.github/styles/*
+!.github/styles/config/
+venv/
+.venv/
+
+.DS_Store # macOS
+Thumbs.db # Windows

orchestrator_lso-1.0.0/.vale.ini

@@ -0,0 +1,27 @@
+StylesPath = .github/styles
+
+MinAlertLevel = suggestion
+
+Vocab = jargon, Sphinx
+
+Packages = proselint, Microsoft
+
+[*]
+BasedOnStyles = Vale, proselint, Microsoft
+; Found to be too intrusive
+Microsoft.Passive = NO
+; We are not a general audience
+Microsoft.GeneralURL = NO
+; It's okay to leave TODOs in the code, that's what they're for
+proselint.Annotations = NO
+; Replacing a ... with … shouldn't be holding back the entire CI pipeline
+proselint.Typography = warning
+; Same applies for not using contractions
+Microsoft.Contractions = warning
+Microsoft.Headings = NO
+Microsoft.SentenceLength = NO
+
+TokenIgnores = (:class:`\S+`),(:returns?.*:),(:param.+:),(noqa.*)
+
+[formats]
+py = rst

orchestrator_lso-1.0.0/Changelog.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## [1.0.0] - 2024-03-07
+Initial release

orchestrator_lso-1.0.0/Dockerfile.example

@@ -0,0 +1,27 @@
+FROM python:3.12-alpine
+
+WORKDIR /app
+
+# Copy in requirements files, if needed
+# These could be for Ansible Galaxy, Poetry, or a requirements.txt file
+COPY ./requirements.txt ./requirements.txt
+COPY ./ansible-galaxy-requirements.yaml ./ansible-galaxy-requirements.yaml
+
+# Install required system packages
+RUN apk add --update --no-cache gcc libc-dev libffi-dev openssh
+
+# Install the LSO python package, and additional requirements
+RUN pip install orchestrator-lso=="1.0.0"
+RUN pip install -r requirements.txt
+
+# Install required Ansible Galaxy roles and collections
+RUN ansible-galaxy install \
+                   -r ansible-galaxy-requirements.yaml \
+                   -p /app/gap/ansible
+RUN ansible-galaxy collection install \
+                   -r ansible-galaxy-requirements.yaml \
+                   -p /app/gap/ansible
+
+EXPOSE 8000
+ENTRYPOINT []
+CMD ["python", "-m",  "uvicorn", "lso.app:app", "--host", "0.0.0.0", "--port", "8000"]

orchestrator_lso-1.0.0/LICENSE

@@ -0,0 +1,202 @@
+                             Apache License
+                       Version 2.0, January 2004
+                    http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+  "License" shall mean the terms and conditions for use, reproduction,
+  and distribution as defined by Sections 1 through 9 of this document.
+
+  "Licensor" shall mean the copyright owner or entity authorized by
+  the copyright owner that is granting the License.
+
+  "Legal Entity" shall mean the union of the acting entity and all
+  other entities that control, are controlled by, or are under common
+  control with that entity. For the purposes of this definition,
+  "control" means (i) the power, direct or indirect, to cause the
+  direction or management of such entity, whether by contract or
+  otherwise, or (ii) ownership of fifty percent (50%) or more of the
+  outstanding shares, or (iii) beneficial ownership of such entity.
+
+  "You" (or "Your") shall mean an individual or Legal Entity
+  exercising permissions granted by this License.
+
+  "Source" form shall mean the preferred form for making modifications,
+  including but not limited to software source code, documentation
+  source, and configuration files.
+
+  "Object" form shall mean any form resulting from mechanical
+  transformation or translation of a Source form, including but
+  not limited to compiled object code, generated documentation,
+  and conversions to other media types.
+
+  "Work" shall mean the work of authorship, whether in Source or
+  Object form, made available under the License, as indicated by a
+  copyright notice that is included in or attached to the work
+  (an example is provided in the Appendix below).
+
+  "Derivative Works" shall mean any work, whether in Source or Object
+  form, that is based on (or derived from) the Work and for which the
+  editorial revisions, annotations, elaborations, or other modifications
+  represent, as a whole, an original work of authorship. For the purposes
+  of this License, Derivative Works shall not include works that remain
+  separable from, or merely link (or bind by name) to the interfaces of,
+  the Work and Derivative Works thereof.
+
+  "Contribution" shall mean any work of authorship, including
+  the original version of the Work and any modifications or additions
+  to that Work or Derivative Works thereof, that is intentionally
+  submitted to Licensor for inclusion in the Work by the copyright owner
+  or by an individual or Legal Entity authorized to submit on behalf of
+  the copyright owner. For the purposes of this definition, "submitted"
+  means any form of electronic, verbal, or written communication sent
+  to the Licensor or its representatives, including but not limited to
+  communication on electronic mailing lists, source code control systems,
+  and issue tracking systems that are managed by, or on behalf of, the
+  Licensor for the purpose of discussing and improving the Work, but
+  excluding communication that is conspicuously marked or otherwise
+  designated in writing by the copyright owner as "Not a Contribution."
+
+  "Contributor" shall mean Licensor and any individual or Legal Entity
+  on behalf of whom a Contribution has been received by Licensor and
+  subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  copyright license to reproduce, prepare Derivative Works of,
+  publicly display, publicly perform, sublicense, and distribute the
+  Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  (except as stated in this section) patent license to make, have made,
+  use, offer to sell, sell, import, and otherwise transfer the Work,
+  where such license applies only to those patent claims licensable
+  by such Contributor that are necessarily infringed by their
+  Contribution(s) alone or by combination of their Contribution(s)
+  with the Work to which such Contribution(s) was submitted. If You
+  institute patent litigation against any entity (including a
+  cross-claim or counterclaim in a lawsuit) alleging that the Work
+  or a Contribution incorporated within the Work constitutes direct
+  or contributory patent infringement, then any patent licenses
+  granted to You under this License for that Work shall terminate
+  as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+  Work or Derivative Works thereof in any medium, with or without
+  modifications, and in Source or Object form, provided that You
+  meet the following conditions:
+
+  (a) You must give any other recipients of the Work or
+      Derivative Works a copy of this License; and
+
+  (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+  (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+  (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+  You may add Your own copyright statement to Your modifications and
+  may provide additional or different license terms and conditions
+  for use, reproduction, or distribution of Your modifications, or
+  for any such Derivative Works as a whole, provided Your use,
+  reproduction, and distribution of the Work otherwise complies with
+  the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+  any Contribution intentionally submitted for inclusion in the Work
+  by You to the Licensor shall be under the terms and conditions of
+  this License, without any additional terms or conditions.
+  Notwithstanding the above, nothing herein shall supersede or modify
+  the terms of any separate license agreement you may have executed
+  with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+  names, trademarks, service marks, or product names of the Licensor,
+  except as required for reasonable and customary use in describing the
+  origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+  agreed to in writing, Licensor provides the Work (and each
+  Contributor provides its Contributions) on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+  implied, including, without limitation, any warranties or conditions
+  of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+  PARTICULAR PURPOSE. You are solely responsible for determining the
+  appropriateness of using or redistributing the Work and assume any
+  risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+  whether in tort (including negligence), contract, or otherwise,
+  unless required by applicable law (such as deliberate and grossly
+  negligent acts) or agreed to in writing, shall any Contributor be
+  liable to You for damages, including any direct, indirect, special,
+  incidental, or consequential damages of any character arising as a
+  result of this License or out of the use or inability to use the
+  Work (including but not limited to damages for loss of goodwill,
+  work stoppage, computer failure or malfunction, or any and all
+  other commercial damages or losses), even if such Contributor
+  has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+  the Work or Derivative Works thereof, You may choose to offer,
+  and charge a fee for, acceptance of support, warranty, indemnity,
+  or other liability obligations and/or rights consistent with this
+  License. However, in accepting such obligations, You may act only
+  on Your own behalf and on Your sole responsibility, not on behalf
+  of any other Contributor, and only if You agree to indemnify,
+  defend, and hold each Contributor harmless for any liability
+  incurred by, or claims asserted against, such Contributor by reason
+  of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+  To apply the Apache License to your work, attach the following
+  boilerplate notice, with the fields enclosed by brackets "[]"
+Copyright [yyyy] [name of copyright owner]
+  replaced with your own identifying information. (Don't include
+  the brackets!)  The text should be enclosed in the appropriate
+  comment syntax for the file format. We also recommend that a
+  file or class name and description of purpose be included on the
+  same "printed page" as the copyright notice for easier
+  identification within third-party archives.
+
+Copyright [2023-2024] [GÉANT Vereniging]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

orchestrator_lso-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.1
+Name: orchestrator-lso
+Version: 1.0.0
+Summary: Automatically invoked app factory.
+Author-email: GÉANT Orchestration and Automation Team <goat@geant.org>
+Requires-Python: >=3.11,<3.13
+Description-Content-Type: text/markdown
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: ansible-runner~=2.3.4
+Requires-Dist: ansible~=9.3.0
+Requires-Dist: fastapi~=0.110.0
+Requires-Dist: httpx~=0.27.0
+Requires-Dist: jsonschema~=4.21.1
+Requires-Dist: uvicorn[standard]~=0.28.0
+Requires-Dist: types-setuptools ; extra == "dev"
+Requires-Dist: types-requests ; extra == "dev"
+Requires-Dist: toml ; extra == "dev"
+Requires-Dist: types-toml ; extra == "dev"
+Requires-Dist: mypy_extensions ; extra == "dev"
+Requires-Dist: pre-commit ; extra == "dev"
+Requires-Dist: sphinx ; extra == "doc"
+Requires-Dist: sphinx-rtd-theme ; extra == "doc"
+Requires-Dist: docutils ; extra == "doc"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: Faker ; extra == "test"
+Requires-Dist: responses ; extra == "test"
+Requires-Dist: mypy ; extra == "test"
+Requires-Dist: ruff ; extra == "test"
+Requires-Dist: jsonschema ; extra == "test"
+Requires-Dist: starlette ; extra == "test"
+Project-URL: Documentation, https://workfloworchestrator.org/lso/
+Project-URL: Source, https://github.com/workfloworchestrator/lso
+Provides-Extra: dev
+Provides-Extra: doc
+Provides-Extra: test
+
+# Lightweight Service Orchestrator
+
+LSO: an API that allows for remotely executing Ansible playbooks.
+
+## Code documentation
+
+Code documentation can be found at <https://workfloworchestrator.org/lso>
+
+## Quick start
+
+This is a quick setup guide for running on your local machine.
+
+### As a Docker container
+
+To run LSO as a Docker container, build an image using the `Dockerfile.example` as an example. Be sure to update
+`requirements.txt` and `ansible-galaxy-requirements.yaml` accordingly, depending on your specific Ansible collection and
+-role needs.
+
+Use the Docker image to then spin up an environment. An example Docker compose file is presented below:
+
+```yaml
+  version: "3.5"
+  services:
+   lso:
+     image: my-lso:latest
+     environment:
+       SETTINGS_FILENAME: /app/config.json
+       ANSIBLE_ROLES_PATH: /app/lso/ansible_roles
+     volumes:
+       - "/home/user/config.json:/app/config.json:ro"
+       - "/home/user/ansible_inventory:/opt/ansible_inventory:ro"
+       - "~/.ssh/id_ed25519.pub:/root/.ssh/id_ed25519.pub:ro"
+       - "~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro"
+```
+
+This will expose the API on port 8000. The container requires some more 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.
+* Any Ansible-specific configuration (such as `collections_path`, `roles_path`, etc.) should be set using
+  environment variables. `ANSIBLE_ROLES_PATH` is given as an example in the Docker compose snippet above.
+
+### Install the module
+
+
+As an alternative, 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 release
+
+```bash
+  python3 -m venv my-venv-directory
+  . my-venv-directory/bin/activate
+
+  pip install orchestrator-lso
+```
+
+* Install the source code
+
+```bash
+  git clone https://github.com/workfloworchestrator/lso.git && cd lso
+  python3 -m venv my-venv-directory
+  . my-venv-directory/bin/activate
+  
+  pip install flit
+  flit install --deps production
+  
+  # Or, for the full development environment
+  flit install --deps develop
+```
+
+### Running the app
+
+* Create a settings file, see `config.json.example` for an example.
+* If necessary, set the environment variable `ANSIBLE_HOME` to a custom path.
+* Run the app like this (`app.py` starts the server on port 44444):
+
+```bash
+  SETTINGS_FILENAME=/absolute/path/to/config.json python -m lso.app
+```
+