containers.podman.podman_network module – Manage podman networks

Note

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

You might already have this collection installed if you are using the ansible package. 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)

containers.podman.podman_network module – Manage podman networks

Synopsis

Requirements

Parameters

Examples

Return Values