From bf8ab8197834d0ab6c5e964acad48e36faf66da0 Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Tue, 30 May 2023 11:20:41 -0400 Subject: [PATCH 1/6] Replace old Dockerfile with ansible-builder configuration --- docs/decision_environment.rst | 24 ++++++++++++++++++++++++ docs/index.rst | 1 + minimal-decision-environment.yml | 25 +++++++++++++++++++++++++ 3 files changed, 50 insertions(+) create mode 100644 docs/decision_environment.rst create mode 100644 minimal-decision-environment.yml diff --git a/docs/decision_environment.rst b/docs/decision_environment.rst new file mode 100644 index 00000000..699f6d9d --- /dev/null +++ b/docs/decision_environment.rst @@ -0,0 +1,24 @@ +==================== +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.yaml -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. + + +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:: + This section needs to be written \ No newline at end of file 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..a8bd63bc --- /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] \ No newline at end of file From abce3b86ce45c5cd4655197f6eaeaf684da44ff7 Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Tue, 30 May 2023 12:23:13 -0400 Subject: [PATCH 2/6] Add rulebook entrypoint for builder, give an example on how to call the minimal base --- docs/decision_environment.rst | 12 ++++++++++++ minimal-decision-environment.yml | 5 ++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/decision_environment.rst b/docs/decision_environment.rst index 699f6d9d..ec3a0dd8 100644 --- a/docs/decision_environment.rst +++ b/docs/decision_environment.rst @@ -14,6 +14,18 @@ A basic and minimal decision_environment is included at the root of the reposito 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 ------------------------------------------------------------------- diff --git a/minimal-decision-environment.yml b/minimal-decision-environment.yml index a8bd63bc..b40da88f 100644 --- a/minimal-decision-environment.yml +++ b/minimal-decision-environment.yml @@ -22,4 +22,7 @@ dependencies: ansible_runner: package_pip: ansible-runner system: - - java-17-openjdk-devel [platform:rpm] \ No newline at end of file + - java-17-openjdk-devel [platform:rpm] +options: + container_init: + entrypoint: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r"]' From 1c9403b8c6ba37f6a93babdcec5ae4a35d096d0c Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Wed, 31 May 2023 08:05:49 -0400 Subject: [PATCH 3/6] Add customized builder example to DE docs --- Makefile | 5 ++- docs/decision_environment.rst | 62 +++++++++++++++++++++++++++++++++-- 2 files changed, 63 insertions(+), 4 deletions(-) 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 index ec3a0dd8..c56415f8 100644 --- a/docs/decision_environment.rst +++ b/docs/decision_environment.rst @@ -2,7 +2,7 @@ Decision Environment ==================== -Decision Environments are `Execution Environments `_ tailored towards running Ansible +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. @@ -32,5 +32,61 @@ 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:: - This section needs to be written \ No newline at end of file +.. 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: + entrypoint: '["/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 `addtional-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: + entrypoint: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r", "/opt/ansible/my_rulebooks/my_rulebook.yml", "-i", "/tmp/inventory"]' From 37a582c0337b6c41ac1e2bcc0eb2584b91dcef56 Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Wed, 31 May 2023 09:51:06 -0400 Subject: [PATCH 4/6] Remove entrypoint from decision environment definition --- minimal-decision-environment.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/minimal-decision-environment.yml b/minimal-decision-environment.yml index b40da88f..cf691a04 100644 --- a/minimal-decision-environment.yml +++ b/minimal-decision-environment.yml @@ -23,6 +23,3 @@ dependencies: package_pip: ansible-runner system: - java-17-openjdk-devel [platform:rpm] -options: - container_init: - entrypoint: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r"]' From c6deacead98784f65b75910075802faf699e3f1a Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Wed, 31 May 2023 15:49:01 -0400 Subject: [PATCH 5/6] Change up some of the docs to point out some optional behavior. Add builder to the dev requirements. --- docs/decision_environment.rst | 11 ++++++++--- requirements_dev.txt | 2 ++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/decision_environment.rst b/docs/decision_environment.rst index c56415f8..17b7e8e5 100644 --- a/docs/decision_environment.rst +++ b/docs/decision_environment.rst @@ -57,12 +57,12 @@ The minimal decision environment is a good starting point, but you will likely w version: 2.10.1 options: container_init: - entrypoint: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r", "my_namespace.my_awesome_collection.my_rulebook", "-i", "/tmp/inventory"]' + 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 `addtional-build-steps`_ +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 @@ -89,4 +89,9 @@ and then making use of Containerfile commands to ADD or COPY to get the files in - 'COPY my_rulebook.yml /opt/ansible/my_rulebooks' options: container_init: - entrypoint: '["/opt/builder/bin/entrypoint","ansible-rulebook", "-r", "/opt/ansible/my_rulebooks/my_rulebook.yml", "-i", "/tmp/inventory"]' + 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/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 From a6e68ec93a588f9b9d320dd0190be8b0af121cda Mon Sep 17 00:00:00 2001 From: Matthew Jones Date: Thu, 1 Jun 2023 09:35:55 -0400 Subject: [PATCH 6/6] Fix extension error in de docs --- docs/decision_environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decision_environment.rst b/docs/decision_environment.rst index 17b7e8e5..9d96f23b 100644 --- a/docs/decision_environment.rst +++ b/docs/decision_environment.rst @@ -10,7 +10,7 @@ A basic and minimal decision_environment is included at the root of the reposito .. code-block:: shell - ansible-builder build -f minimal-decision-environment.yaml -t minimal-decision-environment:latest + 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.