damex.incus.incus_server module – Ensure Incus server configuration

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

Synopsis

• Ensures Incus server configuration via the Incus REST API.

• When init is enabled, bootstraps the server using preseed.

• Supports logging targets (Loki, syslog, webhook) as a validated list inside config that gets flattened to logging.NAME.* keys.

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.
cluster dictionary	Cluster configuration for preseed initialization. Only used when init is enabled.
cluster_address string	Address of an existing cluster member to join.
cluster_certificate string	Expected cluster certificate in X509 PEM format.
cluster_token string	Token for joining an existing cluster.
enabled boolean	Whether clustering is enabled. Choices: false true
member_config list / elements=dictionary	Member-specific configuration overrides for joining.
entity string / required	Type of entity being configured.
key string / required	Configuration key to set.
name string / required	Name of the entity.
value string	Value for the configuration key.
server_address string	Address of the cluster member.
server_name string	Name of the cluster member.
config dictionary	Server configuration key-value pairs. Logging targets can be specified as a list under the logging key and will be automatically flattened to logging.NAME.* config keys. Default: {}
acme.agree_tos boolean	Agree to ACME terms of service. Choices: false true
acme.ca_url string	URL to the ACME CA directory.
acme.challenge string	ACME challenge type to use. Choices: "HTTP-01" "DNS-01"
acme.domain string	Domain for which to issue the certificate.
acme.email string	Email address for the account registration.
acme.http.port string	Port to use for HTTP-01 challenge listener.
acme.provider string	DNS provider for DNS-01 challenge.
acme.provider.environment string	Environment variables for the DNS provider.
acme.provider.resolvers string	DNS resolvers for the DNS-01 challenge.
authorization.scriptlet string	Starlark scriptlet for custom authorization logic.
backups.compression_algorithm string	Compression algorithm to use for backups.
cluster.healing_threshold integer	Threshold after which an offline cluster member is evacuated.
cluster.https_address string	Address to bind for intra-cluster communication.
cluster.images_minimal_replica integer	Minimum number of cluster members that keep a copy of an image.
cluster.join_token_expiry string	Expiry time for cluster join tokens.
cluster.max_standby integer	Maximum number of standby database members.
cluster.max_voters integer	Maximum number of voting database members.
cluster.offline_threshold integer	Seconds after which an unresponsive member is considered offline.
cluster.rebalance.batch integer	Number of instances to move per rebalance batch.
cluster.rebalance.cooldown string	Cooldown period between rebalance batches.
cluster.rebalance.interval integer	Interval in seconds between rebalance checks.
cluster.rebalance.threshold integer	Percentage threshold to trigger instance rebalancing.
core.bgp_address string	Address to bind the BGP server to.
core.bgp_asn string	BGP Autonomous System Number for the local server.
core.bgp_routerid string	BGP router ID for the local server.
core.debug_address string	Address to bind the pprof debug server to.
core.dns_address string	Address to bind the authoritative DNS server to.
core.https_address string	Address to bind the remote API to.
core.https_allowed_credentials boolean	Whether to set Access-Control-Allow-Credentials. Choices: false true
core.https_allowed_headers string	Access-Control-Allow-Headers header value.
core.https_allowed_methods string	Access-Control-Allow-Methods header value.
core.https_allowed_origin string	Access-Control-Allow-Origin header value.
core.https_trusted_proxy string	Comma-separated list of trusted proxy IP addresses.
core.metrics_address string	Address to bind the metrics server to.
core.metrics_authentication boolean	Whether to enforce authentication on the metrics endpoint. Choices: false true
core.proxy_http string	HTTP proxy to use.
core.proxy_https string	HTTPS proxy to use.
core.proxy_ignore_hosts string	Hosts that do not need the proxy.
core.remote_token_expiry string	Expiry time for remote add join tokens.
core.shutdown_timeout integer	Number of minutes to wait for running operations to complete before shutdown.
core.storage_buckets_address string	Address to bind the storage buckets API to.
core.syslog_socket boolean	Whether to enable the syslog socket listener. Choices: false true
core.trust_ca_certificates boolean	Whether to trust CA-signed client certificates. Choices: false true
images.auto_update_cached boolean	Whether to auto-update cached images. Choices: false true
images.auto_update_interval integer	Interval in hours between image auto-update checks.
images.compression_algorithm string	Compression algorithm to use for images.
images.default_architecture string	Default architecture to use in mixed-architecture clusters.
images.remote_cache_expiry integer	Number of days after which an unused cached remote image is removed.
instances.lxcfs.per_instance boolean	Whether to use a per-instance LXCFS process. Choices: false true
instances.nic.host_name string	How to set the host name for a NIC.
instances.placement.scriptlet string	Starlark scriptlet for custom instance placement.
logging list / elements=dictionary	List of logging targets. Each target is flattened to logging.NAME.* config keys.
lifecycle.projects string	Projects to send lifecycle events for.
lifecycle.types string	Lifecycle event types to send.
logging.level string	Minimum log level to send to the logger.
name string / required	Name of the logging target.
target.address string / required	Address of the logging target.
target.ca_cert string	CA certificate for the server.
target.facility string	Syslog facility for the log message.
target.instance string	Name to use as the instance field in Loki events.
target.labels string	Labels for a Loki log entry.
target.password string	Password for authentication.
target.retry integer	Number of delivery retries.
target.type string / required	Type of logging target. Choices: "loki" "syslog" "webhook"
target.username string	Username for authentication.
types string	Events to send to the logger.
network.ovn.ca_cert string	CA certificate for the OVN northbound connection.
network.ovn.client_cert string	Client certificate for the OVN northbound connection.
network.ovn.client_key string	Client key for the OVN northbound connection.
network.ovn.integration_bridge string	Name of the OVS integration bridge to use.
network.ovn.northbound_connection string	OVN northbound database connection string.
network.ovs.connection string	OVS database connection string.
oidc.audience string	Expected audience value for the OIDC provider.
oidc.claim string	OIDC claim to use as the username.
oidc.client.id string	OIDC client ID for the Incus server.
oidc.issuer string	Issuer URL for the OIDC provider.
oidc.scopes string	Comma-separated list of OIDC scopes to request.
openfga.api.token string	API token for the OpenFGA server.
openfga.api.url string	URL of the OpenFGA server.
openfga.store.id string	OpenFGA store ID.
storage.backups_volume string	Volume to use for storing backup tarballs.
storage.images_volume string	Volume to use for storing image tarballs.
storage.linstor.ca_cert string	CA certificate for the LINSTOR controller connection.
storage.linstor.client_cert string	Client certificate for the LINSTOR controller connection.
storage.linstor.client_key string	Client key for the LINSTOR controller connection.
storage.linstor.controller_connection string	LINSTOR controller connection string.
storage.linstor.satellite.name string	LINSTOR satellite node name for this server.
storage.logs_volume string	Volume to use for storing log files.
init boolean	Whether to initialize the server using preseed. Always applies the preseed when enabled. Choices: false ← (default) true
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"
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 server is initialized
  damex.incus.incus_server:
    init: true
    config:
      core.https_address: :8443

- name: Ensure server is initialized with cluster
  damex.incus.incus_server:
    init: true
    config:
      core.https_address: :8443
    cluster:
      enabled: true
      server_name: node1
      server_address: node1:8443

- name: Ensure server configuration
  damex.incus.incus_server:
    config:
      core.https_address: :8443

- name: Ensure server with Loki logging
  damex.incus.incus_server:
    config:
      core.https_address: :8443
      logging:
        - name: loki01
          target.type: loki
          target.address: https://loki.example.com:3100
          target.labels: env=prod
          types: lifecycle,logging
          logging.level: info

- name: Ensure server with syslog logging
  damex.incus.incus_server:
    config:
      logging:
        - name: syslog01
          target.type: syslog
          target.address: tcp://syslog.example.com:514
          target.facility: daemon
          types: lifecycle,logging

Authors

• Roman Kuzmitskii (@damex)

Collection links

• Issue Tracker
• Repository (Sources)