Connection plugins: SSH is a default, not a law · Ansible

Stage 5 of a run opens a connection. Nothing about the rest of the architecture requires that connection to be SSH — the payload has to reach the target and the JSON has to come back, and any mechanism that can do both will serve.

Ansible makes this explicit: the transport is a plugin. SSH is the default because it is what nearly everyone has, not because the model depends on it.

This matters more than it sounds, and for a reason that has nothing to do with exotic transports. Your tests and your production runs may use different connection plugins, and if they do, they are exercising different code paths. A role that passes under one is not thereby proven under the other.

What ships in `ansible-core`

Fewer than most people expect. Verified on ansible-core 2.21.3:

Read-only / Safethe complete set in core— Inspects the installed collection only. This is every connection plugin in ansible-core 2.21.3, with no additional collections installed.

$ ansible-doc -t connection -l

ansible.builtin.local execute on controller
ansible.builtin.psrp  Run tasks over Microsoft PowerShell Remoting Protocol
ansible.builtin.ssh   connect via SSH client binary
ansible.builtin.winrm Run tasks over Microsoft's WinRM

Four. Two of them are for Windows.

Everything else — Docker, Podman, LXD, Kubernetes, network devices, serial consoles — arrives in a collection. That is not a second-class status; community.docker and ansible.netcommon are the normal way to get those transports. It does mean they are a dependency you declare and pin, which the collections part of this course treats as a discipline rather than an afterthought.

What a connection plugin is responsible for

Narrower than people assume, which is what makes the model work.

A connection plugin must be able to:

Establish and tear down a connection to the target.
Transfer a file to the target (put_file).
Retrieve a file from the target (fetch_file).
Execute a command on the target and return stdout, stderr and an exit status (exec_command).

That is the interface. Everything above it — building the module payload, evaluating changed_when, rendering templates, deciding when — is transport-independent controller-side logic, and it does not know or care how the bytes arrived.

Why the same module works over every transport

A module is a Python program that reads arguments, does something, and prints JSON. It never learns how it got there.

That is the design decision that makes the plugin model work, and it has a specific consequence: adding a transport does not require touching any module. ansible.builtin.file works over SSH, over a Docker exec, and over a local connection, unmodified, because in every case the connection plugin’s job was to get the wrapper onto the target and run it.

The inverse also holds, and it is the practically important half. A transport cannot fix a module. If a module needs Python on the target and the target has none, no connection plugin helps — the network path was never the problem. This is why the raw module exists as a bootstrapping escape hatch: it runs a shell command with no payload at all, and it is the only thing that works on a host with no interpreter.

It also explains where check mode lives. Check mode is a per-module capability, not a transport feature, so switching transports never changes whether a task can be predicted. That is a distinction people get wrong when a --check run behaves differently in a container scenario, and the actual difference is almost always somewhere else.

The plugins you will actually meet

`ssh`

The default. Shells out to the system ssh binary, which means your ~/.ssh/config, your agent, your jump-host configuration and your known_hosts all apply exactly as they would interactively.

That is a significant property. Ansible is not reimplementing SSH; it is driving the client you already have, so anything that works from your shell works here, including ProxyJump, certificate authentication and Match blocks.

Its default arguments are worth knowing, because they explain a performance characteristic that otherwise looks like magic:

Read-only / Safethe default SSH arguments— Inspects plugin documentation only. Verified on ansible-core 2.21.3.

$ ansible-doc -t connection ssh | grep -A 12 '^   ssh_args'

   ssh_args  Arguments to pass to all SSH CLI tools.
      set_via:
        env:
        - name: ANSIBLE_SSH_ARGS
        ini:
        - key: ssh_args
          section: ssh_connection
        vars:
        - name: ansible_ssh_args
      default: -C -o ControlMaster=auto -o ControlPersist=60s
      type: string

ControlMaster=auto with ControlPersist=60s means the first connection to a host opens a control socket and subsequent connections reuse it for sixty seconds. Given the previous lesson’s count of round trips per task, this is doing a great deal of work — without it, every task would pay a full SSH handshake.

The SSH part of this course covers tuning it. What matters here is that it exists and that it is a connection-plugin setting rather than something Ansible does internally.

`local`

Runs tasks on the controller itself. No network, no SSH — it forks a process and runs the payload with the controller’s own Python.

Note that it is still a connection: the same payload is built, written to a temporary directory and executed. The trace looks identical to a remote run minus the network.

This is what delegate_to: localhost and connection: local use, and it is how controller-side work — calling an API, updating a load balancer, writing a report — is expressed as a task.

`winrm` and `psrp`

Windows targets. Different transport, different execution model on the far side — PowerShell rather than Python — and a different set of modules. Out of scope for this course beyond knowing they exist and that the architecture accommodates them.

Container connections, from collections

