community.proxmox.proxmox_node_network module – Manage network interfaces on Proxmox nodes

Note

This module is part of the community.proxmox collection (version 1.5.0).

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

To use it in a playbook, specify: community.proxmox.proxmox_node_network.

New in community.proxmox 1.4.0

Synopsis 

This module allows you to manage network interfaces on Proxmox nodes.
Supports various interface types including bridge, bond, eth, vlan, and OVS interfaces.
Network configuration changes are staged and must be explicitly applied using state=apply to take effect.
Changes made with state=present or state=absent are only staged and will not affect the running network configuration until applied.

Requirements 

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

ipaddress
proxmoxer >= 2.0
requests

Parameters 

Parameter	Comments
api_host string / required	Specify the target host of the Proxmox VE cluster. Uses the `PROXMOX_HOST` environment variable if not specified.
api_password string	Specify the password to authenticate with. Uses the `PROXMOX_PASSWORD` environment variable if not specified.
api_port integer	Specify the target port of the Proxmox VE cluster. Uses the `PROXMOX_PORT` environment variable if not specified.
api_token_id string	Specify the token ID. Uses the `PROXMOX_TOKEN_ID` environment variable if not specified.
api_token_secret string	Specify the token secret. Uses the `PROXMOX_TOKEN_SECRET` environment variable if not specified.
api_user string / required	Specify the user to authenticate with. Uses the `PROXMOX_USER` environment variable if not specified.
autostart boolean	Automatically start interface on boot. Supported for `eth`, `bridge`, `bond`, `vlan`, and `OVSBridge` interface types. Choices: `false` `true`
bond_mode string	Bonding mode for `bond` or `OVSBond` interface types. Valid values for `bond` interface type: `balance-rr`, `active-backup`, `balance-xor`, `broadcast`, `802.3ad`, `balance-tlb`, `balance-alb` Valid values for `OVSBond` interface type: `active-backup`, `balance-slb`, `lacp-balance-slb`, `lacp-balance-tcp` Choices: `"balance-rr"` `"active-backup"` `"balance-xor"` `"broadcast"` `"802.3ad"` `"balance-tlb"` `"balance-alb"` `"balance-slb"` `"lacp-balance-slb"` `"lacp-balance-tcp"`
bond_primary string	Primary interface for active-backup bond. Required for `active-backup` bonding mode. Supported for `bond` interface type only. Primary interface should be specified in `slaves` parameter as well.
bond_xmit_hash_policy string	Transmit hash policy for bond type. Required for `balance-xor` and `802.3ad` bonding modes. Choices: `"layer2"` `"layer2+3"` `"layer3+4"`
bridge_ports string	Specify the interfaces you want to add to your bridge. Supported for `bridge` interface type only. Can be deleted by setting to empty string `''`.
bridge_vids string	Specify the allowed VLANs (e.g., ‘2 4 100-200’). Only used if `bridge_vlan_aware` is enabled. Supported for `bridge` interface type only. Can be deleted by setting to empty string `''`.
bridge_vlan_aware boolean	Enable bridge VLAN support. Supported for `bridge` interface type only. Choices: `false` `true`
cidr string	IPv4 host address with prefix length (e.g., ‘192.168.1.10/24’). Supported for `eth`, `bridge`, `bond`, `vlan`, `OVSBridge`, and `OVSIntPort` interface types. Can be deleted by setting to empty string `''`.
cidr6 string	IPv6 host address with prefix length (e.g., ‘2001:db8::10/64’). Supported for `eth`, `bridge`, `bond`, `vlan`, `OVSBridge`, and `OVSIntPort` interface types. Can be deleted by setting to empty string `''`.
comments string	Comments for the interface configuration. Supported for `eth`, `bridge`, `bond`, `vlan`, `OVSBridge`, `OVSBond`, and `OVSIntPort` interface types. Can be deleted by setting to empty string `''`.
gateway string	Default IPv4 gateway address. Supported for `eth`, `bridge`, `bond`, `vlan`, `OVSBridge`, and `OVSIntPort` interface types. Can be deleted by setting to empty string `''`.
gateway6 string	Default IPv6 gateway address. Supported for `eth`, `bridge`, `bond`, `vlan`, `OVSBridge`, and `OVSIntPort` interface types. Can be deleted by setting to empty string `''`.
iface string	Network interface name. Required when `state=present` or `state=absent`. For `vlan` interface type, should be in format `vlanXY` (e.g., `vlan100`) or `iface_name.vlan_id` (e.g., `eth0.100`).
iface_type string	Type of network interface. Required when `state=present`. Cannot be changed after interface creation. Choices: `"bridge"` `"bond"` `"eth"` `"vlan"` `"OVSBridge"` `"OVSBond"` `"OVSIntPort"`
mtu integer	Maximum Transmission Unit (1280 - 65520). Supported for `eth`, `bridge`, `bond`, `vlan`, `OVSBridge`, `OVSBond`, and `OVSIntPort` interface types. Can be deleted by setting to `-1`.
node string / required	The Proxmox node to manage network interfaces on.
ovs_bonds string	Interfaces used by OVS bonding device. (space separated) Required for `OVSBond` interface type.
ovs_bridge string	OVS bridge name. Required for `OVSBond` and `OVSIntPort` interface types.
ovs_options string	OVS interface options. Supported for `OVSBridge`, `OVSBond`, and `OVSIntPort` interface types. Can be deleted by setting to empty string `''`.
ovs_ports string	Interfaces to add to OVS bridge. Supported for `OVSBridge` interface type only. Can be deleted by setting to empty string `''`.
ovs_tag integer	VLAN tag (1 - 4094). Supported for `OVSBond` and `OVSIntPort` interface types. Can be deleted by setting to `-1`.
slaves string	Interfaces used by the bonding device (space separated). Required for `bond` interface type.
state string	The desired state of the network interface. `present` and `absent` stage changes but do not apply them to the running configuration. `apply` applies all staged network configuration changes to the running configuration. `revert` discards all staged network configuration changes. Choices: `"present"` ← (default) `"absent"` `"apply"` `"revert"`
validate_certs boolean	If `false`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. Uses the `PROXMOX_VALIDATE_CERTS` environment variable if not specified. Choices: `false` ← (default) `true`
vlan_raw_device string	Raw device for VLAN interface. Required if iface is in format ‘vlanXY’. Supported for `vlan` interface type only.

