docs(lab): restructure labs

FalcoSuessgott · Nov 13, 2023 · 162a884 · 162a884
1 parent b5345b1
commit 162a884
Show file tree

Hide file tree

Showing 29 changed files with 483 additions and 111 deletions.
diff --git a/Makefile b/Makefile
@@ -45,3 +45,8 @@ new-lab:  ## creates a new lab directory
 	mkdir -p $(name)/templates
 	mkdir -p $(name)/files
 	echo "$(name)" > docs/$(name).md
+
+.PHONY: docs
+docs: ## render docs
+	firefox http://127.0.0.1:8000/home
+	mkdocs serve
diff --git a/README.md b/README.md
@@ -8,13 +8,23 @@ Please refer to the [documentation](https://falcosuessgott.github.io/hashicorp-v
 ![demo](./docs/assets/demo.gif)
 
 ## Learning Labs
-* [x] [Vault TLS Configuration](https://falcosuessgott.github.io/hashicorp-vault-playground/vault/#tls)
-* [x] [Initialization & Unsealing & Sealing](https://falcosuessgott.github.io/hashicorp-vault-playground/vault/)
+### Vault
+* [x] [Vault Raft HA Cluster ](https://falcosuessgott.github.io/hashicorp-vault-playground/vault)
+* [x] [Vault TLS Configuration](https://falcosuessgott.github.io/hashicorp-vault-playground/tls)
+* [x] [Initialization & Unsealing & Sealing](https://falcosuessgott.github.io/hashicorp-vault-playground/seal/)
+* [x] [Generate Root](https://falcosuessgott.github.io/hashicorp-vault-playground/generate-root)
+* [x] [Rekey](https://falcosuessgott.github.io/hashicorp-vault-playground/rekey)
 * [x] [HAProxy including Vaults Health Check](https://falcosuessgott.github.io/hashicorp-vault-playground/haproxy/)
-* [x] [Vault Kubernetes Auth Method](https://falcosuessgott.github.io/hashicorp-vault-playground/minikube/) configured for Minikube
+
+### Kubernetes
+* [x] [Vault Kubernetes Auth Method](https://falcosuessgott.github.io/hashicorp-vault-playground/minikube/)
 * [x] [External Secrets Manager](https://falcosuessgott.github.io/hashicorp-vault-playground/esm/)
 * [x] [Vault Secrets operator](https://falcosuessgott.github.io/hashicorp-vault-playground/vso/)
 * [x] [Vault Agent Injector](https://falcosuessgott.github.io/hashicorp-vault-playground/vai/)
 * [x] [Certmanager](https://falcosuessgott.github.io/hashicorp-vault-playground/cm/)
+
+### MySQL Dynamic DB Credentials
 * [x] [MySQL dynamic DB Credentials](https://falcosuessgott.github.io/hashicorp-vault-playground/databases/)
+
+### ToDos
 * [ ] Prometheus & Grafana + Vault Metrics
diff --git a/docs/assets/cm.png b/docs/assets/cm.png
diff --git a/docs/assets/db.png b/docs/assets/db.png
diff --git a/docs/assets/esm.png b/docs/assets/esm.png
diff --git a/docs/assets/raft.png b/docs/assets/raft.png
diff --git a/docs/assets/vai.png b/docs/assets/vai.png
diff --git a/docs/assets/vso.png b/docs/assets/vso.png
diff --git a/docs/cm.md b/docs/cm.md
@@ -1,12 +1,16 @@
 # Cert-Manager
 
+![img](assets/cm.png)
+> https://genekuo.medium.com/using-hashicorp-vault-as-certificate-manager-on-a-kubernetes-cluster-155604d39a60
+
 ## Requirements
 For this lab youre going to need `kubectl`, `helm` and `jq` installed.
 
 Also in your `terraform.tfvars`:
-```
+
+```yaml
 # terraform.tfvars
-minikube = {
+kubernetes = {
   enabled = true
   cert_manager = true
 }

diff --git a/docs/databases.md b/docs/databases.md
@@ -1,9 +1,12 @@
 # Dynamic MySQL Database Credentials
 
+![img](assets/db.png)
+> https://developer.hashicorp.com/vault/tutorials/db-credentials/database-secrets
+
 ## Requirements
 You can enable this lab by setting:
 
-```
+```yaml
 # terraform.tfvars
 databases = {
   enabled = true

diff --git a/docs/esm.md b/docs/esm.md
@@ -1,12 +1,16 @@
 # External Secrets Manager
 
+![img](assets/esm.png)
+> https://external-secrets.io/latest/provider/hashicorp-vault/
+
 ## Requirements
 For this lab youre going to need `kubectl`, `helm` and `jq` installed.
 
 Also in your `terraform.tfvars`:
-```
+
+```yaml
 # terraform.tfvars
-minikube = {
+kubernetes = {
   enabled                  = true
   external_secrets_manager = true
 }
@@ -159,6 +163,32 @@ $> kubectl get secret -n esm esm-secret -o json | jq '.data | map_values(@base64
 }
 ```
 
+You can update the secrets stored in Vault:
+
+```bash
+$> vault kv patch esm/secrets username=new-value
+== Secret Path ==
+esm/data/secrets
+
+======= Metadata =======
+Key                Value
+---                -----
+created_time       2023-11-13T12:11:09.131740262Z
+custom_metadata    <nil>
+deletion_time      n/a
+destroyed          false
+version            3
+```
+
+And see how the `esm-secret` gets the new value after `60s`:
+
+```bash
+$> kubectl get secret -n esm esm-secret -o json | jq '.data | map_values(@base64d)'
+{
+  "password": "P@ssw0rd",
+  "username": "new-value" # !
+}
+```
 
 ## Addtional Resources
 * [https://github.com/external-secrets/external-secrets](https://github.com/external-secrets/external-secrets)

diff --git a/docs/generate-root.md b/docs/generate-root.md
@@ -0,0 +1,76 @@
+# Generate Root
+Using the unseal-keys we can regenarate a root token
+
+## Revoke Root
+
+```bash
+$> vault token revoke $VAULT_TOKEN
+Success! Revoked token (if it existed)
+$> vault kv get esm/secrets
+Error making API request.
+
+URL: GET https://127.0.0.1/v1/sys/internal/ui/mounts/esm/secrets
+Code: 403. Errors:
+```
+
+## Generate Root
+
+```bash
+# init generate-root process
+$> vault operator generate-root -init
+A One-Time-Password has been generated for you and is shown in the OTP field.
+You will need this value to decode the resulting root token, so keep it safe.
+Nonce         b024b19a-723d-3ec1-1d26-cf30c680d068 # important
+Started       true
+Progress      0/3
+Complete      false
+OTP           MQHg64qQAHXlOWKJHJFkXBIIisG7          # important
+OTP Length    28
+
+# because there is no tty, we have to speciy a nonce, and the unseal key via STDIN
+$> NONCE=b024b19a-723d-3ec1-1d26-cf30c680d068; for v in $(tf output -json unseal_keys | jq -r '.[]'); do VAULT_ADDR="https://127.0.0.1:8001" echo $v | vault operator generate-root -nonce=$NONCE -; done
+Nonce       b024b19a-723d-3ec1-1d26-cf30c680d068
+Started     true
+Progress    1/3
+Complete    false
+Nonce       b024b19a-723d-3ec1-1d26-cf30c680d068
+Started     true
+Progress    2/3
+Complete    false
+Nonce            b024b19a-723d-3ec1-1d26-cf30c680d068
+Started          true
+Progress         3/3
+Complete         true
+Encoded Token    JSc7SQd7KyV5GwsLBT4oKwcQIDsvKjEgEBsKfw # important
+
+# decode token using the OTP
+$> vault operator generate-root -decode JSc7SQd7KyV5GwsLBT4oKwcQIDsvKjEgEBsKfw -otp MQHg64qQAHXlOWKJHJFkXBIIisG7
+hvs.1OZt8SSgJicaOZfPwhxiyhMH
+```
+
+## Verify
+
+
+```bash
+$> VAULT_TOKEN=hvs.1OZt8SSgJicaOZfPwhxiyhMH vault token lookup
+Key                 Value
+---                 -----
+accessor            WyUkIqrs4YOehRpv6d7Pn0Oe
+creation_time       1699878520
+creation_ttl        0s
+display_name        root
+entity_id           n/a
+expire_time         <nil>
+explicit_max_ttl    0s
+id                  hvs.1OZt8SSgJicaOZfPwhxiyhMH
+meta                <nil>
+num_uses            0
+orphan              true
+path                auth/token/root
+policies            [root] # root token
+ttl                 0s
+type                service
+```
+
+# Resources
+* [https://developer.hashicorp.com/vault/tutorials/operations/generate-root](https://developer.hashicorp.com/vault/tutorials/operations/generate-root)
diff --git a/docs/haproxy.md b/docs/haproxy.md
@@ -3,5 +3,67 @@ Vaults UI and API is accessed via HAProxy.
 HAProxy is exposed via HTTPS/443 and redirects all incomming traffic to the Vault Leader Node using [Vaults Health Check](https://developer.hashicorp.com/vault/api-docs/system/health).
 HAProxy does not terminate the TLS Connection instead of it passes through the connection to the Vault Nodes in order to avoid MITM attacks, as stated by the Vault docs.
 
+## Configuration
+See the final HAProxy Configuration:
+
+```bash
+$> docker exec -it haproxy sh -c "cat /usr/local/etc/haproxy/haproxy.cfg"
+Alias tip: dke -it haproxy sh -c "cat /usr/local/etc/haproxy/haproxy.cfg"
+global
+   log stdout format raw local0 info
+   maxconn 3000
+
+defaults
+    mode                    http
+    log                     global
+    option                  httplog
+    option                  dontlognull
+    option http-server-close
+    retries                 3
+    timeout http-request    10s
+    timeout queue           1m
+    timeout connect         10s
+    timeout client          1m
+    timeout server          1m
+    timeout http-keep-alive 10s
+    timeout check           10s
+    maxconn                 3000
+
+# enable haproxy metrics
+frontend stats
+    mode http
+    bind *:8404
+    stats enable
+    stats uri /stats
+    stats refresh 10s
+    stats admin if LOCALHOST
+
+# expose vault api via 443 & 80
+frontend vault
+      mode tcp
+      log global
+      timeout client 30000
+      bind *:80
+      bind *:443
+      description Vault over https
+      default_backend vault_https
+      option tcplog
+
+# redirect requests from vault frontend to vault server nodes via TCP
+backend vault_https
+     mode tcp
+     timeout check 5000
+     timeout server 30000
+     timeout connect 5000
+     # enable Vault Health Check
+     option httpchk GET /v1/sys/health
+     http-check expect status 200
+
+     # do not terminate TLS to avoid MITM
+     server vault-01 vault-01:8200 check check-ssl verify none
+     server vault-02 vault-02:8200 check check-ssl verify none
+     server vault-03 vault-03:8200 check check-ssl verify none
+```
+
 ## HAProxy Stats & Metrics
 You can explore HAProxy Metrics under [http://localhost:8404/stats](http://localhost:8404/stats) and see how the metrics change with every request to Vault.
diff --git a/docs/home.md b/docs/home.md
@@ -5,13 +5,23 @@ Bootstrap a local Vault HA Cluster with many useful learning labs in under a min
 ![demo](./assets/demo.gif)
 
 ## Learning Labs
-* [x] [Vault TLS Configuration](https://falcosuessgott.github.io/hashicorp-vault-playground/vault/#tls)
-* [x] [Initialization & Unsealing & Sealing](https://falcosuessgott.github.io/hashicorp-vault-playground/vault/)
+### Vault
+* [x] [Vault Raft HA Cluster ](https://falcosuessgott.github.io/hashicorp-vault-playground/vault)
+* [x] [Vault TLS Configuration](https://falcosuessgott.github.io/hashicorp-vault-playground/tls)
+* [x] [Initialization & Unsealing & Sealing](https://falcosuessgott.github.io/hashicorp-vault-playground/seal/)
+* [x] [Generate Root](https://falcosuessgott.github.io/hashicorp-vault-playground/generate-root)
+* [x] [Rekey](https://falcosuessgott.github.io/hashicorp-vault-playground/rekey)
 * [x] [HAProxy including Vaults Health Check](https://falcosuessgott.github.io/hashicorp-vault-playground/haproxy/)
-* [x] [Vault Kubernetes Auth Method](https://falcosuessgott.github.io/hashicorp-vault-playground/minikube/) configured for Minikube
+
+### Kubernetes
+* [x] [Vault Kubernetes Auth Method](https://falcosuessgott.github.io/hashicorp-vault-playground/minikube/)
 * [x] [External Secrets Manager](https://falcosuessgott.github.io/hashicorp-vault-playground/esm/)
 * [x] [Vault Secrets operator](https://falcosuessgott.github.io/hashicorp-vault-playground/vso/)
 * [x] [Vault Agent Injector](https://falcosuessgott.github.io/hashicorp-vault-playground/vai/)
 * [x] [Certmanager](https://falcosuessgott.github.io/hashicorp-vault-playground/cm/)
+
+### MySQL Dynamic DB Credentials
 * [x] [MySQL dynamic DB Credentials](https://falcosuessgott.github.io/hashicorp-vault-playground/databases/)
+
+### ToDos
 * [ ] Prometheus & Grafana + Vault Metrics
diff --git a/docs/minikube.md b/docs/minikube.md
@@ -1,9 +1,9 @@
 # Minikube
 A local Minikube cluster can be created during bootstrapping if enabled:
 
-```hcl
+```yaml
 # terraform.tfvars
-minikube = {
+kubernetes = {
   enabled = true
 }
 ```

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -48,8 +48,16 @@ vault = {
   }
 }
 
+# Dyanmic DB Credentials
+databases = {
+  enabled = true
+
+  # enable mysql db
+  mysql = true
+}
+
 # Minikube Configuration
-minikube = {
+kubernetes = {
   # wether to enable minikube deployment
   enabled = true
 
@@ -61,6 +69,9 @@ minikube = {
 
   # enable cert manager
   cert_manager = true
+
+  # enable vault agent injector
+  vault_agent_injector = true
 }
 ```
 

diff --git a/docs/rekey.md b/docs/rekey.md
@@ -0,0 +1,52 @@
+# Rekeying Vault
+
+You can generate a new unseal keys using the following snippet:
+
+```bash
+# start rekey process with 3 shares and 2 threshold
+$> vault operator rekey -init -key-shares=3 -key-threshold=2
+WARNING! If you lose the keys after they are returned, there is no recovery.
+Consider canceling this operation and re-initializing with the -pgp-keys flag
+to protect the returned unseal keys along with -backup to allow recovery of
+the encrypted keys in case of emergency. You can delete the stored keys later
+using the -delete flag.
+
+Key                      Value
+---                      -----
+Nonce                    91365630-524b-dfce-cf2b-ed777db412d8
+Started                  true
+Rekey Progress           0/3
+New Shares               3
+New Threshold            2
+Verification Required    false
+
+# because there is no tty, we have to speciy a nonce, and the unseal key via STDIN
+$> NONCE=91365630-524b-dfce-cf2b-ed777db412d8; for v in $(tf output -json unseal_keys | jq -r '.[]'); do VAULT_ADDR="https://127.0.0.1:8001" echo $v | vault operator rekey -nonce=$NONCE -; done
+Key                      Value
+---                      -----
+Nonce                    91365630-524b-dfce-cf2b-ed777db412d8
+Started                  true
+Rekey Progress           1/3
+New Shares               3
+New Threshold            2
+Verification Required    false
+Key                      Value
+---                      -----
+Nonce                    91365630-524b-dfce-cf2b-ed777db412d8
+Started                  true
+Rekey Progress           2/3
+New Shares               3
+New Threshold            2
+Verification Required    false
+
+Key 1: /jkk9//ZEqDoEqXsf3NDRu4R+gIF1tZ9WdN5QrSt0odX # unseal key 1
+Key 2: HroWSiYp5EySPA2rz94f4wg3fCE7GiMTaIIIWmrtsZeT # unseal key 2
+Key 3: LVse36NDsANEEeAW2hJFjgW7vIxP52hBf1hgoi2SY87P # unseal key 3
+
+Operation nonce: 91365630-524b-dfce-cf2b-ed777db412d8
+
+Vault unseal keys rekeyed with 3 key shares and a key threshold of 2. Please
+securely distribute the key shares printed above. When Vault is re-sealed,
+restarted, or stopped, you must supply at least 2 of these keys to unseal it
+before it can start servicing requests.
+```