Document vault in prod mode instead of dev mode (#7928)

docs/kms/README.md

@@ -42,17 +42,98 @@ MinIO requires the following Vault setup:
 - The [transit backend](https://www.vaultproject.io/api/secret/transit/index.html) configured with a named encryption key-ring
 - [AppRole](https://www.vaultproject.io/docs/auth/approle.html) based authentication with read/update policy for transit backend. In particular, read and update policy are required for the [Generate Data Key](https://www.vaultproject.io/api/secret/transit/index.html#generate-data-key) endpoint and [Decrypt Data](https://www.vaultproject.io/api/secret/transit/index.html#decrypt-data) endpoint.
 
-**2.1.1 Start Vault server in dev mode**
+**2.1.1 Start Vault server**
 
-In dev mode, Vault server runs in-memory and starts unsealed. Note that running Vault in dev mode is insecure and any data stored in the Vault is lost upon restart.
+Vault requires access to `mlock` syscall by default. Use `setcap` to give the Vault executable the ability to use the `mlock` syscall without running the process as root.  To do so run:
+```
+sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
+```
 
+Create `vault-config.json` to use file backend and start the server.
 ```
-vault server -dev
+cat > vault-config.json <<EOF
+{
+  "api_addr": "http://127.0.0.1:8200",
+  "backend": {
+    "file": {
+      "path": "vault/file"
+    }
+  },
+  "default_lease_ttl": "168h",
+  "max_lease_ttl": "720h",
+  "listener": {
+    "tcp": {
+      "address": "0.0.0.0:8200",
+      "tls_disable": true
+    }
+  },
+  "ui": true
+}
+EOF
+
+vault server -config vault-config.json
 ```
 
-**2.1.2 Set up vault transit backend and create an app role**
+> NOTE: In this example we use `"tls_disable": true` for demonstration purposes only,
+> in production setup you should generate proper TLS certificates by specifying
+> - [`tls_cert_file`](https://www.vaultproject.io/docs/configuration/listener/tcp.html#tls_cert_file)
+> - [`tls_key_file`](https://www.vaultproject.io/docs/configuration/listener/tcp.html#tls_key_file)
+
+
+**2.1.2 Initialize vault and unseal it**
 
 ```
+export VAULT_ADDR='http://127.0.0.1:8200'
+vault operator init
+Unseal Key 1: eyW/+8ZtsgT81Cb0e8OVxzJAQP5lY7Dcamnze+JnWEDT
+Unseal Key 2: 0tZn+7QQCxphpHwTm6/dC3LpP5JGIbYl6PK8Sy79R+P2
+Unseal Key 3: cmhs+AUMXUuB6Lzsvgcbp3bRT6VDGQjgCBwB2xm0ANeF
+Unseal Key 4: /fTPpec5fWpGqWHK+uhnnTNMQyAbl5alUi4iq2yNgyqj
+Unseal Key 5: UPdDVPto+H6ko+20NKmagK40MOskqOBw4y/S51WpgVy/
+
+Initial Root Token: s.zaU4Gbcu0Wh46uj2V3VuUde0
+
+Vault is 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.
+```
+
+Use any of the previously generated keys to unseal the vault
+```
+vault operator unseal eyW/+8ZtsgT81Cb0e8OVxzJAQP5lY7Dcamnze+JnWEDT
+vault operator unseal 0tZn+7QQCxphpHwTm6/dC3LpP5JGIbYl6PK8Sy79R+P2
+vault operator unseal cmhs+AUMXUuB6Lzsvgcbp3bRT6VDGQjgCBwB2xm0ANeF
+Key             Value
+---             -----
+Seal Type       shamir
+Initialized     true
+Sealed          false  ---> NOTE: vault is unsealed
+Total Shares    5
+Threshold       3
+Version         1.1.3
+Cluster Name    vault-cluster-3f084948
+Cluster ID      8c92e999-7062-4da6-4434-0fc05f34824d
+HA Enabled      false
+```
+
+Obtain root token from the `vault operator init` output above. It is displayed as `Initial Root Token: s.zaU4Gbcu0Wh46uj2V3VuUde0`
+
+**2.1.3 Set up vault transit backend and create an app role**
+```
+export VAULT_TOKEN=s.zaU4Gbcu0Wh46uj2V3VuUde0
+
+vault auth enable approle    # enable approle style auth
+vault secrets enable transit  # enable transit secrets engine
+# define an encryption key-ring for the transit path
+vault write -f  transit/keys/my-minio-key
+
 cat > vaultpolicy.hcl <<EOF
 path "transit/datakey/plaintext/my-minio-key" {
   capabilities = [ "read", "update"]
@@ -66,17 +147,24 @@ path "transit/encrypt/my-minio-key" {
 
 EOF
 
-export VAULT_ADDR='http://127.0.0.1:8200'
+# define a policy for AppRole to access transit path
-vault auth enable approle    # enable approle style auth
+vault policy write minio-policy ./vaultpolicy.hcl
-vault secrets enable transit  # enable transit secrets engine
+
-vault write -f  transit/keys/my-minio-key  #define a encryption key-ring for the transit path
+# period indicates it is renewable if token is renewed before the period is over
-vault policy write minio-policy ./vaultpolicy.hcl  #define a policy for AppRole to access transit path
+vault write auth/approle/role/my-role token_num_uses=0  secret_id_num_uses=0  period=5m
-vault write auth/approle/role/my-role token_num_uses=0  secret_id_num_uses=0  period=5m # period indicates it is renewable if token is renewed before the period is over
+
 # define an AppRole
 vault write auth/approle/role/my-role policies=minio-policy # apply policy to role
 vault read auth/approle/role/my-role/role-id  # get Approle ID
-vault write -f auth/approle/role/my-role/secret-id
+Key        Value
+---        -----
+role_id    8c03926c-6c51-7a1d-cf7d-62e48ab8d6d7
 
+vault write -f auth/approle/role/my-role/secret-id
+Key                   Value
+---                   -----
+secret_id             edd8738c-6efe-c226-74f9-ef5b66e119d7
+secret_id_accessor    57d1db64-6350-c321-4a3e-fc6aeb7d00b6
 ```
 
 The AppRole ID, AppRole Secret Id, Vault endpoint and Vault key name can now be used to start minio server with Vault as KMS.
@@ -85,10 +173,10 @@ The AppRole ID, AppRole Secret Id, Vault endpoint and Vault key name can now be
 
 You'll need the Vault endpoint, AppRole ID, AppRole SecretID and encryption key-ring name defined in step 2.1.2
 
-```sh
+```
-export MINIO_SSE_VAULT_APPROLE_ID=9b56cc08-8258-45d5-24a3-679876769126
+export MINIO_SSE_VAULT_APPROLE_ID=8c03926c-6c51-7a1d-cf7d-62e48ab8d6d7
-export MINIO_SSE_VAULT_APPROLE_SECRET=4e30c52f-13e4-a6f5-0763-d50e8cb4321f
+export MINIO_SSE_VAULT_APPROLE_SECRET=edd8738c-6efe-c226-74f9-ef5b66e119d7
-export MINIO_SSE_VAULT_ENDPOINT=https://vault-endpoint-ip:8200
+export MINIO_SSE_VAULT_ENDPOINT=http://vault-endpoint-ip:8200
 export MINIO_SSE_VAULT_KEY_NAME=my-minio-key
 export MINIO_SSE_VAULT_AUTH_TYPE=approle
 minio server ~/export
@@ -130,13 +218,13 @@ minio gateway s3
 A KMS master key consists of a master-key ID (CMK) and the 256 bit master key encoded as HEX value separated by a `:`.
 A KMS master key can be specified directly using:
 
-```sh
+```
 export MINIO_SSE_MASTER_KEY=my-minio-key:6368616e676520746869732070617373776f726420746f206120736563726574
 ```
 
 Please use your own master key. A random master key can be generated using e.g. this command on Linux/Mac/BSD* systems:
 
-```sh
+```
 head -c 32 /dev/urandom | xxd -c 32 -ps
 ```
 
@@ -154,13 +242,13 @@ plaintext - for example if sensitive data is stored on public cloud storage.
 
 To enable auto-encryption set the environment variable to `on`:
 
-```sh
+```
 export MINIO_SSE_AUTO_ENCRYPTION=on
 ```
 
 To verify auto-encryption, use the `mc` command:
 
-```sh
+```
 mc cp test.file myminio/crypt/
 test.file:              5 B / 5 B  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  100.00% 337 B/s 0s
 mc stat myminio/crypt/test.file
@@ -173,7 +261,6 @@ Encrypted :
 Note: Auto-Encryption only affects non-SSE-C requests since objects uploaded using SSE-C are already encrypted
 and S3 only allows either SSE-S3 or SSE-C but not both for the same object.
 
-
 # Explore Further
 
 - [Use `mc` with MinIO Server](https://docs.min.io/docs/minio-client-quickstart-guide)

docs/kms/vault-config.json

@@ -0,0 +1,17 @@
+{
+  "api_addr": "http://127.0.0.1:8200",
+  "backend": {
+    "file": {
+      "path": "vault/file"
+    }
+  },
+  "default_lease_ttl": "168h",
+  "max_lease_ttl": "720h",
+  "listener": {
+    "tcp": {
+      "address": "0.0.0.0:8200",
+      "tls_disable": true
+    }
+  },
+  "ui": true
+}