sr2c.podman.podman_networks role – Create Podman network quadlets

Note

This role is part of the sr2c.podman collection (version 0.0.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install sr2c.podman.

To use it in a playbook, specify: sr2c.podman.podman_networks.

Entry point main – Create Podman network quadlets

Synopsis

  • Creates the network quadlets for a rootless Podman user from podman_networks_config, and corrects any configuration or runtime drift.

  • Podman only reads a network’s options when it creates the network. Quadlet runs podman network create --ignore, so changing Subnet=, Internal= or IPRange= in a quadlet does nothing to a network that already exists. This role inspects each live network, and when one differs from its definition it stops podman_networks_stop_units, removes the network and restarts <name>-network.service to create it again.

  • The role fails before changing anything if an entry has an unknown option or the wrong type. The role is not aware of networks defined by previous calls for the same user, so keep all of one user’s subnets in one call.

  • In order to avoid issues with inheritance or priority, the role will fail if anywhere under ~/.config/containers/systemd there is a network drop-in directory (<name>.network.d, a truncated one such as foo-.network.d, or network.d), a .network quadlet below the top level, or a directory named *.network.

  • podman_networks_config should contain every network the user should have. When podman_networks_prune is true, the default, the role also removes any other .network quadlet in ~/.config/containers/systemd, and any other loaded <name>-network.service that quadlet generated, along with its Podman network, so deleting an entry retires the network without the need for additional guard tasks.

  • Enforces that the quadlet’s name <name>.network matches the NetworkName=<name> entry.

  • Requires the jsonschema and netaddr Python libraries on the controller.

Parameters

Parameter

Comments

podman_networks_config

dictionary

The networks, keyed by name. The name is the quadlet file name (<name>.network), the Podman network name (NetworkName=<name>) and the systemd unit (<name>-network.service), so containers use Network=<name>.network.

subnet (string). IPv4 subnet in CIDR form, /8 to /30, with no host bits set, for example 10.89.244.0/24. Omit it to let Podman pick one; the role then doesn’t check the subnet. Fixed subnets should go inside 10.89.0.0/16 but well above 10.89.0.0/24, where Podman starts assigning subnets automatically.

ip_range (string, needs subnet). Addresses Podman hands out automatically, as <first>-<last> inside subnet and excluding its network and broadcast addresses, for example 10.89.244.128-10.89.244.254. Keep fixed addresses (Network=<name>.network:ip=...) outside it, so Podman can’t give one of them to another container.

internal (boolean, default false). true makes the network internal, so nothing on it can reach the internet.

comment (string). Written at the top of the quadlet, one # line per line.

state (present or absent, default present). absent removes the quadlet, its service and the network, even when podman_networks_prune is false.

Default: {}

podman_networks_podman_rootless_user

string / required

The rootless Podman user that owns the networks. The calling role passes its own *_podman_rootless_user.

podman_networks_prune

boolean

Remove every other network quadlet in ~/.config/containers/systemd, and every other loaded quadlet <name>-network.service, along with its Podman network, so deleting an entry from podman_networks_config retires the network.

Set to false when something else also manages networks for this user; then only entries with state=absent are removed.

Choices:

  • false

  • true ← (default)

podman_networks_stop_units

list / elements=string

User units to stop before a network is removed or recreated, usually the stack’s target and anything else on the network, for example link.target and nginx.service.

They are only stopped when a network is actually removed or recreated, because podman network rm --force removes any container still attached. They are not started again; the calling role should ensure services are running afterwards.

Default: []

Authors

Entry point verify – Check the runtime networks match their definitions, once the stack has started

Synopsis

  • Fails if a network in podman_networks_config is missing, or its subnet, internal flag or IP range differs from its definition.

  • Also fails on network drop-in directories and nested .network quadlets, as the main entry point does.

  • Run it once the calling role has started its stack, with the same variables as the main entry point.

Parameters

Parameter

Comments

podman_networks_config

dictionary

The same networks passed to the main entry point; see podman_networks_config for the options.

Default: {}

podman_networks_podman_rootless_user

string / required

The rootless Podman user that owns the networks.

Authors