community.proxmox.proxmox_acme_certificate module – Manages ACME SSL certificates for Proxmox VE nodes

Note

This module is part of the community.proxmox collection (version 2.0.0).

You might already have this collection installed if you are using the ansible package. 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 community.proxmox. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.proxmox.proxmox_acme_certificate.

New in community.proxmox 2.0.0

Synopsis

• Order, renew or remove ACME certificates from a Certificate Authority for a specific Proxmox VE node.

• Before using this module, ensure that an ACME account is configured (using community.proxmox.proxmox_acme_account) and DNS plugins are configured if using DNS-01 challenge (using community.proxmox.proxmox_acme_plugin_dns).

• Requires root@pam authentication.

Requirements

The below requirements are needed on the host that executes this module.

• proxmoxer >= 2.3

• requests

Parameters

Parameter	Comments
account string	The ACME account name to use for ordering the certificate.
api_host string / required	Specify the target host of the Proxmox VE cluster. Uses the PROXMOX_HOST environment variable if not specified.
api_otp string	Specify the OTP. Uses the PROXMOX_OTP environment variable if not specified.
api_password string	Specify the password to authenticate with. Uses the PROXMOX_PASSWORD environment variable if not specified.
api_port integer	Specify the target port of the Proxmox VE cluster. Uses the PROXMOX_PORT environment variable if not specified.
api_timeout integer	Time limit for requests towards the Proxmox VE API. Default: 5
api_token_id string	Specify the token ID. Uses the PROXMOX_TOKEN_ID environment variable if not specified.
api_token_secret string	Specify the token secret. Uses the PROXMOX_TOKEN_SECRET environment variable if not specified.
api_user string / required	Specify the user to authenticate with. Uses the PROXMOX_USER environment variable if not specified.
ca_path path	Path to a local certificate, which will be used to verify TLS connections. Ignored if validate_certs=false.
domains list / elements=dictionary	The list of domains to include in the certificate. At least one domain is required when state=present.
alias string	An optional alias domain for DNS validation.
domain string / required	The domain name to include in the certificate.
plugin string	The DNS plugin to use for DNS-01 challenge validation. If not specified, the standalone HTTP-01 challenge will be used.
force boolean	Force certificate renewal even if the certificate is not due for renewal yet. Setting this to true will trigger a new certificate order. Choices: false ← (default) true
node_name string / required	The name of the Proxmox VE node for which to order/manage the ACME certificate.
state string	Desired state of the ACME certificate on the node. Choices: "present" ← (default) "absent"
validate_certs boolean	Validate the TLS certificates used for the connection to the Proxmox VE API. May be set through the environment variable PROXMOX_VALIDATE_CERTS. Choices: false true ← (default)

Attributes

Attribute	Support	Description
action_group	Action group: community.proxmox.proxmox	Use group/community.proxmox.proxmox in module_defaults to set defaults for this module.
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

Certificate management (Proxmox documentation)

ACME accounts and certificates in Proxmox VE

community.proxmox.proxmox_acme_certificates_info

Retrieves the list of certificates on a Proxmox VE node.

community.proxmox.proxmox_acme_account

Manages an ACME account.

community.proxmox.proxmox_acme_plugin_dns

Manage ACME DNS plugins on a Proxmox VE.

Authentication

Complete guide for the Proxmox API authentication

Examples

- name: Order ACME certificate with HTTP-01 challenge (standalone)
  community.proxmox.proxmox_acme_certificate:
    node_name: pve-node-01
    account: production
    domains:
      - domain: pve.example.com

- name: Order ACME certificate with DNS-01 challenge using Cloudflare
  community.proxmox.proxmox_acme_certificate:
    node_name: pve-node-01
    account: production
    domains:
      - domain: pve.example.com
        plugin: cloudflare

- name: Multiple domains with mixed challenge types
  community.proxmox.proxmox_acme_certificate:
    node_name: pve-node-01
    account: production
    domains:
      - domain: pve.example.com
        plugin: cloudflare
      - domain: pve2.example.com

- name: Force certificate renewal
  community.proxmox.proxmox_acme_certificate:
    node_name: pve-node-01
    account: production
    force: true
    domains:
      - domain: pve.example.com
        plugin: cloudflare

- name: Remove ACME certificate and configuration
  community.proxmox.proxmox_acme_certificate:
    node_name: pve-node-01
    state: absent

Return Values

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

Key	Description
account string	The ACME account name used for the certificate. Returned: when state=present
certificate string	The PEM-encoded certificate data. Returned: when state=present and a certificate exists
domains list / elements=dictionary	The list of domains included in the certificate. Returned: when state=present
alias string	The alias domain used for DNS validation. Returned: success
domain string	The domain name. Returned: success
plugin string	The DNS plugin used for validation. Returned: success
fingerprint string	The certificate fingerprint. Returned: when state=present and a certificate exists
issuer string	The certificate issuer. Returned: when state=present and a certificate exists
msg string	Short description of the action taken. Returned: always
node_name string	The Proxmox VE node name. Returned: on success
not_after string	The certificate expiration timestamp. Returned: when state=present and a certificate exists
not_before string	The certificate start timestamp. Returned: when state=present and a certificate exists
subject string	The certificate subject. Returned: when state=present and a certificate exists
subject_alternative_names list / elements=string	The certificate subject alternative names (SANs). Returned: when state=present and a certificate exists

Authors

• Clément Cruau (@PendaGTP)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication