Merge pull request #25 from stackhpc/unseal

Improve initialisation and unsealing

Author: markgoddard

roles/vault/README.md

@@ -31,8 +31,38 @@ s (default: Omitted)
     * `vault_extra_volumes`: List of `"<host_location>:<container_mountpoint>"`
     * `vault_tls_key`: Path to TLS key to use by Vault
     * `vault_tls_cert`: Path to TLS cert to use by Vault
+    * `vault_log_keys`: Whether to log the root token and unseal keys in the Ansible output. Default `false`
+    * `vault_set_keys_fact`: Whether to set a `vault_keys` fact containing the root token and unseal keys. Default `false`
+    * `vault_write_keys_file`: Whether to write the root token and unseal keys to a file. Default `false`
+    * `vault_write_keys_file_host`: Host on which to write root token and unseal keys. Default `localhost`
+    * `vault_write_keys_file_path`: Path of file to write root token and unseal keys. Default `vault-keys.json`
 
+Root and unseal keys
+--------------------
 
+After Vault has been initialised, a root token and a set of unseal keys are emitted.
+It is very important to store these keys safely and securely.
+This role provides several mechanisms for extracting the root token and unseal keys:
+
+1. Print to Ansible log output (`vault_log_keys`)
+1. Set a `vault_keys` fact (`vault_set_keys_fact`)
+1. Write to a file (`vault_write_keys_file`)
+
+In each case, the output will contain the following:
+
+```json
+{
+  "keys": [
+    "...",
+    "..."
+  ],
+  "keys_base64": [
+    "...",
+    "..."
+  ],
+  "root_token": "..."
+}
+```
 
 Example playbook (used with OpenStack Kayobe)
 ---------------------------------------------
@@ -96,21 +126,4 @@ Example post-config playbook to enable secrets engines:
       run_once: True
 ```
 
-Example vault unseal playbook based on Kayobe's secrets.yml
-```
----
-- name: Unseal vault
-  any_errors_fatal: True
-  gather_facts: True
-  hosts: vault
-  tasks:
-    - name: Unseal vault
-      hashivault_unseal:
-        url: "https://sparrow.cf.ac.uk:8200"
-        keys: "{{ item }}"
-      run_once: True
-      with_items: "{{ secrets_vault_keys.unseal_keys_b64 }}"
-      no_log: True
-```
-
 NOTE: secrets_external_tls_cert/key are variables in Kayobe's secrets.yml

roles/vault/defaults/main.yml

@@ -68,3 +68,16 @@ consul_extra_volumes: []
 # Combined volume lists
 _vault_volumes: "{{ _vault_default_volumes + vault_extra_volumes }}"
 _consul_volumes: "{{ _consul_default_volumes + consul_extra_volumes }}"
+
+# Whether to log the root token and unseal keys in the Ansible output.
+vault_log_keys: false
+
+# Whether to set a vault_keys fact containing the root token and unseal keys.
+vault_set_keys_fact: false
+
+# Whether to write the root token and unseal keys to a file.
+vault_write_keys_file: false
+# Host on which to write root token and unseal keys.
+vault_write_keys_file_host: localhost
+# Path of file to write root token and unseal keys.
+vault_write_keys_file_path: vault-keys.json

roles/vault/tasks/vault.yml

@@ -22,18 +22,36 @@
   register: vault_init_status
   retries: 50
   delay: 1
+  run_once: true
   until: vault_init_status.status == 200
 
-- name: Initialize vault
-  hashivault_init:
-    url: "{{ vault_api_addr }}"
-  run_once: True
-  no_log: True
-  when: not vault_init_status.json.initialized
-  register: vault_keys
+- block:
+    - name: Initialize vault
+      hashivault_init:
+        url: "{{ vault_api_addr }}"
+      no_log: true
+      register: vault_keys_result
 
-- name: Print vault keys
-  debug:
-    var: vault_keys
-  when: not vault_init_status.json.initialized
+    - name: Print vault keys
+      debug:
+        var: vault_keys_result
+      when:
+        - vault_log_keys | bool
 
+    - name: Set vault_keys fact
+      set_fact:
+        vault_keys: "{{ vault_keys_result }}"
+      when:
+        - vault_set_keys_fact | bool
+
+    - name: Write vault keys to a file
+      copy:
+        content: "{{ vault_keys_result | to_nice_json }}"
+        dest: "{{ vault_write_keys_file_path }}"
+        mode: 0600
+      delegate_to: "{{ vault_write_keys_file_host }}"
+      when:
+        - vault_write_keys_file | bool
+  run_once: true
+  when:
+    - not vault_init_status.json.initialized

roles/vault_unseal/README.md

@@ -0,0 +1,33 @@
+This role unseals Hashicorp Vault.
+
+Note that in a Vault cluster, each Vault server must be unsealed individually.
+
+Requirements
+------------
+
+``ansible-modules-hashivault`` PyPI package installed
+
+Role variables
+--------------
+
+* `vault_api_addr`: Vault [API addr](https://www.vaultproject.io/docs/configuration#api_addr) - Full URL including protocol and port (e.g. "http://127.0.0.1:8200"). In a Vault cluster, this should point to an individual Vault server, rather than a load balancer.
+* `vault_unseal_keys`: List of unseal key shards.
+
+Example playbook
+----------------
+
+Example vault unseal playbook:
+```
+---
+- name: Unseal vault
+  any_errors_fatal: True
+  gather_facts: True
+  hosts: vault
+  tasks:
+    - name: Unseal vault
+      import_role:
+        name: stackhpc.vault_unseal
+      vars:
+        vault_api_addr: "https://vault.example.com"
+        vault_keys: "{{ vault_keys.keys_base64 }}"
+```

roles/vault_unseal/defaults/main.yml

@@ -0,0 +1,7 @@
+---
+# Allow vault_vip_url and vault_vip_address for backwards compatibility.
+vault_vip_address: "{{ vault_vip_url | default('') }}"
+vault_api_addr: "{{ ('https://' ~ vault_vip_address ~ ':8200') if vault_vip_address else '' }}"
+
+# List of unseal key shards.
+vault_unseal_keys: []

roles/vault_unseal/tasks/main.yml

@@ -0,0 +1,5 @@
+---
+- name: Unseal Vault
+  hashivault_unseal:
+    url: "{{ vault_api_addr }}"
+    keys: "{{ vault_unseal_keys | join(' ') }}"

tests/test_vault.yml

@@ -2,6 +2,14 @@
 - name: Prepare for vault role
   gather_facts: True
   hosts: consul
+  vars:
+    consul_bind_interface: lo
+    vault_bind_address: 127.0.0.1
+    vault_api_addr: http://127.0.0.1:8200
+    vault_config_dir: "/etc/vault"
+    vault_log_keys: true
+    vault_set_keys_fact: true
+    vault_write_keys_file: true
   tasks:
     - name: Ensure /etc/vault exists
       file:
@@ -11,8 +19,13 @@
 
     - include_role:
         name: vault
+
+    # Idempotence test
+    - include_role:
+        name: vault
+
+    - name: Unseal vault
+      import_role:
+        name: vault_unseal
       vars:
-        consul_bind_interface: lo
-        vault_bind_address: 127.0.0.1
-        vault_api_addr: http://127.0.0.1:8200
-        vault_config_dir: "/etc/vault"
+        vault_keys: "{{ vault_keys.keys_base64 }}"