Configuration¶

This page shows where the Ansible configuration lives and how to make the common changes: privilege escalation, remote hosts, more collections, vault and AWS access.

Where things live¶

Path	What it is
`/etc/ansible/ansible.cfg`	Configuration. Created on first boot and not overwritten afterwards.
`/etc/ansible/hosts`	Inventory. Starts with `localhost` only.
`/etc/ansible/vault-password`	Vault password generated on first boot. Root only.
`/var/lib/ansible-core/workspace`	Your playbooks. Owned by `ubuntu`. Holds the example `site.yml`.
`/opt/ansible-core/venv`	Python 3.12 environment with ansible-core.
`/opt/ansible-core/collections`	Installed collections.

The commands in /usr/local/bin use /etc/ansible/ansible.cfg unless you set ANSIBLE_CONFIG to another file.

The main settings in the shipped configuration:

[defaults]
inventory = /etc/ansible/hosts
collections_path = /opt/ansible-core/collections
interpreter_python = /opt/ansible-core/venv/bin/python
local_tmp = /var/lib/ansible-core/tmp
retry_files_enabled = False
host_key_checking = True
forks = 5
timeout = 10

[privilege_escalation]
become = False

Run tasks as root¶

Privilege escalation is off. To let a run change system files on the instance, ask for it on the command line:

ansible-playbook --become /var/lib/ansible-core/workspace/<playbook>.yml

Or set become: true on the play or task that needs it. To make it the default for every run, set become = True under [privilege_escalation] in ansible.cfg.

Manage remote hosts¶

The inventory starts with one host, the instance itself:

[local]
localhost ansible_connection=local ansible_python_interpreter=/opt/ansible-core/venv/bin/python ansible_host=127.0.0.1

To manage other machines over SSH:

Add them to /etc/ansible/hosts (as root) in a group of their own. Set their Python interpreter, because ansible.cfg points the default at this instance's virtual environment, which other hosts do not have:
```
[web]
<host-name> ansible_host=<private-ip> ansible_user=<remote-user> ansible_python_interpreter=/usr/bin/python3
```
Put the SSH private key for those hosts in the ubuntu user's ~/.ssh and make sure the instance can reach them on port 22.
Host key checking is on. Connect once with ssh and verify each host key before you run a playbook, so it lands in ~/.ssh/known_hosts.
Test the connection:
```
ansible web -m ansible.builtin.ping
```

Use SSH keys, not passwords. Once the inventory has other hosts, ansible-inventory --sushi-check-local and the walkthrough script report an error: they check only the default, localhost-only setup.

Add collections¶

ansible.posix 2.2.2 and ansible.utils 6.1.1 are installed. To add others, install them into the shared collections path as root. The instance needs outbound internet access to Ansible Galaxy:

sudo ansible-galaxy collection install <namespace.collection> -p /opt/ansible-core/collections

Some collections need extra Python libraries. Install those into /opt/ansible-core/venv, not into the system Python.

Use Ansible Vault¶

First boot creates a random vault password in /etc/ansible/vault-password. Only root can read it, so run vault commands with sudo:

sudo ansible-vault encrypt --vault-password-file /etc/ansible/vault-password <file>
sudo ansible-vault view --vault-password-file /etc/ansible/vault-password <file>

Encrypted files cannot be read without this password, and it exists only on this instance. Keep a copy somewhere you trust, see Backups. Never commit it to a repository.

Call AWS from playbooks¶

The image does not call AWS and does not include the amazon.aws collection. To manage AWS resources:

Create an IAM role that allows only the actions and resources your playbooks need, and attach it to the instance as its instance profile.
Install the collections and Python libraries your playbooks use.
Let them pick up credentials from the instance role. Do not put access keys in playbooks, ansible.cfg or user data.