community.hashi_vault.vault_pki_generate_certificate module – Generates a new set of credentials (private key and certificate) using HashiCorp Vault PKI
Note
This module is part of the community.hashi_vault collection (version 4.2.1).
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.hashi\_vault.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.hashi_vault.vault_pki_generate_certificate.
New in community.hashi_vault 2.3.0
Synopsis
Generates a new set of credentials (private key and certificate) based on a Vault PKI role.
Requirements
The below requirements are needed on the host that executes this module.
hvac(Python library) version0.9.1or higherFor detailed requirements, see the collection requirements page.
Parameters
Parameter |
Comments |
|---|---|
Specifies requested Subject Alternative Names. These can be host names or email addresses; they will be parsed into their respective fields. If any requested names do not match role policy, the entire request will be denied. Default: |
|
Authentication method to be used.
Choices:
|
|
The AWS access key to use. |
|
If specified, sets the value to use for the |
|
The AWS profile |
|
The AWS secret key that corresponds to the access key. |
|
The AWS security token if using temporary access and secret keys. |
|
The client ID (also known as application ID) of the Azure AD service principal or managed identity. Should be a UUID. If not specified, will use the system assigned managed identity. |
|
The client secret of the Azure AD service principal. |
|
The resource URL for the application registered in Azure Active Directory. Usually should not be changed from the default. Default: |
|
The Azure Active Directory Tenant ID (also known as the Directory ID) of the service principal. Should be a UUID. Required when using a service principal to authenticate to Vault, e.g. required when both azure_client_id and azure_client_secret are specified. Optional when using managed identity to authenticate to Vault. |
|
Path to certificate to use for authentication. If not specified by any other means, the |
|
For |
|
For |
|
Specifies the requested CN for the certificate. If the CN is allowed by role policy, it will be issued. |
|
Specify the mount point used by the PKI engine. Defaults to the default used by |
|
If true, the given common_name will not be included in DNS or Email Subject Alternate Names (as appropriate). Useful if the CN is not a hostname or email address, but is instead some human-readable identifier. Choices:
|
|
Specifies the format for returned data. Can be If If Choices:
|
|
Specifies requested IP Subject Alternative Names. Only valid if the role allows IP SANs (which is the default). Default: |
|
The JSON Web Token (JWT) to use for JWT authentication to Vault. |
|
Vault mount point. If not specified, the default mount point for a given auth method is used. Does not apply to token authentication. |
|
Vault namespace where secrets reside. This option requires HVAC 0.7.0+ and Vault 0.11+. Optionally, this may be achieved by prefixing the authentication mount point and/or secret path with the namespace (e.g If environment variable |
|
Specifies custom OID/UTF8-string SANs. These must match values specified on the role in The format is the same as OpenSSL: Default: |
|
Authentication password. |
|
Specifies the format for marshaling the private key. Defaults to The other option is Choices:
|
|
URL(s) to the proxies used to access the Vault service. It can be a string or a dict. If it’s a dict, provide the scheme (eg. If it’s a string, provide a single URL that will be used as the proxy for both A string that can be interpreted as a dictionary will be converted to one (see examples). You can specify a different proxy for HTTP and HTTPS resources. If not specified, environment variables from the Requests library are used. |
|
The AWS region for which to create the connection. |
|
Allows for retrying on errors, based on the Retry class in the urllib3 library. This collection defines recommended defaults for retrying connections to Vault. This option can be specified as a positive number (integer) or dictionary. If this option is not specified or the number is A number sets the total number of retries, and uses collection defaults for the other settings. A dictionary value is used directly to initialize the For detailed information on retries, see the collection User Guide. |
|
Controls whether and how to show messages on retries. This has no effect if a request is not retried. Choices:
|
|
Vault Role ID or name. Used in For For |
|
Specifies the name of the role to create the certificate against. |
|
Secret ID to be used for Vault AppRole authentication. |
|
Sets the connection timeout in seconds. If not set, then the |
|
Vault token. Token may be specified explicitly, through the listed [env] vars, and also through the If no token is supplied, explicitly or through env, then the plugin will check for a token file, as determined by token_path and token_file. The order of token loading (first found wins) is |
|
If no token is specified, will try to read the token from this file in token_path. Default: |
|
If no token is specified, will try to read the token_file from this path. |
|
For token auth, will perform a Disable if your token does not have the Choices:
|
|
Specifies requested Time To Live. Cannot be greater than the role’s If not provided, the role’s Note that the role values default to system values if not explicitly set. |
|
Specifies the requested URI Subject Alternative Names. Default: |
|
URL to the Vault service. If not specified by any other means, the value of the If |
|
Authentication user name. |
|
Controls verification and validation of SSL certificates, mostly you only want to turn off with self signed ones. Will be populated with the inverse of Will default to Choices:
|
Attributes
Attribute |
Support |
Description |
|---|---|---|
Action group: community.hashi_vault.vault |
Use |
|
Support: partial In check mode, this module will not contact Vault and will return an empty |
Can run in |
See Also
See also
- HashiCorp Vault PKI Secrets Engine API
API documentation for the HashiCorp Vault PKI secrets engine.
- HVAC library reference
HVAC library reference about the PKI engine.
Examples
- name: Login and use the resulting token
community.hashi_vault.vault_login:
url: https://localhost:8200
auth_method: ldap
username: "john.doe"
password: "{{ user_passwd }}"
register: login_data
- name: Generate a certificate with an existing token
community.hashi_vault.vault_pki_generate_certificate:
role_name: test.example.org
common_name: test.example.org
ttl: 8760h
alt_names:
- test2.example.org
- test3.example.org
url: https://vault:8201
auth_method: token
token: "{{ login_data.login.auth.client_token }}"
register: cert_data
- name: Display generated certificate
debug:
msg: "{{ cert_data.data.data.certificate }}"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Information about newly generated certificate Returned: success |
|
Payload Returned: success |
|
Linked list of CA certificates. Returned: success Sample: |
|
Generated certificate. Returned: success Sample: |
|
CA certificate. Returned: success Sample: |
|
Private key used to generate certificate. Returned: success Sample: |
|
Private key algorithm. Returned: success Sample: |
|
Certificate’s serial number. Returned: success Sample: |
|
Vault lease duration. Returned: success Sample: |
|
Vault lease attached to certificate. Returned: success Sample: |
|
True if certificate is renewable. Returned: success Sample: |
|
Warnings returned by Vault during generation. Returned: success |
Collection links
Issue Tracker Repository (Sources) Discussion, Q&A, troubleshooting Communication