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)