Deploying a Vault cluster

This documentation explains each steps necessary to successfully deploy a Vault cluster using the ednz_cloud.hashistack ansible collection.

Prerequisites

You should, before attempting any deployment, have read through the Quick Start Guide. These steps are necessary in order to ensure smooth operations going forward.

Variables

Basics

First, in order to deploy a Vault cluster, you need to enable it.

enable_vault: "yes"

Selecting the vault version to install is done with the vault_version variable.

vault_version: latest

The vault version can either be latest or X.Y.Z.

For production deployment, it is recommended to use the X.Y.Z syntax.

The deployment_method variable will define how to install vault on the nodes.

By default, it runs vault inside a docker container, but this can be changed to host to install vault from the package manager.

deployment_method: "docker"

General Settings

First, you can change some general settings for vault.

vault_cluster_name: vault
vault_enable_ui: true
vault_seal_configuration:
  key_shares: 3
  key_threshold: 2

Storage Settings

The storage configuration for vault can be edited as well. By default, vault will be configured to setup raft storage between all declared vault servers (in the vault_servers group).

vault_storage_configuration:
  raft:
    path: "{{ hashi_vault_data_dir }}/data"
    node_id: "{{ ansible_hostname }}"
    retry_join: |
      [
      {% for host in groups['vault_servers'] %}
        {
          'leader_api_addr': 'http://{{ hostvars[host].api_interface_address }}:8200'
        }{% if not loop.last %},{% endif %}
      {% endfor %}
      ]

While this is the recommended way to configure storage for vault, you can edit this variable to enable any storage you want. Refer to the vault documentation for compatibility and syntax details about this variable.

Example:

# MySQL storage configuration
vault_storage_configuration:
  mysql:
    address: "10.1.10.10:3006"
    username: "vault"
    password: "vault"
    database: "vault"

Listener Settings

TCP Listeners

By default, TLS is disabled for vault. This goes against the Hashicorp recommendations on the matter, but there is no simple way to force the use of TLS (yet), without adding a lot of complexity to the deployment.

The listener configuration settings can be modified in vault_listener_configuration variable.

vault_listener_configuration:
  tcp:
    address: "0.0.0.0:8200"
    tls_disable: true

By default, vault will listen on all interfaces, on port 8200. you can change it by modifying the tcp.address property, and adding you own listener preferences.

Enabling TLS for Vault

In order to enable TLS for Vault, you simply need to set the vault_enable_tls variable to true.

At the moment, hashistack-Ansible does nothing to help you generate the certificates and renew them. All it does is look inside the etc/hashistack/vault_servers/tls directory on the deployment node, and copy the files to the destination hosts in /etc/vault.d/config/tls. The listener expect 2 files by default, a cert.pem, and a key.pem file.

Please refer to the vault documentation for details bout enabling TLS on vault listeners.

In case you want to add more configuration to the vault listeners, you can add it to the vault_extra_listener_configuration variable, which by default is empty. This variable will be merge with the rest ofthe listener configuration variables, and takes precedence over all the others.

Waring At the moment, hashistack-ansible does not support setting up multiple TCP listeners. Only one can be set.

Plugins for Vault

To enable plugin support for Vault, you can set the vault_enable_plugins variable to true. This variable will add the necessary configuration options in the vault.json file to enable support. Once enabled, you can simply place your compiled plugin files into the etc/hashistack/vault_servers/plugin directory. They will be copied over to the /etc/vault.d/config/plugin directory on the target nodes.

Refer to the vault documentation for details about enabling and using plugins.

4.5 KiB Raw Blame History