galcvua.nspawn

galcvua.nspawn provides an Ansible connection plugin for running normal Ansible tasks inside an existing systemd-nspawn machine. The controller uses SSH to reach the machine's host and systemd-run --machine= to execute commands inside the machine.

The first release intentionally has a narrow scope:

• the nspawn machine must already exist and be running;
• the systemd host is reached with the OpenSSH client;
• the SSH user must be allowed to invoke systemd-run --machine;
• commands run as root in the machine unless Ansible wraps them with become;
• file transfers stream through the machine and are not staged on its host.

nspawn_containers:
  hosts:
    web.container-host-01:
      ansible_connection: galcvua.nspawn.systemd_run
      ansible_host: container-host-01.example.com
      ansible_user: root
      ansible_nspawn_machine: web
      ansible_python_interpreter: /usr/bin/python3

ansible_host and ansible_user select the systemd host and its SSH user. ansible_nspawn_machine selects the machine in which tasks execute. Inventory names should include the systemd host when the same machine name can occur on more than one host.

The plugin accepts the usual SSH connection settings, including ansible_port, ansible_private_key_file, ansible_ssh_common_args, and ansible_ssh_extra_args. Key-based authentication is recommended. Streaming file transfers do not provide an interactive password prompt.

Pipelining avoids most temporary module files and is recommended:

[connection]
pipelining = true

• Ansible Core 2.16 or newer on the controller
• OpenSSH client on the controller
• systemd-run on the systemd-nspawn host
• /bin/sh and cat in the machine

The plugin uses these execution semantics:

systemd-run --machine=MACHINE --wait --pipe --quiet --collect \
  --service-type=exec -- /bin/sh -c COMMAND

Create the development environment and install the test dependency:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt

The commands use the virtual environment executables explicitly, so they do not depend on shell activation and never install into the system Python.

Run the unit tests with:

.venv/bin/python -m unittest discover -s tests/unit -v

Build the collection artifact with:

.venv/bin/ansible-galaxy collection build

GPL-3.0-or-later.