damex.incus.incus_network module – Ensure Incus network

Note

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

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

path

Path to the client certificate for remote authentication.

Requires url and client_key. Mutually exclusive with token.

client_key

path

Path to the client key for remote authentication.

Requires url and client_cert.

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.

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.

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

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

path

Path to the server certificate for remote verification.

Requires url.

socket_path

string

Path to the Incus Unix socket for local connections.

Default: "/var/lib/incus/unix.socket"

state

string

Desired state of the network.

Choices:

  • "present" ← (default)

  • "absent"

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

URL of the remote Incus server (e.g. https://host:8443).

If specified, connects via HTTPS instead of Unix socket.

validate_certs

boolean

Whether to validate the server TLS certificate.

Choices:

  • false

  • true ← (default)

wait

boolean

Whether to wait for async operations to complete before returning.

Set to false for fire-and-forget behaviour.

Choices:

  • false

  • true ← (default)

Examples

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

- name: Remove network
  damex.incus.incus_network:
    name: incusbr0
    state: absent

Authors

  • Roman Kuzmitskii (@damex)