added README

This commit is contained in:
Bertrand Lanson 2023-04-19 23:37:30 +02:00
parent aea6dfcb77
commit 508a77604e

View File

@ -7,16 +7,75 @@ This role install consul-template and configure a service to automate renewal of
Requirements Requirements
------------ ------------
None. This role assume that you already have installed a vault server on the host, and is only here to assist in automating the certificate renewal process.
Role Variables Role Variables
-------------- --------------
Available variables are listed below, along with default values. A sample file for the default values is available in `default/hashicorp_vault.yml.sample` in case you need it for any `group_vars` or `host_vars` configuration. Available variables are listed below, along with default values. A sample file for the default values is available in `default/renew_vault_certificates.yml.sample` in case you need it for any `group_vars` or `host_vars` configuration.
```yaml ```yaml
hashi_vault_install: true # by default, set to true renew_vault_certificates_config_dir: /etc/consul-template.d/vault # by default, set to /etc/consul-template.d/vault
``` ```
This variable defines if the vault package is to be installed or not before configuring. If you install vault using another task, you can set this to `false`. This variable defines where the files for the role are stored (consul-template configuration + templates).
```yaml
renew_vault_certificates_vault_user: vault # by default, set to vault
```
This variable defines the user that'll be running the certificate renewal service. Defaults to `vault`, and should be present on the host prior to playing this role (ideally when installing vault).
```yaml
renew_vault_certificates_vault_group: vault # by default, set to vault
```
This variable defines the group that'll be running the certificate renewal service. Defaults to `vault`, and should be present on the host prior to playing this role (ideally when installing vault).
```yaml
renew_vault_certificates_vault_addr: https://127.0.0.1:8200 # by default, set to https://127.0.0.1:8200
```
This variable defines the address the consul-template service will query to get the new certificates. Defaults to localhost, but can be changed if vault isnt reachable on localhost (because of missing certificates SANs for example).
```yaml
renew_vault_certificates_vault_token: mysupersecretvaulttokenthatyoushouldchange # by default, set to a dummy string
```
This variable defines the vault token top use to access vault and renew the certificate. Default is a dummy string to pass unit tests.
```yaml
renew_vault_certificates_vault_token_unwrap: false # by default, set to false
```
Defines whether or not the token is wrapped and should be unwrapped (this is an enterprise-only feature of vault at the moment).
```yaml
renew_vault_certificates_vault_token_renew: true # by default, set to true
```
This variable defines whether or not to renew the vault token. It should probably be `true`, and you should have a periodic token to handle this.
```yaml
renew_vault_certificates_cert_dest: /opt/vault/tls/cert.pem # by default, set to /opt/vault/tls/cert.pem
```
This variable defines where to copy the certificates upon renewal. Default to `/opt/vault/tls/cert.pem` but should be changed depending on where you store the certificates.
```yaml
renew_vault_certificates_key_dest: /opt/vault/tls/key.pem # by default, set to /opt/vault/tls/cert.pem
```
This variable defines where to copy the private keys upon renewal. Default to `/opt/vault/tls/key.pem` but should be changed depending on where you store the keys.
```yaml
renew_vault_certificates_info: # by default, set to:
issuer_path: pki/issue/your-issuer
common_name: vault01.example.com
ttl: 90d
include_consul_service: false
```
This variable defines the path on vault to retrieve the certificates, as well as the common name and TTL to use for it. It can also include vault aliases in case you have registered vault services in a consul cluster (`active.vault.service.consul,` `standby.vault.service.consul`, `vault.service.consul`).
```yaml
renew_vault_certificates_consul_service_name: vault.service.consul # by default, set to vault.service.consul
```
This variable defines the vault service name in consul. Default is `vault.service.consul`
```yaml
renew_vault_certificates_start_service: false
```
This variable defines whether or not to start the service after creating it. By default, it is only enabled, but not started, in case you're building golden images (in which case you probably don't want a certificate generated during the build process).
Dependencies Dependencies
------------ ------------
@ -31,7 +90,7 @@ Including an example of how to use your role (for instance, with variables passe
# calling the role inside a playbook with either the default or group_vars/host_vars # calling the role inside a playbook with either the default or group_vars/host_vars
- hosts: servers - hosts: servers
roles: roles:
- ednxzu.hashicorp_vault - ednxzu.renew_vault_certificates
``` ```
License License