This Ansible role performs a basic Vault installation, including filesystem structure and example configuration.
It can also bootstrap a minimal development or evaluation server or HA Consul-backed cluster in a Vagrant and VirtualBox based environment. See README_VAGRANT.md and the associated Vagrantfile for more details about the developer mode setup.
Brian Shumates transferred this role to @ansible-community/hashicorp-tools. This role resides on GitHub pending fixing the integration with Ansible Galaxy. To install this role create a roles/requirements.yml
file in your Ansible project folder with the following contents:
- src: https://github.com/ansible-community/ansible-vault.git
name: ansible-community.ansible-vault
scm: git
version: master
You can use git tag in the version attribute. Also you can honor its legacy name: brianshumate.ansible-vault
.
This role requires Archlinux, or FreeBSD, or a Debian or RHEL based Linux distribution. It might work with other software versions, but does work with the following specific software and versions:
- Ansible: 2.8.4
- Vault: 1.4.0
- Debian
- Debian 10 (buster)
- Debian 9 (stretch)
- Debian 8 (jessie)
- FreeBSD 11
- Ubuntu 18.04
- ArchLinux
Sorry, there is no planned support at the moment for Windows.
The role defines variables in defaults/main.yml
:
-
Version to install
- Can be overridden with
VAULT_VERSION
environment variable - Will include "+prem" if vault_enterprise_premium=True
- Will include ".hsm" if vault_enterprise_premium_hsm=True
- Can be overridden with
-
Default value: 1.4.0
- Set this to true when installing Vault Enterprise; this is not currently
possible as a "remote only" install method
- Can be overridden with
VAULT_ENTERPRISE
environment variable
- Can be overridden with
- Default value: false
- package filename
- Default value:
"vault_{{ vault_version }}_linux_amd64.zip"
- package filename
- Default value:
"vault-enterprise_{{ vault_version }}_{{ vault_os }}_{{ vault_architecture }}.zip"
- Package download URL
- Default value:
"https://releases.hashicorp.com/vault/{{ vault_version }}/vault_{{ vault_version }}_linux_amd64.zip"
- Override this var if you have your zip hosted internally
- Works for enterprise installs also
- SHA summaries URL
- Override this var if you have your sha file is hosted internally
- Default value:
"https://releases.hashicorp.com/vault/{{ vault_version }}/vault_{{ vault_version}}_SHA256SUMS"
- Set this to
true
when installing Vault via HashiCorp Linux repository - Default value: false
- SHA summaries filename (included for convenience not for modification)
- Default value:
"vault_{{ vault_version }}_SHA256SUMS"
- SHA summaries filename (included for convenience not for modification)
- Will attempt to download from
vault_checksum_file_url
if not present in files/ - Default value:
"vault-enterprise_{{ vault_version }}_SHA256SUMS"
- Binary installation path
- Default value:
/usr/local/bin
- Configuration file path
- Default value:
/etc/vault.d
- Path from where plugins can be loaded
- Default value:
/usr/local/lib/vault/plugins
- Data path
- Default value:
/var/vault
- Log path
- Default value:
/var/log/vault
- PID file location
- Default value:
/var/run/vault
- Should this role manage the vault user?
- Default value: true
- OS user name
- Default value: vault
- OS group name
- Default value: bin
- OS additional groups as in ansibles user module
- Default value: null
- Should this role manage the vault group?
- Default value: false
- Inventory group name
- Default value: vault_instances
- Cluster name label
- Default value: dc1
- Datacenter label
- Default value: dc1
- Enable vault web UI
- Default value: true
- Which storage backend should be selected, choices are: consul, etcd, file, raft, s3, and dynamodb
- Default value: consul
- User-specified source directory for TLS files for storage communication
- {{ vault_tls_src_files }}
- Path to directory containing backend tls config files
- {{ vault_tls_config_path }}
- Specifies the path to the certificate for backend communication (if supported).
- {{ vault_tls_cert_file }}
- Specifies the path to the private key for backend communication (if supported).
- {{ vault_tls_key_file }}
- CA certificate used for backend communication (if supported). This defaults to system bundle if not specified.
- {{ vault_tls_ca_file }}
- Backend consul template filename
- Default value:
backend_consul.j2
- host:port value for connecting to Consul HA backend
- Default value: 127.0.0.1:8500
- Scheme for Consul backend
- Supported values: http, https
- Default value: http
- Name of Vault's Consul K/V root path
- Default value: vault
- Name of the Vault service to register in Consul
- Default value: vault
- ACL token for accessing Consul
- Default value: none
- Address of etcd storage
- Default value: 127.0.0.1:2379
- API version
- Default value: v3
- Path for Vault storage
- Default value: /vault/
- Discovery server
- Default value: none
- Discovery server name
- Default value: none
- Use storage for High Availability mode
- Default value: false
- Use etcdsync
- Default value: true
- Username
- Default value: none
- Password
- Default value: none
- Request timeout
- Default value: "5s"
- Lock timeout
- Default value: "15s"
- Backend file template filename
- Default value:
backend_file.j2
- Backend raft integrated storage template filename
- Default value:
vault_backend_raft.j2
- Identifier for the node in the integrated storage Raft cluster
- Default value: "raft_node_1"
- Details of all the nodes are known beforehand
- Default value: "[]"
- Address of a possible leader node.
- Default value: ""
- File path to the CA cert of the possible leader node.
- Default value: ""
- File path to the client certificate for the follower node to establish client authentication with the possible leader node.
- Default value: ""
- File path to the client key for the follower node to establish client authentication with the possible leader node.
- Default value: ""
- CA cert of the possible leader node.
- Default value: ""
- Client certificate for the follower node to establish client authentication with the possible leader node.
- Default value: ""
- Client key for the follower node to establish client authentication with the possible leader node.
- Default value: ""
For additional documentation for the various options available, see the Vault documentation for the DynamoDB storage backend.
- Specifies an alternative DynamoDB endpoint.
- Default value: none
- Can be overridden with the environment variable
AWS_DYNAMODB_ENDPOINT
.
- Can be overridden with the environment variable
- Name of the DynamoDB table used to store Vault data.
- If the table does not already exist, it will be created during initialization.
- Default value:
"vault-dynamodb-backend"
- Can be overridden with the environment variable
AWS_DYNAMODB_TABLE
.
- Can be overridden with the environment variable
- Whether High Availability is enabled for this storage backend.
- Default value:
"false"
- Can be overridden with the environment variable
DYNAMODB_HA_ENABLED
.- The missing
AWS_
prefix is not a typo, this particular variable is not prefixed in both the Vault documentation and source code.
- The missing
- Can be overridden with the environment variable
- The maximum number of concurrent requests.
- Default value:
"128"
- The AWS region.
- Default value:
us-east-1
- Can be overridden with the environment variable
AWS_DEFAULT_REGION
- Can be overridden with the environment variable
- Number of reads per second to provision for the table.
- Only used during table creation, has no effect if the table already exists.
- Default value:
5
- Can be overridden with the environment variable
AWS_DYNAMODB_READ_CAPACITY
.
- Can be overridden with the environment variable
- Number of writes per second to provision for the table.
- Only used during table creation, has no effect if the table already exists.
- Default value:
5
- Can be overridden with the environment variable
AWS_DYNAMODB_WRITE_CAPACITY
.
- Can be overridden with the environment variable
- AWS access key to use for authentication.
- Default value: none
- Can be overridden with the environment variable
AWS_ACCESS_KEY_ID
- Can be overridden with the environment variable
- Leaving both this and
vault_dynamodb_secret_key
blank will cause Vault to attempt to retrieve the credentials from the AWS metadata service.
- AWS secret key used for authentication.
- Default value: none
- Can be overridden with the environment variable
AWS_SECRET_ACCESS_KEY
- Can be overridden with the environment variable
- Leaving both this and
vault_dynamodb_access_key
blank will cause Vault to attempt to retrieve the credentials from the AWS metadata service.
- AWS session token.
- Default value: none
- Can be overridden with the environment variable
AWS_SESSION_TOKEN
- Can be overridden with the environment variable
For additional information on the various options, see the Vault documentation for Consul service registration. Note that this is only available starting at Vault version 1.4.
- Enable Consul service registration
- Default value: false
- Consul service registration template filename
- Default value:
service_registration_consul.j2
- host:port value for connecting to Consul service registration
- Default value: 127.0.0.1:8500
- Specifies the check interval used to send health check information back to Consul.
- Default value: 5s
- Specifies whether Vault should register itself with Consul.
- Default value: false
- Scheme for Consul service registration
- Supported values: http, https
- Default value: http
- Name of the Vault service to register in Consul
- Default value: vault
- Specifies a comma-separated list of tags to attach to the service registration in Consul.
- Default value: ""
- Specifies a service-specific address to set on the service registration in Consul.
- Default value: nil
- ACL token for registering with Consul service registration
- Default value: none
- Path to TLS certificate and key
- Default value
{{ vault_tls_config_path }}
- CA certificate filename
- Default value:
{{ vault_tls_ca_file }}
- Server certificate
- Default value:
{{ vault_tls_cert_file }}
- Server key
- Default value:
{{ vault_tls_key_file }}
- Minimum acceptable TLS version
- Default value:
{{ vault_tls_min_version }}
- Disable verification of TLS certificates. Using this option is highly discouraged.
- Default value: false
For additional information on the various options, see the Vault documentation for Kubernetes service registration. Note that this is only available starting at Vault version 1.4.
- Enable Kubernetes service registration
- Default value: false
- Kubernetes service registration template filename
- Default value:
service_registration_kubernetes.j2
- Kubernetes namespace to register
- Default value: vault
- Kubernetes pod name to register
- Default value: vault
- Log level
- Supported values: trace, debug, info, warn, err
- Default value: info
- Requires Vault version 0.11.1 or higher
- Network interface
- Can be overridden with
VAULT_IFACE
environment variable
- Can be overridden with
- Default value: eth1
- Primary network interface address to use
- Default value:
"{{ hostvars[inventory_hostname]['ansible_'+vault_iface]['ipv4']['address'] }}"
- TCP port number to on which to listen
- Default value: 8200
- Configures the maximum possible lease duration for tokens and secrets.
- Default value: 768h (32 days)
- Configures the default lease duration for tokens and secrets.
- Default value: 768h (32 days)
- Main configuration file name (full path)
- Default value:
"{{ vault_config_path }}/vault_main.hcl"
- Vault main configuration template file
- Default value: vault_main_configuration.hcl.j2
- Address to bind to for cluster server-to-server requests
- Default value:
"{{ hostvars[inventory_hostname]['ansible_'+vault_iface]['ipv4']['address'] }}:{{ (vault_port | int) + 1}}"
- Address to advertise to other Vault servers in the cluster for request forwarding
- Default value:
"{{ vault_protocol }}://{{ vault_cluster_address }}"
- HA Client Redirect address
- Default value:
"{{ vault_protocol }}://{{ vault_redirect_address or hostvars[inventory_hostname]['ansible_'+vault_iface]['ipv4']['address'] }}:{{ vault_port }}"
- vault_redirect_address is kept for backward compatibility but is deprecated.
- Disable HA clustering
- Default value: false
- Disable Certificate Validation for API reachability check
- Default value: true
- Path to TLS certificate and key
- Default value
/etc/vault/tls
- Disable TLS
- Can be overridden with
VAULT_TLS_DISABLE
environment variable
- Can be overridden with
- Default value: 1
- Enable TLS Gossip to storage (if supported)
- Default value: 0
- User-specified source directory for TLS files
- Override with
VAULT_TLS_SRC_FILES
environment variable
- Override with
- Default value:
{{ role_path }}/files
- CA certificate filename
- Override with
VAULT_TLS_CA_CRT
environment variable
- Override with
- Default value:
ca.crt
- Server certificate
- Override with
VAULT_TLS_CERT_FILE
environment variable
- Override with
- Default value:
server.crt
- Server key
- Override with
VAULT_TLS_KEY_FILE
environment variable
- Override with
- Default value:
server.key
- Minimum acceptable TLS version
- Can be overridden with
VAULT_TLS_MIN_VERSION
environment variable
- Can be overridden with
- Default value: tls12
- Comma-separated list of supported ciphersuites
- Default value: ""
- Prefer server's cipher suite over client cipher suite
- Can be overridden with
VAULT_TLS_PREFER_SERVER_CIPHER_SUITES
environment variable
- Can be overridden with
- Default value: false
- Require clients to present a valid client certificate
- Default value: false
- Disable requesting for client certificates
- Default value: false
- Copy TLS files from src to dest
- Default value: true
- Copy from remote source if TLS files are already on host
- Default value: false
- BSD init template file
- Default value:
vault_service_bsd_init.j2
- SysV init template file
- Default value:
vault_sysvinit.j2
- Debian init template file
- Default value:
vault_service_debian_init.j2
- Systemd service template file
- Default value:
vault_service_systemd.j2
- Systemd service unit name
- Default value: "vault"
- Enable Vault telemetry
- If enabled, you must set at least one of the following parameters according to your telemetry provider:
- vault_statsite_address with a format of "FQDN:PORT"
- vault_statsd_address with a format of "FQDN:PORT"
- vault_prometheus_retention_time e.g: "30s" or "24h"
- If enabled, optionally set vault_telemetry_disable_hostname to strip the hostname prefix from telemetry data
- Default value: false
The vault
binary works on most Linux platforms and is not distribution
specific. However, some distributions require installation of specific OS
packages with different naming, so this role was built with support for
popular Linux distributions and defines these variables to deal with the
differences across distributions:
- Vault package filename
- Default value:
{{ vault_version }}_linux_amd64.zip
- Vault package download URL
- Default value:
{{ vault_zip_url }}
- List of OS packages to install
- Default value: list
- Vault package filename
- Default value:
"{{ vault_version }}_linux_amd64.zip"
- Vault package download URL
- Default value:
"{{ vault_zip_url }}"
- Vault download SHA256 summary
- Default value: SHA256 summary
- List of OS packages to install
- Default value: list
- Vault package filename
- Default value:
"{{ vault_version }}_linux_amd64.zip"
- Vault package download URL
- Default value:
"{{ vault_zip_url }}"
- Vault package SHA256 summary
- Default value: SHA256 summary
- List of OS packages to install
- Default value: list
- Vault package filename
- Default value:
"{{ vault_version }}_linux_amd64.zip"
- Vault package download URL
- Default value:
"{{ vault_zip_url }}"
- Vault package SHA256 summary
- Default value: SHA256 summary
- Enable log to
vault_log_path
- Default value: false
- Enable logrotation for systemd based systems
- Default value: false
- Determines how frequently to rotate vault logs
- Default value: 7
- Logrotate template file
- Default value:
vault_logrotate.j2
- List of OS packages to install
- Default value: list
NOTE: Read these before executing the role to avoid certain frequently encountered issues which are resolved by installing the correct dependencies.
Ansible requires GNU tar and this role performs some local use of the
unarchive module, so ensure that your system has gtar
installed.
The role depends on python-netaddr
so:
pip install netaddr
on the Ansible control host prior to executing the role.
Basic installation is possible using the included site.yml
playbook:
ansible-playbook -i hosts site.yml
You can also pass variables in using the --extra-vars
option to the
ansible-playbook
command:
ansible-playbook -i hosts site.yml --extra-vars "vault_datacenter=maui"
Specify a template file with a different backend definition
(see templates/backend_consul.j2
):
ansible-playbook -i hosts site.yml --extra-vars "vault_backend_file=backend_file.j2"
You need to make sure that the template file backend_file.j2
is in the
role directory for this to work.
See examples/README_VAGRANT.md
for details on quick Vagrant deployments
under VirtualBox for testing, etc.
example playbook for a file based vault instance.
- hosts: all
gather_facts: True
become: true
vars:
vault_backend: file
vault_cluster_disable: True
vault_log_level: debug
roles:
- vault
The role can install Vault Enterprise based instances.
Place the Vault Enterprise zip archive into {{ role_path }}/files
and set
vault_enterprise: true
or use the VAULT_ENTERPRISE="true"
environment
variable. Attempts to download the package from vault_zip_url
if zip is not found in files/.
- Set to True if using premium binary. Basically just includes "+prem" in "vault_version" var
- Default value: False
The role can configure HSM based instances. Make sure to reference the HSM support page and take notice of the behavior changes after HSM is installed.
- Set to True if using premium hsm binary. Basically just includes ".hsm" in "vault_version" var
- Default value: false
- Set which cryptography app to use.
- Default value: pkcs11
NOTE: This seal will be migrated to the
pkcs11
seal and made consistent with the other seal types with respect to breaking naming changes soon.
- Backend seal template filename
- Default value:
vault_backend_seal.j2
- Set to the absolute path of the HSM library vault will call
- Default value:
/lib64/hsmlibrary.so
- The PIN for login. May also be specified by the VAULT_HSM_PIN environment variable. If set via the environment variable, Vault will obfuscate the environment variable after reading it, and it will need to be re-set if Vault is restarted.
- Default value: 12345
- The label of the key to use. If the key does not exist and generation is enabled, this is the label that will be given to the generated key. May also be specified by the VAULT_HSM_KEY_LABEL environment variable.
- Default value: vault-hsm-key
- If no existing key with the label specified by key_label can be found at Vault initialization time, instructs Vault to generate a key. This is a boolean expressed as a string (e.g. "true"). May also be specified by the VAULT_HSM_GENERATE_KEY environment variable. Vault may not be able to successfully generate keys in all circumstances, such as if proprietary vendor extensions are required to create keys of a suitable type.
- Default value: false
- Do not change this unles you know you need to. The encryption/decryption mechanism to use, specified as a decimal or hexadecimal (prefixed by 0x) string. May also be specified by the VAULT_HSM_MECHANISM environment variable.
- Default value: ''
- Example for RSA: 0x0009
- The slot token label to use. May also be specified by the VAULT_HSM_TOKEN_LABEL environment variable. This label will only be applied when
vault_softcard_enable
is true. - Default value: ''
- Enable if you plan to use a softcard on your HSM.
- Default value: false
- The slot number to use, specified as a string (e.g. "0"). May also be specified by the VAULT_HSM_SLOT environment variable. This label will only be applied when
vault_softcard_enable
is false (default). - Default value: 0
This feature enables operators to delegate the unsealing process to Google Key Management System Cloud to ease operations in the event of partial failure and to aid in the creation of new or ephemeral clusters.
This Auto-unseal mechanism is Open Source in Vault 1.0 but would require Enterprise binaries for any earlier version.
- Set to True to enable Google Cloud KMS Auto-Unseal.
- Default value: false
- Backend seal template filename
- Default value:
vault_seal_gcpkms.j2
- GCP Project where the key reside.
- Default value: ''
- User-specified source directory for GCP Credential on Ansible control node.
- Default value: ''
- Path to GCP credential on Vault server.
- Default value:
/home/vault/vault-kms.json
- GCP Region where the key reside.
- Default value: global
- The id of the Google Cloud Platform KeyRing to which the key shall belong.
- Default value: vault
- The CryptoKey's name. A CryptoKey's name must be unique within a location and match the regular expression [a-zA-Z0-9_-]{1,63}
- Default value: vault_key
This feature enabled operators to delegate the unsealing process to AWS KMS to ease operations in the event of a partial failure and to aid in the creation of new or ephemeral clusters.
- Set to true to enable AWS KMS Auto-unseal
- Default value: false
- Backend seal template filename
- Default value:
vault_seal_awskms.j2
- Which AWS KMS region to use
- Default value: us-east-1
- The AWS Access Key to use for talking to AWS KMS
- Default value: AWS_ACCESS_KEY_ID
- The AWS Secret Key ID to use for takling to AWS KMS
- Default value: AWS_SECRET_ACCESS_KEY
- The KMS Key ID to use for AWS KMS
- Default value: VAULT_AWSKMS_SEAL_KEY_ID
- The endpoint to use for KMS
- Default value: AWS_KMS_ENDPOINT
This feature enabled operators to delegate the unsealing process to AZURE Key Vaultto ease operations in the event of a partial failure and to aid in the creation of new or ephemeral clusters.
- Set to true to enable AZURE Key Vault Auto-unseal
- Default value: false
- Backend seal template filename
- Default value:
vault_seal_azurekeyvault.j2
- Application ID related to Service Principal Name for the Application used to connect to Azure
- Default value: EXAMPLE_CLIENT_ID
- Client Secret is the secret key attached to your Application
- Default value: EXAMPLE_CLIENT_SECRET
- Tenant ID is your Directory ID in Azure
- Default value: EXAMPLE_TENANT_ID
- The name of the Vault which hosts the key
- Default value: vault
- The key hosted in the Vault in Azure Key Vault
- Default value: vault_key
BSD-2-Clause
Special thanks to the folks listed in CONTRIBUTORS.md for their contributions to this project.