diff --git a/knowledge base/ansible.md b/knowledge base/ansible.md
index f34b828..5c92014 100644
--- a/knowledge base/ansible.md
+++ b/knowledge base/ansible.md
@@ -23,6 +23,7 @@
1. [Role dependencies](#role-dependencies)
1. [Create custom filter plugins](#create-custom-filter-plugins)
1. [Execution environments](#execution-environments)
+ 1. [Build execution environments](#build-execution-environments)
1. [Secrets management](#secrets-management)
1. [Ansible Vault](#ansible-vault)
1. [Best practices](#best-practices)
@@ -770,6 +771,23 @@ See [Creating your own Ansible filter plugins].
Container images that can be used as Ansible control nodes.
+Prefer using `ansible-navigator` to `ansible-runner` for local runs as the latter is a pain in the ass to use directly.
+
+
+ Commands example
+
+```sh
+pip install 'ansible-builder' 'ansible-runner' 'ansible-navigator'
+ansible-builder build --container-runtime 'docker' -t 'example-ee:latest' -f 'definition.yml'
+ansible-runner -p 'test_play.yml' --process-isolation --container-image 'example-ee:latest'
+ansible-navigator run 'test_play.yml' -i 'localhost,' --execution-environment-image 'example-ee:latest' \
+ --mode 'stdout' --pull-policy 'missing' --container-options='--user=0'
+```
+
+
+
+### Build execution environments
+
Ansible Builder aids in the creation of Ansible Execution Environments.
Refer [Introduction to Ansible Builder] for how to build one.
@@ -854,19 +872,6 @@ collections:
-
- Commands example
-
-```sh
-pip install 'ansible-builder'
-ansible-builder build --container-runtime 'docker' -t 'example-ee:latest' -f 'definition.yml'
-ansible-runner -p 'test_play.yml' --container-image 'example-ee:latest'
-ansible-navigator run 'test_play.yml' -i 'localhost,' --execution-environment-image 'example-ee:latest' \
- --mode 'stdout' --pull-policy 'missing' --container-options='--user=0'
-```
-
-
-
## Secrets management
Refer [handling secrets in your Ansible playbooks].
@@ -1443,6 +1448,8 @@ Solution: use a version of `ansible-core` lower than 2.17.
- [Debugging tasks]
- [AWX]
- [Introduction to Ansible Builder]
+- [Ansible Navigator]
+- [Ansible Runner]
### Sources
@@ -1507,6 +1514,8 @@ Solution: use a version of `ansible-core` lower than 2.17.
[8 ways to speed up your ansible playbooks]: https://www.redhat.com/sysadmin/faster-ansible-playbook-execution
[ansible galaxy user guide]: https://docs.ansible.com/ansible/latest/galaxy/user_guide.html
+[ansible navigator]: https://ansible.readthedocs.io/projects/navigator/en/stable/
+[ansible runner]: https://ansible.readthedocs.io/projects/runner/en/stable/
[asynchronous actions and polling]: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_async.html
[automating helm using ansible]: https://www.ansible.com/blog/automating-helm-using-ansible
[blocks]: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_blocks.html
diff --git a/snippets/ansible/commands.sh b/snippets/ansible/commands.sh
index ffa11c6..fe272b0 100644
--- a/snippets/ansible/commands.sh
+++ b/snippets/ansible/commands.sh
@@ -27,7 +27,7 @@ ansible-galaxy init 'gitlab'
ansible-galaxy role init 'my_role'
ansible-galaxy role init --type 'container' --init-path 'gitlab' 'name'
-# Apply changes.
+# Run playbooks.
ansible-playbook -DK 'ansible/playbooks/local-network.hosts.configure.yml' \
-i 'inventory/local-network.ini' -l 'workstation.lan' -c 'local' -C
ansible-playbook 'gitlab.yml' \
@@ -42,10 +42,34 @@ ansible-playbook 'playbook.yaml' \
-e 'ansible_remote_tmp=/tmp/.ansible-\${USER}/tmp' \
-i 'i-0123456789abcdef0,' -D
ansible-playbook -i 'localhost,' -c 'local' -Dvvv 'playbook.yml' -t 'container_registry' --ask-vault-pass
+ansible-runner -p 'test_play.yml' --container-image 'example-ee:latest'
+# Run playbooks within Execution Environments.
+# Use the '=' between options and their arguments.
+ansible-runner run \
+ --container-volume-mount "$HOME/.aws:/runner/.aws:ro" \
+ --container-image '012345678901.dkr.ecr.eu-west-1.amazonaws.com/ansible-ee:1.2'
+ --process-isolation --process-isolation-executable 'docker' \
+ '.' --playbook 'playbook.yml' -i 'inventory.ini'
+ansible-navigator run 'playbook.yml' --execution-environment-image='ee/image'
+ansible-navigator \
+ --container-options='--platform=linux/amd64' --pull-policy='missing' \
+ --mode='stdout' \
+ --set-environment-variable='AWS_DEFAULT_REGION=eu-west-1' \
+ --pass-environment-variable='AWS_PROFILE' \
+ --execution-environment-volume-mounts="$HOME/.aws:/runner/.aws:ro" \
+ run \
+ --enable-prompts -i 'localhost,' \
+ 'playbook.yml' \
+ -DC -c 'local'
+
+# Debug runs
ANSIBLE_ENABLE_TASK_DEBUGGER=True ansible-playbook …
+
+# Time task execution
ANSIBLE_CALLBACKS_ENABLED='profile_tasks' ansible-playbook …
+# Validate playbooks
ansible-playbook 'path/to/playbook.yml' --syntax-check
# Ad-hoc commands.
@@ -58,7 +82,18 @@ venv/bin/ansible -i 'localhost ansible_python_interpreter=venv/bin/python,' -c '
ansible -i 'localhost,' -c 'local' -Cvvv 'localhost' \
-m 'ansible.builtin.template' -a 'src=anonymizer/templates/anonymize_data.sql.j2 dest=/tmp/anonymize_data.sql' \
-e 'country=ireland' -e '{"phone_codes":{"ireland":"+353"}}'
+ansible-runner run '.' -m 'debug' -a 'msg=hello' --hosts 'localhost'
+ansible-runner run '.' -m 'setup' --hosts 'localhost' \
+ --process-isolation --process-isolation-executable 'docker' --container-image 'me/ansible-ee:1.2'
+# Run roles
+# FIXME: check and test
+ansible-runner run 'path/to/dir' --role 'role-name' --role-var 'key1=value1 … keyN=valueN'
+
+# Clean up artifact directories
+ansible-runner run --rotate-artifacts
+
+# Encrypt/decrypt sensitive data with Vault
ansible-vault encrypt_string --name 'command_output' 'somethingNobodyShouldKnow'
ANSIBLE_VAULT_PASSWORD='ohSuchASecurePassword' ansible-vault encrypt --output 'ssh.key' '.ssh/id_rsa'
ansible-vault view 'ssh.key.pub' --vault-password-file 'password_file.txt'
@@ -73,3 +108,12 @@ ansible-doc -t 'strategy' -l
# Show plugin-specific docs and examples.
ansible-doc -t 'lookup' 'fileglob'
ansible-doc -t 'strategy' 'linear'
+
+# Run commands within Execution Environments.
+ansible-navigator exec
+AWS_PROFILE='AnsibleTaskExecutor' venv/bin/ansible-navigator \
+ --execution-environment-image='012345678901.dkr.ecr.eu-west-1.amazonaws.com/infra/ansible-ee' \
+ --execution-environment-volume-mounts="$HOME/.aws:/runner/.aws:ro" \
+ --pass-environment-variable='AWS_PROFILE' \
+ --set-environment-variable='AWS_DEFAULT_REGION=eu-west-1' \
+ exec -- aws sts get-caller-identity --no-cli-pager