cookbooks/hc-vault/README.md

   1 hc-vault Cookbook
   2 =================
   3
   4 This cookbook sets up a HashiCorp Vault service.
   5
   6 ## Contents
   7
   8 - [Requirements](#requirements)
   9     - [platforms](#platforms)
  10     - [packages](#packages)
  11 - [Attributes](#attributes)
  12 - [Usage](#usage)
  13     - [Recipes](#recipes)
  14         - [hc-vault::default](#hc-vaultdefault)
  15         - [hc-vault::docker-compose](#hc-vaultdocker-compose)
  16     - [Role Examples](#role-examples)
  17     - [SSL server keys and certificates management by `ssl_cert` cookbook](#ssl-server-keys-and-certificates-management-by-ssl_cert-cookbook)
  18 - [License and Authors](#license-and-authors)
  19
  20 ## Requirements
  21
  22 ### platforms
  23
  24 - Debian >= 9.0
  25 - Ubuntu >= 14.04
  26 - CentOS,RHEL >= 7.3
  27
  28 ### packages
  29 - none.
  30
  31 ## Attributes
  32
  33 |Key|Type|Description, example|Default|
  34 |:--|:--|:--|:--|
  35 |`['hc-vault']['with_ssl_cert_cookbook']`|Boolean|If this attribute is true, `node['hc-vault']['docker-compose']['config']` are are overridden by the following `common_name` attributes.|`false`|
  36 |`['hc-vault']['ssl_cert']['common_name']`|String|Vault server common name for TLS|`node['fqdn']`|
  37 |`['hc-vault']['config']`|Hash|Vault configurations. This Hash is expanded to a `/vault/config/config.json` in Docker container.|See `attributes/default.rb`|
  38 |`['hc-vault']['docker-compose']['vault_owner']`|Integer|Vault owner UID (read only).|`100`|
  39 |`['hc-vault']['docker-compose']['vault_group']`|Integer|Vault group GID (read only).|`1000`|
  40 |`['hc-vault']['docker-compose']['app_dir']`|String||`"#{node['docker-grid']['compose']['app_dir']}/vault"`|
  41 |`['hc-vault']['docker-compose']['config_dir']`|String||`"#{node['hc-vault']['docker-compose']['app_dir']}/config"`|
  42 |`['hc-vault']['docker-compose']['file_dir']`|String|Default backend storage.|`"#{node['hc-vault']['docker-compose']['app_dir']}/file"`|
  43 |`['hc-vault']['docker-compose']['logs_dir']`|String||`"#{node['hc-vault']['docker-compose']['app_dir']}/logs"`|
  44 |`['hc-vault']['docker-compose']['certs_dir']`|String||`"#{node['hc-vault']['docker-compose']['app_dir']}/certs"`|
  45 |`['hc-vault']['docker-compose']['config']`|Hash|`docker-compose.yml` configurations.|See `attributes/default.rb`|
  46
  47 ## Usage
  48
  49 ### Recipes
  50
  51 #### hc-vault::default
  52
  53 This recipe does nothing.
  54
  55 #### hc-vault::docker-compose
  56
  57 This recipe generates a `docker-compose.yml` for the HashiCorp Vault service.
  58
  59 ### Role Examples
  60
  61 - `roles/vault-on-docker.rb`
  62
  63 ```ruby
  64 name 'vault-on-docker'
  65 description 'Vault on Docker'
  66
  67 vault_port = '8200'
  68
  69 run_list(
  70   # see https://osdn.net/projects/metasearch/scm/git/grid-chef-repo/blobs/master/roles/docker-new-repo.rb
  71   'role[docker]',
  72   'recipe[hc-vault::docker-compose]',
  73 )
  74
  75 #env_run_lists()
  76
  77 #default_attributes()
  78
  79 override_attributes(
  80   'docker-grid' => {
  81     'engine' => {
  82       'skip_setup' => false,
  83     },
  84     'compose' => {
  85       'skip_setup' => false,
  86     },
  87   },
  88   'hc-vault' => {
  89     'config' => {
  90       #'default_lease_ttl' => '768h',
  91       #'max_lease_ttl' => '768h',
  92     },
  93     'docker-compose' => {
  94       'config' => {
  95         # Version 2 docker-compose format
  96         'version' => '2',
  97         'services' => {
  98           'vault' => {
  99             'ports' => [
 100               "#{vault_port}:8200",
 101             ],
 102             #'volumes' => [
 103               # These volumes will be set by the hc-vault::docker-compose recipe automatically.
 104               #"#{node['hc-vault']['docker-compose']['config_dir']}/config.json:/vault/config/config.json:ro",
 105               #"#{node['hc-vault']['docker-compose']['file_dir']}:/vault/file:rw",
 106               #"#{node['hc-vault']['docker-compose']['logs_dir']}:/vault/logs:rw",
 107             #],
 108             'environment' => {
 109               # use the ['hc-vault']['config'] attribute instead of this variable.
 110               #'VAULT_LOCAL_CONFIG' => '',  # expanded to /vault/config/local.json
 111             },
 112           },
 113         },
 114       },
 115     },
 116   },
 117 )
 118 ```
 119
 120 - `roles/vault-with-ssl-on-docker.rb`
 121
 122 ```ruby
 123 name 'vault-with-ssl-on-docker'
 124 description 'Vault setup with ssl_cert cookbook'
 125
 126 vault_cn = 'vault.io.example.com'
 127 vault_port = '8200'
 128
 129 run_list(
 130   'role[docker]',
 131   'recipe[hc-vault::docker-compose]',
 132 )
 133
 134 #env_run_lists()
 135
 136 #default_attributes()
 137
 138 override_attributes(
 139   'docker-grid' => {
 140     'engine' => {
 141       'skip_setup' => false,
 142     },
 143     'compose' => {
 144       'skip_setup' => false,
 145     },
 146   },
 147   'ssl_cert' => {
 148     #'common_names' => [
 149     #  vault_cn,  # hc-vault cookbook < 0.1.3
 150     #],
 151   },
 152   'hc-vault' => {
 153     'with_ssl_cert_cookbook' => true,
 154     'ssl_cert' => {
 155       'common_name' => vault_cn,
 156     },
 157     'config' => {
 158       'listener' => {
 159         'tcp' => {
 160           # These configurations will be set by the hc-vault::docker-compose recipe automatically.
 161           #'tls_disable' => false
 162           #'tls_cert_file' => '/vault/server.crt',
 163           #'tls_key_file' => '/vault/server.key',
 164         },
 165       },
 166       #'default_lease_ttl' => '768h',
 167       #'max_lease_ttl' => '768h',
 168     },
 169     'docker-compose' => {
 170       'config' => {
 171         # Version 2 docker-compose format
 172         'version' => '2',
 173         'services' => {
 174           'vault' => {
 175             'ports' => [
 176               "#{vault_port}:8200",
 177             ],
 178             #'volumes' => [
 179               # These volumes will be set by the hc-vault::docker-compose recipe automatically.
 180               #"#{node['hc-vault']['docker-compose']['config_dir']}/config.json:/vault/config/config.json:ro",
 181               #"#{node['hc-vault']['docker-compose']['file_dir']}:/vault/file:rw",
 182               #"#{node['hc-vault']['docker-compose']['logs_dir']}:/vault/logs:rw",
 183               #"#{server_cert_path(node['hc-vault']['ssl_cert']['common_name'])}:/vault/server.crt:ro",
 184               #"#{node['hc-vault']['docker-compose']['certs_dir']}/server.key:/vault/server.key:ro",
 185             #],
 186             'environment' => {
 187               # use the ['hc-vault']['config'] attribute instead of this variable.
 188               #'VAULT_LOCAL_CONFIG' => '',  # expanded to /vault/config/local.json
 189             },
 190           },
 191         },
 192       },
 193     },
 194   },
 195 )
 196 ```
 197
 198 ### SSL server keys and certificates management by `ssl_cert` cookbook
 199
 200 - create chef-vault items.
 201
 202 ```text
 203 $ ruby -rjson -e 'puts JSON.generate({"private" => File.read("vault.io.example.com.prod.key")})' \
 204 > > ~/tmp/vault.io.example.com.prod.key.json
 205
 206 $ ruby -rjson -e 'puts JSON.generate({"public" => File.read("vault.io.example.com.prod.crt")})' \
 207 > > ~/tmp/vault.io.example.com.prod.crt.json
 208
 209 $ cd $CHEF_REPO
 210
 211 $ knife vault create ssl_server_keys vault.io.example.com.prod \
 212 > --json ~/tmp/vault.io.example.com.prod.key.json
 213
 214 $ knife vault create ssl_server_certs vault.io.example.com.prod \
 215 > --json ~/tmp/vault.io.example.com.prod.crt.json
 216 ```
 217
 218 - grant reference permission to the Vault host
 219
 220 ```text
 221 $ knife vault update ssl_server_keys  vault.io.example.com.prod -S 'name:vault-host.example.com'
 222 $ knife vault update ssl_server_certs vault.io.example.com.prod -S 'name:vault-host.example.com'
 223 ```
 224
 225 - modify run_list and attributes
 226
 227 ```ruby
 228 run_list(
 229   'recipe[hc-vault::docker-compose]',
 230 )
 231
 232 override_attributes(
 233   'ssl_cert' => {
 234     #'common_names' => [
 235     #  'vault.io.example.com',  # hc-vault cookbook < 0.1.3
 236     #],
 237   },
 238   'hc-vault' => {
 239     'with_ssl_cert_cookbook' => true,
 240     'ssl_cert' => {
 241       'common_name' => 'vault.io.example.com',
 242     },
 243     # ...
 244   },
 245 )
 246 ```
 247
 248 ## License and Authors
 249
 250 - Author:: whitestar at osdn.jp
 251
 252 ```text
 253 Copyright 2017, whitestar
 254
 255 Licensed under the Apache License, Version 2.0 (the "License");
 256 you may not use this file except in compliance with the License.
 257 You may obtain a copy of the License at
 258
 259     http://www.apache.org/licenses/LICENSE-2.0
 260
 261 Unless required by applicable law or agreed to in writing, software
 262 distributed under the License is distributed on an "AS IS" BASIS,
 263 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 264 See the License for the specific language governing permissions and
 265 limitations under the License.
 266 ```