# 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)