maxhoesel.smallstep.step_ca_renew module – Renew a valid certificate

Note

This module 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. You need further requirements to be able to use this module, see Requirements for details.

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

New in maxhoesel.smallstep 0.3.0

Synopsis

  • Renew a valid certificate

Requirements

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

  • step-cli must be installed on the remote host. You can set the executable name/path with step_cli_executable.

Parameters

Parameter

Comments

ca_config

path

The path to the certificate authority configuration file on the host.

ca_url

string

URI of the targeted Step Certificate Authority. Used if the module is run in online mode (default) and the hosts step-cli is not configured to trust the CA.

crt_file

path / required

The certificate in PEM format that we want to renew.

exec

string

The command to run after the certificate has been renewed.

expires_in

string

The amount of time remaining before certificate expiration, at which point a renewal should be attempted. The certificate renewal will not be performed if the time to expiration is greater than the expires_in value. A random jitter (duration/20) will be added to avoid multiple services hitting the renew endpoint at the same time. The duration is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

force

boolean

Force the overwrite of files without asking.

Choices:

  • false

  • true

key_file

path / required

They key file of the certificate.

offline

boolean

Don’t contact the CA. Offline mode uses the configuration, certificates, and keys created with step ca init, but can accept a different configuration file using the ca_config flag.

Choices:

  • false

  • true

output_file

path

The new certificate file path. Defaults to overwriting the crt-file positional argument.

password

string

The password to encrypt or decrypt the private key. Will be passed to step-cli through a temporary file. Mutually exclusive with password_file

password_file

path

The path to the file containing the password to encrypt or decrypt the private key. Mutually exclusive with password

pid

integer

The process id to signal after the certificate has been renewed. By default the the SIGHUP (1) signal will be used, but this can be configured with the signal parameter.

pid_file

path

The path from which to read the process id that will be signaled after the certificate has been renewed. By default the the SIGHUP (1) signal will be used, but this can be configured with the signal parameter.

root

path

The path to the PEM file used as the root certificate authority. Used if the module is run in online mode (default) and the hosts step-cli is not configured to trust the CA.

signal

integer

The signal number to send to the selected PID, so it can reload the configuration and load the new certificate. Default value is SIGHUP (1).

step_cli_executable

path

Name (or absolute path) of the step-cli executable to use

Default: "step-cli"

Notes

Note

  • Check mode is supported.

Examples

# See https://smallstep.com/docs/step-cli/reference/ca/renew for more examples

- name: Renew a certificate
  maxhoesel.smallstep.step_ca_renew:
    crt_file: internal.crt
    key_file: internal.key
    ca_url: https://ca.smallstep.com:9000
    force: yes

Authors

  • Max Hösel (@maxhoesel)