damex.incus.incus_cluster_member module – Ensure Incus cluster member

Note

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

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

Synopsis

  • Ensures Incus cluster members via the Incus REST API.

  • When creating a new member, generates a join token and returns it.

  • When updating an existing member, ensures description, config, roles, groups, and failure domain.

  • When removing a member, deletes it from the cluster.

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

Cluster member configuration key-value pairs.

Default: {}

scheduler.instance

string

Controls how instances are scheduled to run on this member.

Choices:

  • "all"

  • "manual"

  • "group"

description

string

Description of the cluster member.

Default: ""

failure_domain

string

Failure domain of the cluster member.

groups

list / elements=string

List of cluster groups for the member.

name

string / required

Name of the cluster member.

roles

list / elements=string

List of roles assigned to the cluster member.

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 cluster member.

Use joined to generate a join token for a new member.

Use present to update an existing member.

Choices:

  • "present" ← (default)

  • "joined"

  • "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 cluster member join token
  damex.incus.incus_cluster_member:
    name: node2
    state: joined
  register: result

- name: Ensure cluster member config
  damex.incus.incus_cluster_member:
    name: node1
    config:
      scheduler.instance: all
    description: Primary node

- name: Ensure cluster member roles
  damex.incus.incus_cluster_member:
    name: node1
    roles:
      - database

- name: Ensure cluster member is absent
  damex.incus.incus_cluster_member:
    name: node2
    state: absent

Return Values

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

Key

Description

join_addresses

list / elements=string

Addresses of existing online cluster members.

Returned: when creating a new member

join_fingerprint

string

Fingerprint of the cluster network certificate.

Returned: when creating a new member

join_token

string

Join secret for the cluster member.

Returned: when creating a new member

Authors

  • Roman Kuzmitskii (@damex)