containers.podman.podman_network module – Manage podman networks

Note

This module is part of the containers.podman collection (version 1.16.2).

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 containers.podman. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: containers.podman.podman_network.

New in containers.podman 1.0.0

Synopsis

• Manage podman networks with podman network command.

Requirements

The below requirements are needed on the host that executes this module.

• podman

Parameters

Parameter	Comments
debug boolean	Return additional information which can be helpful for investigations. Choices: false ← (default) true
disable_dns boolean	disable dns plugin (default “false”) Choices: false true
dns list / elements=string	Set network-scoped DNS resolver/nameserver for containers in this network. If not set, the host servers from /etc/resolv.conf is used.
driver string	Driver to manage the network (default “bridge”)
executable string	Path to podman executable if it is not in the $PATH on the machine running podman Default: "podman"
force boolean	Remove all containers that use the network. If the container is running, it is stopped and removed. Choices: false ← (default) true
gateway string	IPv4 or IPv6 gateway for the subnet
interface_name string	For bridge, it uses the bridge interface name. For macvlan, it is the parent device on the host (it is the same as ‘opt.parent’)
internal boolean	Restrict external access from this network (default “false”) Choices: false true
ip_range string	Allocate container IP from range
ipam_driver string	Set the ipam driver (IP Address Management Driver) for the network. When unset podman chooses an ipam driver automatically based on the network driver Choices: "host-local" "dhcp" "none"
ipv6 boolean	Enable IPv6 (Dual Stack) networking. You must pass a IPv6 subnet. The subnet option must be used with the ipv6 option. Idempotency is not supported because it generates subnets randomly. Choices: false true
macvlan string	Create a Macvlan connection based on this device
name string / required	Name of the network
net_config list / elements=dictionary	List of dictionaries with network configuration. Each dictionary should contain ‘subnet’ and ‘gateway’ keys. ‘ip_range’ is optional.
gateway string / required	Gateway for the subnet
ip_range string	Allocate container IP from range
subnet string / required	Subnet in CIDR format
opt dictionary	Add network options. Currently ‘vlan’ and ‘mtu’ are supported.
bclim integer	Set the threshold for broadcast queueing. Must be a 32 bit integer. Setting this value to -1 disables broadcast queueing altogether.
bridge_name string	This option assigns the given name to the created Linux Bridge. Sets ‘com.docker.network.bridge.name’ option.
driver_mtu string	Sets the Maximum Transmission Unit (MTU) and takes an integer value. Sets ‘com.docker.network.driver.mtu’ option.
isolate boolean	This option isolates networks by blocking traffic between those that have this option enabled. Choices: false true
metric integer	Sets the Route Metric for the default route created in every container joined to this network. Can only be used with the Netavark network backend.
mode string	This option sets the specified ip/macvlan mode on the interface.
mtu integer	MTU size for bridge network interface.
no_default_route string	If set to 1, Podman will NOT automatically add a default route to subnets.
parent string	The host device which should be used for the macvlan interface (it is the same as ‘interface’ in that case). Defaults to the default route interface.
vlan integer	VLAN tag for bridge which enables vlan_filtering.
vrf string	This option assigns a VRF to the bridge interface. It accepts the name of the VRF and defaults to none. Can only be used with the Netavark network backend.
quadlet_dir path	Path to the directory to write quadlet file in. By default, it will be set as /etc/containers/systemd/ for root user, ~/.config/containers/systemd/ for non-root users.
quadlet_file_mode any	The permissions of the quadlet file. The quadlet_file_mode can be specied as octal numbers or as a symbolic mode (for example, u+rwx or u=rw,g=r,o=r). For octal numbers format, you must either add a leading zero so that Ansible’s YAML parser knows it is an octal number (like 0644 or 01777) or quote it (like '644' or '1777') so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. If quadlet_file_mode is not specified and the quadlet file does not exist, the default '0640' mask will be used when setting the mode for the newly created file. If quadlet_file_mode is not specified and the quadlet file does exist, the mode of the existing file will be used. Specifying quadlet_file_mode is the best way to ensure files are created with the correct permissions.
quadlet_filename string	Name of quadlet file to write. By default it takes name value.
quadlet_options list / elements=string	Options for the quadlet file. Provide missing in usual network args options as a list of lines to add.
recreate boolean	Recreate network even if exists. Choices: false ← (default) true
route list / elements=string	A static route in the format <destination in CIDR notation>,<gateway>,<route metric (optional)>. This route will be added to every container in this network.
state string	State of network, default ‘present’ Choices: "present" ← (default) "absent" "quadlet"
subnet string	Subnet in CIDR format

Examples

- name: Create a podman network
  containers.podman.podman_network:
    name: podman_network
  become: true

- name: Create internal podman network
  containers.podman.podman_network:
    name: podman_internal
    internal: true
    ip_range: 192.168.22.128/25
    subnet: 192.168.22.0/24
    gateway: 192.168.22.1
  become: true

- name: Create Quadlet file for podman network
  containers.podman.podman_network:
    name: podman_network
    state: quadlet
    quadlet_options:
      - IPv6=true
      - Label="ipv6 network"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

network list / elements=string

Facts from created or updated networks Returned: always Sample: [{"created": "2024-07-13T15:43:36.548472483+03:00", "dns_enabled": true, "driver": "bridge", "id": "3f46dc2626fe082b1ec703bc74d048765c1110c9eab7d61e33344e212279402c", "internal": false, "ipam_options": {"driver": "host-local"}, "ipv6_enabled": false, "name": "virtuals", "network_interface": "podman2", "subnets": [{"gateway": "10.99.99.1", "subnet": "10.99.99.0/24"}]}]

Authors

• Sagi Shnaidman (@sshnaidm)

Collection links

• Issue Tracker
• Repository (Sources)