Frequently asked questions
The ansible.cfg
file
Where should the ansible.cfg
file go when using an execution environment?
The easiest place to have the ansible.cfg
is in the project directory adjacent to the playbook. The playbook directory is automatically mounted in the execution environment and the ansible.cfg
file will be found. If the ansible.cfg
file is in another directory, the ANSIBLE_CONFIG
variable needs to be set and the directory specified as a custom volume mount. (See the settings guide for execution-environment-volume-mounts
)
Where should the ansible.cfg
file go when not using an execution environment?
Ansible will look for the ansible.cfg
in the typical locations when not using an execution-environment. (See the ansible docs for the possibilities)
Placement of ansible collections
Where should ansible collections be placed when using an execution environment?
The easiest place to have ansible collections is in the project directory, in a playbook adjacent collections directory. (eg ansible-galaxy collections install ansible.utils -p ./collections
). The playbook directory is automatically mounted in the execution environment and the collections should be found. Another option is to build the collections into an execution environment using ansible builder. This was done to help playbook developers author playbooks that are production ready, as both ansible controller and awx support playbook adjacent collection directories. If the collections are in another directory, the ANSIBLE_COLLECTIONS_PATHS
variable needs to be set and the directory specified as a custom volume mount. (See the settings guide for execution-environment-volume-mounts
)
Where should ansible collections be placed when not using an execution environment?
When not using an execution environment, ansible will look in the default locations for collections. For more information about these, check out the collections guide.
SSH keys
How do I use my SSH keys with an execution environment?
The simplest way to use SSH keys with an execution environment is to use ssh-agent
and use default key names. Register keys as needed if they do not use one of the default key names. (~/.ssh/id_rsa
, ~/.ssh/id_dsa
, ~/.ssh/id_ecdsa
, ~/.ssh/id_ed25519
, and ~/.ssh/identity
. (eg ssh-add ~/.ssh/my_key
). ansible-navigator
will automatically setup and enable the use of ssh-agent
within the execution environment by volume mounting the SSH authentication socket path and setting the SSH_AUTH_SOCK environment variable. (eg
-v /run/user/1000/keyring/:/run/user/1000/keyring/ -e SSH_AUTH_SOCK=/run/user/1000/keyring/ssh
(as seen in the ansible-navigator
log file when using an execution environment and --log-level debug
)
The use of ssh-agent
results in the simplest configuration and eliminates issues with SSH key passphrases when using ansible-navigator
with execution environments.
Additionally, ansible-navigator
will automatically volume mount the user’s SSH keys into the execution environment in 2 different locations to assist users not running ssh-agent
.
For compatibility with SSH connections using OpenSSH, the keys are mounted into the home directory of the default user within the execution environment as specified by the user’s entry in the execution environment’s
/etc/passwd
file. When using OpenSSH withoutssh-agent
, only keys using the default names (id_rsa
,id_dsa
,id_ecdsa
,id_ed25519
, andid_xmss
) will be used. The use ofansible_ssh_private_key_file
will enable the use of non-default named keys.
-v /home/current_user/.ssh/:/root/.ssh/
(as seen in the ansible-navigator
log file when using an execution environment and --log-level debug
)
For compatibility with SSH connections using
paramiko
, the keys are mounted into the home directory of the default user within the execution environment as specified by theHOME
environment variable within the execution environment. When usingparamiko
withoutssh-agent
, only key using default names (id_rsa
,id_dsa
orid_ecdsa
, andid_ed25519
) will by used. The use ofansible_ssh_private_key_file
will enable the use of non-default named keys.
-v /home/current_user/.ssh/:/home/runner/.ssh/
(as seen in the ansible-navigator
log file when using an execution environment and --log-level debug
)
Note: When using ansible_ssh_private_key_file
with execution environments, the path to the key needs to reference it’s location after being volume mounted to the execution environment. (eg /home/runner/.ssh/key_name
or /root/.ssh/key_name
). It may be convenient to specify the path to the key as ~/.ssh/key_name
which will resolve to the user’s home directory with or without the use of an execution environment.
Compatibility with ansible-*
utilities
Why does the playbook hang when vars_prompt
, pause/prompt
or --ask-pass
is used?
By default ansible-navigator
runs the playbook in the same manner that ansible controller and AWX would run the playbook. This was done to help playbook developers author playbooks that would be ready for production. If the use of vars_prompt
, pause\prompt
or --ask-pass
can not be avoided, disabling playbook-artifact
creation and using --mode stdout
causes ansible-navigator
to run the playbook in a manner that is compatible with ansible-playbook
and allows for user interaction.
$ ansible-navigator run site.yml --mode stdout --playbook-artifact-enable false --ask-pass
How can I use ansible-test
without having it locally installed?
The ansible-test
utility can be used from within an execution environment using the exec
subcommand.
$ cd ./collections/ansible_collections/ansible/utils/
$ ansible-navigator exec -- ansible-test sanity --python 3.8
How do I use ansible-playbook
parameters like --forks 15
?
All parameters not directly used by ansible-navigator
will be passed to the ansible-playbook
command. These can be provided inline after the ansible-navigator
parameters or delimited by a --
$ ansible-navigator run site.yml --forks 15
$ ansible-navigator run site.yml -- --forks 15
Other
How can complex commands be run inside an execution-environment?
The easiest way to pass complex commands to an execution environment is by using the --
delimiter. Everything after the --
will be passed into the execution-environment.
$ ansible-navigator exec -- ansible --version | head -n 1 | awk -F '\\[|\\]|\\s' '{print $4}'
2.12.4rc1.post0
Why did I get an error about /dev/mqueue
missing?
Although the /dev/mqueue
directory is not used by ansible-navigator
, it is currently required when using podman
. Not all operating systems have a /dev/mqueue
directory by default.
Please reference the documentation for your operating system related to POSIX message queues, or simply create the directory.
Something didn’t work, how can I troubleshoot it?
ansible-navigator
has reasonable logging messages, debug logging can be enabled with --log-level debug
. If you think you might have found a bug, please log an issue and include the details from the log file.