diff --git a/Makefile b/Makefile index dd8ccda3..109059c7 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: clean clean-build clean-pyc clean-test coverage dist docs help install lint lint/flake8 lint/black +.PHONY: clean clean-build clean-pyc clean-test coverage dist docs help install lint lint/flake8 lint/black minimal-ee .DEFAULT_GOAL := help define BROWSER_PYSCRIPT @@ -86,3 +86,6 @@ dist: clean ## builds source and wheel package install: clean ## install the package to the active Python's site-packages pip install . + +minimal-ee: + ansible-builder build -f ./minimal-decision-environment.yml -t minimal-de:latest \ No newline at end of file diff --git a/docs/decision_environment.rst b/docs/decision_environment.rst new file mode 100644 index 00000000..9d96f23b --- /dev/null +++ b/docs/decision_environment.rst @@ -0,0 +1,97 @@ +==================== +Decision Environment +==================== + +Decision Environments are `Execution Environments `_ tailored towards running Ansible +Rulebook tasks. These represent container images that launch and run the rulebook process and contain all of the dependencies, collections, +and configuration needed to run a rulebook. + +A basic and minimal decision_environment is included at the root of the repository. This is a good starting point for building your own: + +.. code-block:: shell + + ansible-builder build -f minimal-decision-environment.yml -t minimal-decision-environment:latest + +This will build a container image named ``minimal-decision-environment:latest`` that can be used as the basis for your own decision environment. + +Lets run a rulebook using this decision environment, lets make sure we have a local inventory that has localhost in it we're going to use: + +.. code-block:: shell + + echo "localhost ansible_connection=local" > inventory + +Now lets run a rulebook using this decision environment: + +.. code-block:: shell + + docker run -it --rm -v ./inventory:/tmp/inventory ansible-execution-env:latest ansible-rulebook -r ansible.eda.hello_events -i /tmp/inventory + + +Using your own rulebooks and projects with the decision environment +------------------------------------------------------------------- + +The minimal decision environment is a good starting point, but you will likely want to add your own rulebooks and projects to it. + +.. note:: + + Have a look at the `Ansible Builder Execution Environment Definition `_ for details on how to add collections and dependencies to your decision environment. + +.. code-block:: yaml + + --- + version: 3 + + images: + base_image: + name: 'minimal-decision-environment:latest' + dependencies: + python: + - pywinrm + system: + - iputils [platform:rpm] + galaxy: + collections: + - name: my_namespace.my_awesome_collection + - name: community.windows + - name: ansible.utils + version: 2.10.1 + options: + container_init: + cmd: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r", "my_namespace.my_awesome_collection.my_rulebook", "-i", "/tmp/inventory"]' + +This shows an example where you may have your own Collection that contains rulebooks and playbooks but need to bring them together with some other collections +and some python and system dependencies. + +You could also use Builder to add your own rulebooks and playbooks to the decision environment via `additional-build-steps`_ +and then making use of Containerfile commands to ADD or COPY to get the files into the environment. + +.. code-block:: yaml + + --- + version: 3 + + images: + base_image: + name: 'minimal-decision-environment:latest' + dependencies: + python: + - pywinrm + system: + - iputils [platform:rpm] + galaxy: + collections: + - name: community.windows + - name: ansible.utils + version: 2.10.1 + additional_build_steps: + prepend_builder: + - 'RUN mkdir -p /opt/ansible/my_rulebooks' + - 'COPY my_rulebook.yml /opt/ansible/my_rulebooks' + options: + container_init: + cmd: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r", "/opt/ansible/my_rulebooks/my_rulebook.yml", "-i", "/tmp/inventory"]' + +.. note:: + + container_init.cmd is an optional override that can be used to override the default command that is run when the container is launched. This is useful if you want to + run a playbook or rulebook without needing to supply the full command line arguments. It can still be overridden at runtime by passing a command to the container. diff --git a/docs/index.rst b/docs/index.rst index 22bb3f72..4eca768b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,7 @@ Welcome to Ansible Rulebook documentation runner collections environments + decision_environment Indices and tables ================== diff --git a/minimal-decision-environment.yml b/minimal-decision-environment.yml new file mode 100644 index 00000000..cf691a04 --- /dev/null +++ b/minimal-decision-environment.yml @@ -0,0 +1,25 @@ +version: 3 + +images: + base_image: + name: 'registry.access.redhat.com/ubi9/python-311:latest' + +dependencies: + galaxy: + collections: + - ansible.eda + python: + - azure-servicebus + - aiobotocore + - aiohttp + - aiokafka + - watchdog + - systemd-python + - dpath + - ansible-rulebook + ansible_core: + package_pip: ansible-core==2.14.4 + ansible_runner: + package_pip: ansible-runner + system: + - java-17-openjdk-devel [platform:rpm] diff --git a/requirements_dev.txt b/requirements_dev.txt index 29c9e204..ea791ae6 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -12,3 +12,5 @@ build tox coverage +# For building DEs +ansible-builder