maxhoesel.smallstep.step_acme_cert role – Setup an auto-renewing ACME cert using step tooling

Note

This role is part of the maxhoesel.smallstep collection (version 0.24.5).

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 maxhoesel.smallstep.

To use it in a playbook, specify: maxhoesel.smallstep.step_acme_cert.

Entry point main – Setup an auto-renewing ACME cert using step tooling

Synopsis

  • This role acquires a certificate from the CA via ACME, then sets up automatic renewal with step-cli renew‘s daemon mode

  • Requirements:

    • Root access using become: yes or equivalent

    • The host must be bootstrapped with step_bootstrap_host and the root user must be able to access the CA

  • Supported distributions:

    • Ubuntu 18.04 LTS or newer

    • Debian 10 or newer

    • Fedora 36 or newer

    • A CentOS-compatible distribution like RockyLinux/AlmaLinux 8 or newer. RockyLinux is used for testing

Parameters

Parameter

Comments

step_acme_cert_ca_provisioner

string / required

Name of the provisioner on the CA that will issue the ACME cert

step_acme_cert_certfile

dictionary

Details about the cert file on disk

group

string

Group of the file

Default: "root"

mode

string

File mode for the cert file

Default: "644"

owner

string

Owner of the file

Default: "root"

path

path

Absolute path to the cert file

Default: "/etc/ssl/step.crt"

step_acme_cert_contact

string

Contact email for the CA for important notifications

Default: "root@localhost"

step_acme_cert_duration

string

Valid duration of the certificate

Uses the provisioner default (typically 24h) if no duration is given

step_acme_cert_keyfile

dictionary

Details about the key file on disk

group

string

Group of the file

Default: "root"

mode

string

File mode for the key file

Default: "600"

owner

string

Owner of the file

Default: "root"

path

path

Absolute path to the key file

Default: "/etc/ssl/step.key"

step_acme_cert_name

string

The subject name that the certificate will be issued for

Default: "{{ ansible_fqdn }}"

step_acme_cert_renewal_reload_services

list / elements=string

Reload or restart these systemd services after a cert renewal

Example: ['nginx.service', 'mysqld.service']

Default: []

step_acme_cert_renewal_service

string

Name of the systemd service that will handle cert renewals

If you have multiple cert/key pairs on one system, you will have to set a unique service name for each pair. If you only have one, then you can leave this as is.

Default: "step-renew"

step_acme_cert_renewal_when

string

Renew the cert when its remaining valid time crosses this threshold

Uses the smallstep default (1/3 of the certs valid duration) if left undefined

step_acme_cert_san

list / elements=string

Subject Alternate Names to add to the cert

Default: []

step_acme_cert_webroot_path

string

If set, this role will use C (step-cli)s webroot mode to get a new certificate.

If empty, this role will use the standalone mode instead, causing step-cli to bind itself to port 80. Make sure that no other services are listening on this port.

Note that step-cli only needs to bind to this port when getting a new certificate. It does not need to bind if it is only renewing a valid certificate

Default: ""

step_cli_executable

path

Path or name of the step-cli executable to use for executing commands in this role

Can be an absolute path or a command (make sure the executable is in $PATH) for all users

Default: "step-cli"

step_cli_steppath

path

Optionally set a custom $STEPPATH from which to read the step config

Example: /etc/step-cli

Default: "$HOME/.step"