Vault Installation

Below you will find a description for how to install and configure HashiCorp Vault KMS solution for Orchesto. Vault will be run in server mode and should be utilized in all production deployments.

Install vault according with the instruction for your operating system. For a UNIX like system the following can be done:

Create a vault configuration file "orchesto-vault-config.hcl" with the following content:

storage "file" {
  path    = "${HOME}/.vault/"

listener "tcp" {
 address     = ""
 tls_disable = 1

Start vault in server mode

$> export VAULT_API_ADDR=''
$> vault server -config=orchesto-vault-config.hcl

Launch a new terminal window and review the vault status using the command
vault status

Sample output:

$> export VAULT_API_ADDR=''
$> vault status

Key                Value
---                -----
Seal Type          shamir
Initialized        false
Sealed             true
Total Shares       0
Threshold          0
Unseal Progress    0/0
Unseal Nonce       n/a
Version            n/a
HA Enabled         false

Initialize vault with the command vault operator init

Sample output:

$> vault operator init
Unseal Key 1: 6PZML+3Knp0bBRIv5A/Y9JbtqPzYDGAG0ZJen0EwIoZK
Unseal Key 2: iVwKTQDivjJN9Ja1aTrwQviiu29dAUdcWY2WAv3w6lmP
Unseal Key 3: EP3WrkTuNCmQgi4vqATvY2d4t2uUBJD3K5bSiKfAiBV+
Unseal Key 4: Vv2dWUyxbvQjkShcTtgjxN+wMm9xB6vJBKCSWz429Vzs
Unseal Key 5: 4OWVjlo5pgKBej5tGz6n2IQS7pQuPDmrGIGQWX0874ee

## Initial Root Token: s.YBJSmRNSp4bzxfyolYSOFOqP

Vault initialized with 5 key shares and a key threshold of 3. Please securely
distribute the key shares printed above. When the Vault is re-sealed,
restarted, or stopped, you must supply at least 3 of these keys to unseal it
before it can start servicing requests.

Vault does not store the generated master key. Without at least 3 key to
reconstruct the master key, Vault will remain permanently sealed!

It is possible to generate new unseal keys, provided you have a quorum of
existing unseal keys shares. See "vault operator rekey" for more information.

Export the Initial Root Token

$> export VAULT_TOKEN=s.YBJSmRNSp4bzxfyolYSOFOqP

Unseal vault using 3 different unseal keys of the 5 provided above, one at time.

Sample output:

$> vault operator unseal 6PZML+3Knp0bBRIv5A/Y9JbtqPzYDGAG0ZJen0EwIoZK
Key                Value
---                -----
Seal Type          shamir
Initialized        true
Sealed             true
Total Shares       5
Threshold          3
Unseal Progress    1/3
Unseal Nonce       7b040e79-d831-44fb-f3f5-22c91719968a
Version            1.3.1
HA Enabled         false
$> vault operator unseal iVwKTQDivjJN9Ja1aTrwQviiu29dAUdcWY2WAv3w6lmP
Key                Value
---                -----
Seal Type          shamir
Initialized        true
Sealed             true
Total Shares       5
Threshold          3
Unseal Progress    2/3
Unseal Nonce       7b040e79-d831-44fb-f3f5-22c91719968a
Version            1.3.1
HA Enabled         false
$> vault operator unseal EP3WrkTuNCmQgi4vqATvY2d4t2uUBJD3K5bSiKfAiBV+
Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    5
Threshold       3
Version         1.3.1
Cluster Name    vault-cluster-de47fddd
Cluster ID      5e215e2d-6db2-91bb-fedd-c887219a0b71
HA Enabled      false

Configure vault for Orchesto

Create a vault policy for Orchesto

A policy named orchesto-vault-policy.hcl with following content:

// Backend credentials
path "orchesto/cred/*" {
  capabilities = ["read", "create", "update", "delete"]

// IAM Users
path "orchesto/iam/user/*" {
  capabilities = ["read", "create", "update", "delete", "list"]

// IAM Keys
path "orchesto/iam/key/*" {
  capabilities = ["read", "create", "update", "delete", "list"]

// Vault KMS
path "transit/datakey/plaintext/gse-master" {
  capabilities = [ "read", "update" ]

path "transit/decrypt/gse-master" {
  capabilities = [ "read", "update" ]

path "transit/keys/gse-master/rotate" {
  capabilities = [ "update" ]

path "transit/keys/*" {
  capabilities = [ "list", "read" ]

Disable the secrets engine.

$> export VAULT_API_ADDR=''
$> vault secrets disable secret
Success! Disabled the secrets engine (if it existed) at: secret/

Enable the kv secrets engine:

$> vault secrets enable -path=orchesto kv
Success! Enabled the kv secrets engine at: orchesto/

Enable approle auth method

$> vault auth enable approle
Success! Enabled approle auth method at: approle/

Activate the vault policy in Orchesto

Upload and activate the Orchesto vault policy.

!!!! Note The command below needs to be updated using the correct path to orchesto-vault-policy.hcl:

$> vault policy write orchesto-policy orchesto-vault-policy.hcl 
Success! Uploaded policy: orchesto-policy
$> vault write auth/approle/role/orchesto-role token_num_users=0 secret_id_num_users=0 period=60s
Success! Data written to: auth/approle/role/orchesto-role
$> vault write auth/approle/role/orchesto-role policies=orchesto-policy
Success! Data written to: auth/approle/role/orchesto-role

Configure vault for KMS encryption

Remember to store the ROLE_ID and SECRET_ID. These will be used to configure vault as KMS in Orchesto.

$> vault secrets enable transit
Success! Enabled the transit secrets engine at: transit/

$> vault write -f transit/keys/gse-master
Success! Data written to: transit/keys/gse-master

$> echo "export ROLE_ID=$(vault read --field=role_id auth/approle/role/orchesto-role/role-id)"
export ROLE_ID=595291ba-f2ed-5489-f868-11ad03368487

$> echo "export SECRET_ID=$(vault write -f --field=secret_id auth/approle/role/orchesto-role/secret-id)"
export SECRET_ID=21026039-032f-1345-e780-33cdd82ceaf6

Configure vault KMS in Orchesto

This can be done either via the Orctl command-line tool, as indicated below, or from the Web GUI.

$> orctl kms add KMS2 vault --vault-endpoint "" --approle-id ${ROLE_ID} --approle-secret ${SECRET_ID} --vault-keyid gse-master
$> orctl kms default KMS2
Default KMS set to KMS2

Verify the result

orctl kms list

  Default KMS: KMS2

    Type: orchesto
    Rotated Keys: tycXDVMa4_7C2aRKXhcqBYXYWcNF9ODecgIaEfL0GSc

    Type: vault
    Rotated Keys: gse-master v1