Attributes 

Attribute	Support	Description
action_group	Action group: community.proxmox.proxmox	Use `group/community.proxmox.proxmox` in `module_defaults` to set defaults for this module.
check_mode	Support: full Check mode is fully supported for all states.	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: full Check mode is fully supported for all states.	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Notes 

Note

Network configuration changes are staged and must be explicitly applied using state=apply to take effect.
Changes made with state=present or state=absent are only staged and will not affect the running network configuration until applied.
Interface type cannot be changed after creation. Delete and recreate the interface to change its type.
Ethernet interfaces (eth type) represent physical hardware and cannot be created via API. Only existing physical interfaces can be configured.
Bond and OVS bond interfaces must follow naming format bondX where X is a number between 0 and 9999 (e.g., bond0, bond1, bond9999).
VLAN interfaces support two naming formats: vlanXY (e.g., vlan100) and iface_name.vlan_id (e.g., eth0.100).
For vlanXY format, vlan_raw_device parameter is required.
For iface_name.vlan_id format, vlan_raw_device should not be specified.
Parameter deletion is supported for specific parameters. Set string parameters to empty string '' or integer parameters to -1 to delete them.
Deletable parameters: cidr, gateway, cidr6, gateway6, comments, mtu, bridge_ports, bridge_vids, ovs_ports, ovs_options, ovs_tag.
When state=apply or state=revert, only the node parameter is accepted. All other parameters are not allowed.

Examples 

# Configure a network interface
- name: Configure network interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: eth0
    iface_type: eth
    cidr: 192.168.1.10/24
    gateway: 192.168.1.1
    cidr6: 2001:db8::10/64
    gateway6: 2001:db8::1
    autostart: true
    mtu: 1500
    comments: "Management network"

# Create a simple bridge interface
- name: Create bridge interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vmbr0
    iface_type: bridge
    cidr: 192.168.1.10/24
    gateway: 192.168.1.1
    autostart: true

# Create a bond interface
- name: Create bond interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: bond0
    iface_type: bond
    bond_mode: active-backup
    bond_primary: eth0
    slaves: eth0 eth1
    cidr: 192.168.1.0/24
    gateway: 192.168.1.1

# Create a VLAN interface
- name: Create VLAN interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: eth0.100
    iface_type: vlan
    cidr: 192.168.100.10/24

# Create a VLAN interface with vlanXY format
- name: Create VLAN interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vlan100
    iface_type: vlan
    vlan_raw_device: eth0
    cidr: 192.168.100.0/24

# Create a complex bridge with VLAN awareness
- name: Create VLAN-aware bridge
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vmbr1
    iface_type: bridge
    bridge_ports: eth1 eth2
    bridge_vlan_aware: true
    bridge_vids: "2 4 100-200"
    cidr: 192.168.2.0/24
    gateway: 192.168.2.1
    mtu: 9000
    comments: "VLAN-aware bridge for trunking"

