damex.incus.incus_network_forward module – Ensure Incus network forward

Note

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

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_forward.

Synopsis

  • Create, update, and delete Incus network forwards via the Incus REST API.

  • Network forwards allow external IP addresses to be forwarded to internal addresses inside bridge and OVN networks.

  • Forwards are identified by their listen address within a given network.

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

Path to the client certificate 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

Path to the client key for remote authentication.

Requires url and client_cert_path. Mutually exclusive with client_key.

config

dictionary

Network forward configuration key-value pairs.

Boolean values are converted to lowercase strings.

Default: {}

target_address

string

Default target address for traffic not matching any port rule.

description

string

Description of the network forward.

Default: ""

name

string / required

Listen address of the network forward.

network

string / required

Name of the network containing the forward.

ports

list / elements=dictionary

List of port forwarding rules.

description

string

Description of the port rule.

listen_port

string / required

Port or port range to listen on.

protocol

string / required

Network protocol to forward.

Choices:

  • "tcp"

  • "udp"

snat

boolean

Whether to rewrite traffic source address.

Only supported on bridge networks with nftables.

Choices:

  • false

  • true

target_address

string / required

Target address to forward traffic to.

target_port

string

Target port or port range.

Defaults to listen port if not specified.

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

Path to the server certificate for remote verification.

Requires url. Mutually exclusive with server_cert.

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 forward.

Choices:

  • "present" ← (default)

  • "absent"

token

string

Token for remote authentication.

Requires url. Mutually exclusive with client_cert.

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: Ensure network forward with default target
  damex.incus.incus_network_forward:
    network: incusbr0
    name: 192.168.1.100
    config:
      target_address: 10.0.0.5

- name: Ensure network forward with port rules
  damex.incus.incus_network_forward:
    network: incusbr0
    name: 192.168.1.100
    description: Web server forward
    ports:
      - protocol: tcp
        listen_port: 80,443
        target_address: 10.0.0.5
      - protocol: udp
        listen_port: "53"
        target_address: 10.0.0.10
        description: DNS forward

- name: Ensure network forward is absent
  damex.incus.incus_network_forward:
    network: incusbr0
    name: 192.168.1.100
    state: absent

Authors

  • Roman Kuzmitskii (@damex)