damex.incus.incus_network module – Ensure Incus network

Note

This module is part of the damex.incus collection (version 1.11.7).

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 damex.incus.

To use it in a playbook, specify: damex.incus.incus_network.

Synopsis 

Create, update, and delete Incus networks via the Incus REST API.
Networks are project-scoped resources.
The network type is set on creation and cannot be changed afterwards.

Parameters 

Parameter	Comments
client_cert string	Client certificate content for remote authentication. Requires `url` and `client_key`. Mutually exclusive with `token` and `client_cert_path`.
client_cert_path string	Client certificate path for remote authentication. Requires `url` and `client_key_path`. Mutually exclusive with `token` and `client_cert`.
client_key string	Client key content for remote authentication. Requires `url` and `client_cert`. Mutually exclusive with `client_key_path`.
client_key_path string	Client key path for remote authentication. Requires `url` and `client_cert_path`. Mutually exclusive with `client_key`.
config dictionary	Network configuration key-value pairs. Boolean values are converted to lowercase strings. Default: `{}`
bgp.ipv4.nexthop string	Override the next-hop for advertised IPv4 prefixes.
bgp.ipv6.nexthop string	Override the next-hop for advertised IPv6 prefixes.
bgp_peers list / elements=dictionary	List of BGP peers for OVN downstream networks. Each peer is converted to `bgp.peers.<name>.<key>` config keys internally. Supported on bridge and physical network types used as OVN uplinks.
address string / required	Peer address (IPv4 or IPv6).
asn integer / required	Peer AS number.
holdtime integer	Hold time in seconds for the BGP session.
name string / required	Name identifier for the BGP peer.
password string	Password for the BGP session.
bridge.driver string	Bridge driver to use. Choices: `"native"` `"openvswitch"`
bridge.external_interfaces string	Comma-separated list of unconfigured NICs to bridge.
bridge.hwaddr string	MAC address for the bridge.
bridge.mtu string	Bridge MTU.
dns.domain string	Domain to advertise to DHCP clients and use for DNS resolution.
dns.mode string	DNS registration mode. Choices: `"managed"` `"dynamic"` `"none"`
dns.nameservers string	Comma-separated list of DNS nameservers.
dns.search string	Comma-separated list of DNS search domains.
dns.zone.forward string	Comma-separated list of DNS zone names for forward DNS records.
dns.zone.reverse.ipv4 string	DNS zone name for IPv4 reverse DNS records.
dns.zone.reverse.ipv6 string	DNS zone name for IPv6 reverse DNS records.
gvrp boolean	Whether to register VLAN via GARP VLAN Registration Protocol. Choices: `false` `true`
ipv4.address string	IPv4 address for the bridge (use none or auto).
ipv4.dhcp boolean	Whether to allocate addresses via DHCP. Choices: `false` `true`
ipv4.dhcp.expiry string	DHCP lease expiry time.
ipv4.dhcp.gateway string	Address of the gateway for the subnet.
ipv4.dhcp.ranges string	Comma-separated list of IPv4 DHCP ranges.
ipv4.dhcp.routes string	Additional IPv4 routes to advertise via DHCP.
ipv4.firewall boolean	Whether to generate filtering firewall rules. Choices: `false` `true`
ipv4.gateway string	Override gateway for the subnet.
ipv4.gateway.hwaddr string	MAC address of the gateway.
ipv4.nat boolean	Whether to NAT IPv4 traffic. Choices: `false` `true`
ipv4.nat.address string	Source address for outbound IPv4 NAT.
ipv4.nat.order string	Whether to add NAT rules before or after pre-existing rules. Choices: `"before"` `"after"`
ipv4.routes string	Comma-separated list of additional IPv4 CIDR subnets to route to the bridge.
ipv4.routes.anycast boolean	Whether to allow overlapping routes on multiple networks. Choices: `false` `true`
ipv4.routing boolean	Whether to route IPv4 traffic in and out of the bridge. Choices: `false` `true`
ipv6.address string	IPv6 address for the bridge (use none or auto).
ipv6.dhcp boolean	Whether to provide additional network configuration via DHCPv6. Choices: `false` `true`
ipv6.dhcp.expiry string	DHCPv6 lease expiry time.
ipv6.dhcp.ranges string	Comma-separated list of IPv6 DHCP ranges.
ipv6.dhcp.stateful boolean	Whether to enable stateful DHCPv6 address allocation. Choices: `false` `true`
ipv6.firewall boolean	Whether to generate filtering firewall rules. Choices: `false` `true`
ipv6.gateway string	Override gateway for the subnet.
ipv6.gateway.hwaddr string	MAC address of the gateway.
ipv6.nat boolean	Whether to NAT IPv6 traffic. Choices: `false` `true`
ipv6.nat.address string	Source address for outbound IPv6 NAT.
ipv6.nat.order string	Whether to add NAT rules before or after pre-existing rules. Choices: `"before"` `"after"`
ipv6.routes string	Comma-separated list of additional IPv6 CIDR subnets to route to the bridge.
ipv6.routes.anycast boolean	Whether to allow overlapping routes on multiple networks. Choices: `false` `true`
ipv6.routing boolean	Whether to route IPv6 traffic in and out of the bridge. Choices: `false` `true`
mtu string	MTU of the network interface.
parent string	Parent interface to use for the network.
raw.dnsmasq string	Additional dnsmasq configuration to append.
security.acls string	Comma-separated list of network ACLs to apply.
security.acls.default.egress.action string	Default action for egress traffic not matching any ACL rule. Choices: `"allow"` `"reject"` `"drop"`
security.acls.default.egress.logged boolean	Whether to log default egress actions. Choices: `false` `true`
security.acls.default.ingress.action string	Default action for ingress traffic not matching any ACL rule. Choices: `"allow"` `"reject"` `"drop"`
security.acls.default.ingress.logged boolean	Whether to log default ingress actions. Choices: `false` `true`
tunnels list / elements=dictionary	List of tunnels for bridge networks. Each tunnel is converted to `tunnel.<name>.<key>` config keys internally.
group string	Multicast address for VXLAN tunnels.
id integer	Tunnel ID for VXLAN tunnels.
interface string	Host interface to use for the tunnel.
local string	Local address for the tunnel.
name string / required	Name identifier for the tunnel.
port integer	Destination UDP port for VXLAN tunnels.
protocol string	Tunneling protocol. Choices: `"vxlan"` `"gre"`
remote string	Remote address for the tunnel.
ttl integer	TTL for multicast routing topologies.
vlan integer	VLAN ID to attach to.
vlan.tagged string	Comma-separated list of VLAN IDs to join for tagged traffic.
description string	Network description. Default: `""`
name string / required	Name of the network.
project string	Incus project to query. Default: `"default"`
server_cert string	Server certificate content for remote verification. Requires `url`. Mutually exclusive with `server_cert_path`.
server_cert_path string	Server certificate path for remote verification. Requires `url`. Mutually exclusive with `server_cert`.
socket_path string	Incus Unix socket path for local connections. Default: `"/var/lib/incus/unix.socket"`
state string	Desired state of the network. Choices: `"present"` ← (default) `"absent"`
target string	Cluster member to target for pending network creation.
token string	Token for remote authentication. Requires `url`. Mutually exclusive with `client_cert`.
type string	Network type. Required when creating a new network. Ignored on update — type cannot be changed after creation. Choices: `"bridge"` `"macvlan"` `"ovn"` `"physical"` `"sriov"`
url string	Remote Incus server URL (e.g. https://host:8443). If specified, connects via HTTPS instead of Unix socket.
validate_certs boolean	Server TLS certificate validation. Choices: `false` `true` ← (default)
wait boolean	Async operation completion wait. Set to `false` for fire-and-forget behaviour. Choices: `false` `true` ← (default)

Examples 

- name: Ensure bridge network
  damex.incus.incus_network:
    name: incusbr0
    type: bridge
    config:
      ipv4.address: 10.0.0.1/24
      ipv4.nat: true

- name: Ensure network on cluster member
  damex.incus.incus_network:
    name: incusbr0
    type: bridge
    target: node1

- name: Ensure network is finalized
  damex.incus.incus_network:
    name: incusbr0
    type: bridge
    config:
      ipv4.address: 10.0.0.1/24
      ipv4.nat: true

- name: Ensure bridge network with BGP peers
  damex.incus.incus_network:
    name: bgpbr0
    type: bridge
    config:
      ipv4.address: 10.12.102.1/24
      ipv4.nat: false
      bgp_peers:
        - name: router
          address: 10.12.101.1
          asn: 64601
        - name: backup
          address: 10.12.101.2
          asn: 64602
          holdtime: 300

- name: Ensure bridge network with VXLAN tunnel
  damex.incus.incus_network:
    name: multibr0
    type: bridge
    config:
      ipv4.address: 10.0.0.1/24
      tunnels:
        - name: site2
          protocol: vxlan
          local: 192.168.1.1
          remote: 192.168.1.2
          id: 100

- name: Ensure network is absent
  damex.incus.incus_network:
    name: incusbr0
    state: absent

Return Values 

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

Key	Description
changed boolean	Resource state change indicator. Returned: always
changed_keys list / elements=string	Configuration keys that changed. Returned: always
diff dictionary	Before and after state for diff mode. Returned: changed
after dictionary	State after the change. Returned: success
before dictionary	State before the change. Returned: success

Authors

Roman Kuzmitskii (@damex)

damex.incus.incus_network module – Ensure Incus network

Synopsis

Parameters

Examples

Return Values

Authors

Collection links

Synopsis 

Parameters 

Examples 

Return Values 