# Create an OVS bridge
- name: Create OVS bridge
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: ovsbr0
    iface_type: OVSBridge
    ovs_ports: eth3 eth4
    ovs_options: "updelay=5000"
    cidr: 192.168.3.10/24
    gateway: 192.168.3.1

# Create an OVS bond
- name: Create OVS bond
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: bond1  # Must follow bondX format where X is 0-9999
    iface_type: OVSBond
    bond_mode: active-backup
    ovs_bonds: eth5 eth6
    ovs_bridge: ovsbr0
    ovs_tag: 10
    ovs_options: "updelay=5000"

# Create an OVS internal port
- name: Create OVS internal port
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: ovsint0
    iface_type: OVSIntPort
    ovs_bridge: ovsbr0
    ovs_tag: 20
    ovs_options: "tag=20"
    cidr: 192.168.20.10/24
    gateway: 192.168.20.1

# Create interface with IPv6
- name: Create dual-stack interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vmbr2
    iface_type: bridge
    bridge_ports: eth7
    cidr: 192.168.4.0/24
    gateway: 192.168.4.1
    cidr6: 2001:db8::/64
    gateway6: 2001:db8::1
    autostart: true

# Remove an interface
- name: Remove interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: absent
    iface: vmbr0

# Apply network configuration
- name: Apply network
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: apply

# Complete workflow example
- name: Create interface and apply changes
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vmbr1
    iface_type: bridge
    cidr: 192.168.2.10/24
    gateway: 192.168.2.1

- name: Apply staged network changes
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: apply

# Revert network configuration changes
- name: Revert network changes
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: revert

# Using API token authentication
- name: Create interface with API token
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_token_id: my-token
    api_token_secret: my-token-secret
    node: pve01
    state: present
    iface: vmbr3
    iface_type: bridge
    cidr: 192.168.5.10/24
    gateway: 192.168.5.1

# Delete specific parameters from an interface
- name: Remove IP configuration from bridge
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vmbr0
    iface_type: bridge
    cidr: ""          # Delete IPv4 CIDR
    gateway: ""       # Delete IPv4 gateway
    cidr6: ""         # Delete IPv6 CIDR
    gateway6: ""      # Delete IPv6 gateway
    comments: ""      # Delete comments
    mtu: -1           # Delete MTU (use -1 for integer parameters)

# Remove bridge ports and VLAN configuration
- name: Remove bridge ports and VLAN settings
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: vmbr1
    iface_type: bridge
    bridge_ports: ""  # Remove all bridge ports
    bridge_vlan_aware: true
    bridge_vids: ""   # Remove VLAN IDs (requires bridge_vlan_aware: true)

# Remove OVS-specific parameters
- name: Remove OVS options and ports
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: ovsbr0
    iface_type: OVSBridge
    ovs_ports: ""     # Remove OVS ports
    ovs_options: ""   # Remove OVS options
    ovs_tag: -1       # Remove VLAN tag (use -1 for integer parameters)

# Configure existing physical Ethernet interface
- name: Configure physical Ethernet interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: eth0
    iface_type: eth
    cidr: 192.168.1.10/24
    gateway: 192.168.1.1
    mtu: 9000
    comments: "Management interface"
  # Note: eth interfaces represent physical hardware and cannot be created via API
  # Only existing physical interfaces can be configured

# Create bond interface with proper naming format
- name: Create bond interface
  community.proxmox.proxmox_node_network:
    api_host: proxmox.example.com:8006
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: bond0  # Must follow bondX format where X is 0-9999
    iface_type: bond
    bond_mode: active-backup
    bond_primary: eth0
    slaves: eth0 eth1
    cidr: 192.168.10.0/24
    gateway: 192.168.10.1

Return Values 

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

Key	Description
changed boolean	Whether the module made changes. Returned: always Sample: `true`
diff list / elements=string	Differences between configurations in YAML format with before/after states. Returned: when changes were made (create, update, delete)
interface dictionary	The interface configuration that was applied. Returned: when state is present Sample: `{"autostart": true, "cidr": "192.168.1.0/24", "comments": "Management network", "gateway": "192.168.1.1", "iface": "vmbr0", "iface_type": "bridge", "mtu": 1500}`
msg string	A message describing what happened. Returned: always Sample: `"Interface vmbr0 created successfully"`

Authors

aleskxyz (@aleskxyz)

community.proxmox.proxmox_node_network module – Manage network interfaces on Proxmox nodes

Synopsis 

Requirements 

Parameters 

Attributes 

Notes 

See Also 

Examples 

Return Values 

Authors

Collection links