community.docker.docker and containers.podman.podman execute inside a container by driving the container runtime, with no SSH and no sshd in the container.

This is how Molecule tests roles quickly, and it is the source of the most consequential point in this lesson.

Network device connections, from collections

ansible.netcommon.network_cli connects to a switch or router and drives its CLI. There is no Python on the target and no payload transfer — the modules run on the controller and send configuration commands over the connection.

That is a genuinely different execution model, not just a different transport, and the network part of this course treats it separately. The architectural point is that the plugin boundary is wide enough to accommodate it.

The consequence: your test transport decides what your test proves

This is why the lesson exists.

A Molecule scenario using the Docker connection and a production run using SSH differ in more than the network path:

	Container scenario	Production VM over SSH
Transport	Container runtime exec	SSH to `sshd`
PID 1	Usually the entrypoint, often not an init	`systemd`
Service management	Frequently unavailable or stubbed	Real `systemctl`
Reboot	Not possible	Possible, and sometimes required
Kernel parameters	Shared with the host; many are not settable	Own namespace-wide settings
Storage	Container filesystem	Real block devices, mounts, quotas
Privilege escalation	Often already root, so `become` is untested	Real `sudo` path
SSH itself	Not exercised at all	The commonest source of production failures

Read the last row carefully. A container scenario does not test SSH, authentication, host keys, or ProxyJump — and a large share of the problems that stop a production run are exactly those. A role with perfect container test coverage can still fail on every host in the fleet for a reason the tests were structurally unable to see.

Container tests are worth having, and they prove a specific thing

None of this is an argument against container testing. It is fast, it is cheap, it catches real defects, and for a role that installs a package and templates a file it is close to sufficient.

What it proves is that the task logic is correct: the right arguments, the right conditionals, the right idempotency for the operations it could perform. What it does not prove is that the role works on a machine with an init system, a real sudo path, real storage and a network you have to authenticate across.

The testing part of this course develops the distinction properly. The architectural half of it is in this lesson: they are different connection plugins, so they are different code paths, so a pass under one is not a pass under the other.

For anything depending on systemd as PID 1, reboot, kernel behaviour, network reconfiguration or storage, use a virtual machine. The Docker course covers what a container’s process model actually is, in processes, signals and PID 1, and it is worth reading if the reason is not obvious to you.

Choosing and setting the connection

The connection is a variable like any other, which means it can be set per host, per group, per play or per task.

# inventory/hosts.yml
all:
  children:
    switches:
      hosts:
        sw01:
          ansible_host: 192.0.2.51
      vars:
        ansible_connection: ansible.netcommon.network_cli
        # Platform-specific, and fully qualified: the value names the
        # collection that owns the platform, not the connection plugin.
        ansible_network_os: vyos.vyos.vyos

    controller_side:
      hosts:
        localhost:
          ansible_connection: local

Set it in inventory rather than in the playbook wherever you can. A playbook that hard-codes a connection cannot be reused against a different environment, and — more importantly for this course — the inventory is where a reader looks to answer “what will this run actually do to which hosts”. Transport is part of that answer.

The role that passed every test and failed on every host

A team develops a role that configures and starts an application service. Molecule scenario against a Debian container, full coverage, idempotency test passes, green for weeks.

First production run: fails on every host at the task that starts the service.

What the container scenario did: the image had no init system, so the team had used a task that starts the process directly rather than through systemd, guarded with a conditional on whether systemd was available. The conditional was written during development to make the tests pass.

What production did: the conditional evaluated the other way, took the systemd branch for the first time ever, and that branch had never been executed by anything. It contained a unit file with a typo.

Why the obvious diagnosis is wrong: the instinct is that production differs from the test environment in some subtle way, and people go looking for the difference in the hosts. The difference is not subtle and it is not in the hosts — it is that the tests exercised a branch production never takes, and never exercised the branch production always takes. Coverage was high and it was coverage of the wrong path.

The general lesson: a conditional added to make a test pass is a signal that the test environment cannot exercise the real path. The honest responses are to test on something with an init system, or to accept that the systemd branch is untested and say so — not to let the green result stand in for a claim it cannot support.

Knowledge check

Why this matters

Two practical consequences, one immediate and one structural.

The immediate one is that a test result is a claim about a specific code path, and the connection plugin is part of what determines which path ran. When somebody says “the role is tested”, the useful follow-up is “over which transport”, because the answer decides whether SSH, sudo, systemd and storage were in scope at all.

The structural one is that the plugin boundary is narrow and that is deliberate: four operations, and everything above them is transport-independent. That is why the same module works over SSH, a container runtime and a local fork without modification, and why a transport cannot rescue a module whose requirements the target does not meet. When you later meet raw as the bootstrapping escape hatch, or network modules that execute on the controller rather than the device, both are legible from this boundary rather than needing to be memorised as exceptions.

What ships in ansible-core