Bertrand Lanson
91c4720740
All checks were successful
build-deploy / Bump version and create changelog with commitizen (push) Successful in 9s
267 lines
9.6 KiB
Markdown
267 lines
9.6 KiB
Markdown
**Vault**
|
||
=========
|
||
|
||
This role configures [HashiCorp Vault](https://www.hashicorp.com/products/vault) on **Debian-based** distributions.
|
||
|
||
**Requirements**
|
||
------------
|
||
|
||
This role requires that the `unzip` package is installed on the target host.
|
||
If using the auto-unseal feature from this role, it also requires the `hvac` Python library to be installed on the target host.
|
||
|
||
**Role Variables**
|
||
--------------
|
||
|
||
### Service Configuration
|
||
|
||
```yaml
|
||
vault_version: latest
|
||
```
|
||
Specifies the version of Vault to install. Default is `latest`, which installs the latest stable version. It is recommended to pin the vault version to install, as setting latest will cause the role to query the github API, andyou might run into rate limiting issues. A pinned version should look like `X.Y.Z`, in accordance with the vault's [release repository](https://releases.hashicorp.com/vault/) (just strip out the leading `vault_`)
|
||
|
||
```yaml
|
||
vault_start_service: true
|
||
```
|
||
Indicates whether the Vault service should start after installation. Defaults to `true`.
|
||
|
||
```yaml
|
||
vault_config_dir: "/etc/vault.d"
|
||
```
|
||
Path to the directory where Vault's configuration files are stored.
|
||
|
||
```yaml
|
||
vault_data_dir: "/opt/vault"
|
||
```
|
||
Specifies the directory where Vault will store its data.
|
||
|
||
```yaml
|
||
vault_certs_dir: "{{ vault_config_dir }}/tls"
|
||
```
|
||
Path to the directory where Vault's TLS certificates should be stored when using internal TLS.
|
||
|
||
```yaml
|
||
vault_logs_dir: "/var/log/vault"
|
||
```
|
||
Directory path where Vault's log files will be stored if logging to file is enabled.
|
||
|
||
```yaml
|
||
vault_extra_files: false
|
||
```
|
||
If `true`, allows additional files to be copied over to the target host by the role.
|
||
|
||
```yaml
|
||
vault_extra_files_list: []
|
||
```
|
||
A list of additional files to manage with the role if `vault_extra_files` is set to `true`. This is a list of objects like:
|
||
|
||
```yaml
|
||
- src: /path/on/deploy/machine
|
||
dest: /path/to/copy/over
|
||
```
|
||
|
||
Sources can be any type of file, directory or jinja2 templates. Destination should match the type of the source. Jinja2 templates inside of a directory that would be copied over are also templated, and their `.j2` extensions will be stripped out.
|
||
|
||
Example:
|
||
|
||
```yaml
|
||
vault_extra_files_list:
|
||
- src: /local/path/to/tls/files
|
||
dest: "{{ vault_certs_dir }}"
|
||
- src: /another/single/file.j2
|
||
dest: /var/lib/file
|
||
```
|
||
|
||
```yaml
|
||
vault_env_variables: {}
|
||
```
|
||
Environment variables to be set for the Vault service, defined as key-value pairs.
|
||
|
||
### Extra Configuration
|
||
|
||
```yaml
|
||
vault_extra_configuration: {}
|
||
```
|
||
Dictionary for any additional Vault configuration options not covered by other variables. This should be used only for options not provided by existing variables.
|
||
|
||
### General
|
||
|
||
```yaml
|
||
vault_cluster_name: vault
|
||
```
|
||
Specifies the name of the Vault cluster. Default is `vault`.
|
||
|
||
```yaml
|
||
vault_bind_addr: "0.0.0.0"
|
||
```
|
||
Defines the IP address that Vault will bind to for communication. Default is `"0.0.0.0"`, allowing connections from any IP address.
|
||
|
||
```yaml
|
||
vault_cluster_addr: "{{ ansible_default_ipv4.address }}"
|
||
```
|
||
Sets the address for Vault cluster communication, typically the IP of the host running Vault.
|
||
|
||
```yaml
|
||
vault_enable_ui: true
|
||
```
|
||
Enables the Vault web UI if set to `true`. Default is `true`.
|
||
|
||
```yaml
|
||
vault_disable_mlock: false
|
||
```
|
||
If set to `true`, disables the use of `mlock` syscall, which can prevent Vault from being able to lock its memory. Useful in environments where `mlock` is restricted.
|
||
|
||
```yaml
|
||
vault_disable_cache: false
|
||
```
|
||
Disables Vault’s cache if set to `true`, forcing Vault to avoid caching data.
|
||
|
||
### Storage Configuration
|
||
|
||
```yaml
|
||
vault_storage_configuration:
|
||
file:
|
||
path: "{{ vault_data_dir }}"
|
||
```
|
||
Defines the storage backend configuration for Vault, provided as a dictionary. This configuration should resemble the `storage` stanza from the [Vault documentation](https://developer.hashicorp.com/vault/docs/configuration/storage), allowing users to specify their preferred storage backend and its associated options. Here, `file` storage is configured, with `path` set to `vault_data_dir` for file-based storage.
|
||
|
||
### Auto-Unseal Configuration
|
||
|
||
```yaml
|
||
vault_enable_auto_unseal: false
|
||
```
|
||
Enables or disables Vault's auto-unseal feature. If set to `true` and `vault_unseal_keys` is not empty, the role will attempt to unseal Vault automatically after it has started or restarted. Requires the `hvac` Python library.
|
||
|
||
```yaml
|
||
vault_unseal_url: "https://127.0.0.1:8200"
|
||
```
|
||
Specifies the URL of the Vault server used for the unseal operation.
|
||
|
||
```yaml
|
||
vault_unseal_tls_verify: true
|
||
```
|
||
Determines whether TLS verification is enabled for the unseal process. If `true`, Vault will verify the TLS certificate when connecting to `vault_unseal_url`.
|
||
|
||
```yaml
|
||
vault_unseal_keys: []
|
||
```
|
||
A list of unseal keys used to unseal the Vault server. This list should contain valid unseal keys if `vault_enable_auto_unseal` is `true`.
|
||
|
||
### Listener Configuration
|
||
|
||
```yaml
|
||
vault_enable_tls: false
|
||
```
|
||
Enables TLS for Vault listeners if set to `true`. When enabled, `vault_tls_listener_configuration` settings will take precedence over non-TLS settings.
|
||
|
||
```yaml
|
||
vault_listener_configuration:
|
||
- tcp:
|
||
address: "{{ vault_cluster_addr }}:8200"
|
||
tls_disable: true
|
||
```
|
||
Defines the default listener configuration for Vault. Here, it uses TCP with TLS disabled, binding to the `vault_cluster_addr` on port `8200`.
|
||
|
||
```yaml
|
||
vault_tls_listener_configuration:
|
||
- tcp:
|
||
tls_disable: false
|
||
tls_cert_file: "{{ vault_certs_dir }}/cert.pem"
|
||
tls_key_file: "{{ vault_certs_dir }}/key.pem"
|
||
tls_disable_client_certs: true
|
||
```
|
||
Specifies the TLS listener configuration for Vault. When `vault_enable_tls` is `true`, this configuration merges with `vault_listener_configuration`, with TLS settings overriding non-TLS values where applicable.
|
||
|
||
```yaml
|
||
vault_certificates_extra_files_dir: []
|
||
```
|
||
List of directories/files containing additional TLS certificates. These will be appended to `vault_extra_files_list` (with `vault_extra_files` set to `true`), ensuring Vault has access to required certificate files.
|
||
|
||
```yaml
|
||
vault_extra_listener_configuration: []
|
||
```
|
||
Allows adding custom listener configurations to extend the main listener settings. This configuration merges with the combined result of `vault_listener_configuration` and `vault_tls_listener_configuration`.
|
||
|
||
**Note on Merging Configuration:**
|
||
|
||
- If `vault_enable_tls` is set to `true`, `vault_listener_configuration` and `vault_tls_listener_configuration` are merged with priority given to TLS settings.
|
||
- The combined listener configurations are further extended by `vault_extra_listener_configuration`, enabling a flexible and layered configuration approach.
|
||
- `vault_certificates_extra_files_dir` directories will add entries to `vault_extra_files_list`, ensuring certificate files are available for Vault. To activate this, `vault_extra_files` should be set to `true`.
|
||
|
||
### Service Registration
|
||
|
||
```yaml
|
||
vault_enable_service_registration: false
|
||
```
|
||
Enables or disables service registration for Vault. When set to `true`, Vault will attempt to register itself with the specified service registration provider.
|
||
|
||
```yaml
|
||
vault_service_registration_configuration:
|
||
consul:
|
||
address: "127.0.0.1:8500"
|
||
scheme: "http"
|
||
token: ""
|
||
```
|
||
Defines the configuration for service registration, resembling a `service_registration` stanza from the [Vault documentation](https://developer.hashicorp.com/vault/docs/configuration/service-registration). Here, Consul is configured as the service registry with its `address`, `scheme`, and optional `token`. This allows Vault to register with Consul for service discovery if `vault_enable_service_registration` is `true`.
|
||
|
||
### Plugins Configuration
|
||
|
||
```yaml
|
||
vault_enable_plugins: false
|
||
```
|
||
Enables plugin configuration for Vault if set to `true`. This only adds the necessary entries to the Vault configuration file; actual plugin files must be copied to the plugins directory by the user or managed using the `vault_extra_files` variable.
|
||
|
||
```yaml
|
||
vault_plugins_directory: "{{ vault_config_dir }}/plugins"
|
||
```
|
||
Specifies the directory where Vault plugins are stored. Plugins should be manually placed in this directory, as enabling plugins within Vault itself is not yet managed by this role.
|
||
|
||
### Vault Logging
|
||
|
||
```yaml
|
||
vault_log_level: info
|
||
```
|
||
Sets the logging level for Vault. Accepted values are `trace`, `debug`, `info`, `warn`, and `error`. See [Vault documentation on log levels](https://developer.hashicorp.com/vault/docs/configuration#log_level) for more details.
|
||
|
||
```yaml
|
||
vault_enable_log_to_file: false
|
||
```
|
||
Enables logging to a file if set to `true`. When enabled, the settings in `vault_log_to_file_configuration` will define the log file path, rotation frequency, and retention of logs.
|
||
|
||
```yaml
|
||
vault_log_to_file_configuration:
|
||
log_file: "{{ vault_logs_dir }}/vault.log"
|
||
log_rotate_duration: 24h
|
||
log_rotate_max_files: 30
|
||
```
|
||
Specifies configuration for file-based logging:
|
||
- **`log_file`**: Defines the path to the Vault log file (e.g., `vault_logs_dir/vault.log`). See [Vault log file configuration](https://developer.hashicorp.com/vault/docs/configuration#log_file) for details.
|
||
- **`log_rotate_duration`**: Sets the duration before log rotation occurs (e.g., `24h` for daily rotation).
|
||
- **`log_rotate_max_files`**: Maximum number of rotated log files to retain.
|
||
|
||
With `vault_enable_log_to_file` set to `true`, these settings provide a default configuration for logging to a file, allowing Vault to manage log files and rotation automatically.
|
||
|
||
Dependencies
|
||
------------
|
||
|
||
None.
|
||
|
||
Example Playbook
|
||
----------------
|
||
|
||
```yaml
|
||
# calling the role inside a playbook with either the default or group_vars/host_vars
|
||
- hosts: servers
|
||
roles:
|
||
- ednz_cloud.hashistack.vault
|
||
```
|
||
|
||
License
|
||
-------
|
||
|
||
MIT / BSD
|
||
|
||
Author Information
|
||
------------------
|
||
|
||
This role was created by Bertrand Lanson in 2023.
|