docs(cicd): add CI/CD section

FalcoSuessgott · Nov 19, 2023 · cbe553b · cbe553b
1 parent 8675fd6
commit cbe553b
Show file tree

Hide file tree

Showing 25 changed files with 163 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -14,27 +14,29 @@
 </div>
 
 ## Features
+* **CI/CD Integrations for [Gitlab, GitHub, Azure Devops](https://falcosuessgott.github.io/vkv/11_cicd/gitlab/)**
+* support all Vault Auth Env Vars and `VKV_LOGIN_COMMAND` for avoiding having to hardcode the `VAULT_TOKEN` ([example](https://falcosuessgott.github.io/vkv/03_authentication/#special-env-var-vkv_login_command))
 * recursively print secrets of any KVv2 Engine in `json`, `yaml`, `markdown` and [other formats](https://falcosuessgott.github.io/vkv/05_export/formats/)
 * engine export shows the secret version as well as its [custom metadata](https://developer.hashicorp.com/vault/docs/commands/kv/metadata)
 * customize the output (show only-keys, only-paths, mask/unmask secrets) via [flags or environment](https://falcosuessgott.github.io/vkv/05_export/)
 * print the CRUD-capabilities of the authenticated token for each KV-path (format: `policy`)
-* print secrets in `export <key>=<value>` format for variable exporting (format: `export`)
-* [import](https://falcosuessgott.github.io/vkv/06_import/) secrets back to Vault from `vkv`'s `json` or `yaml` format 
-* save and restore KVv2 snapshots (including namespaces) and running on [kubernetes](https://falcosuessgott.github.io/vkv/09_advanced_examples/kubernetes/)
-* list all engines or namespaces for scripting purposes
-* handy [snippets](https://falcosuessgott.github.io/vkv/09_advanced_examples/) for managing KVv2 engines using `fzf`, `sops` & `diff`, [gitlab-CI Examples](https://falcosuessgott.github.io/vkv/10_advanced_examples/gitlab/)
+* print secrets in `export <key>=<value>` format for env var exporting (format: `export`)
+* [import](https://falcosuessgott.github.io/vkv/06_import/) secrets back to Vault from `vkv`'s `json` or `yaml` format output
+* save and restore KVv2 snapshots (including namespaces) ([kubernetes](https://falcosuessgott.github.io/vkv/10_advanced_examples/kubernetes/) example)
+* list all KVv2-engines or namespaces for scripting purposes ([fzf](https://falcosuessgott.github.io/vkv/10_advanced_examples/fzf/) example)
+* more handy [snippets](https://falcosuessgott.github.io/vkv/09_advanced_examples/) using `fzf`, `sops` & `diff`,
 
 Checkout the [Quickstart](https://falcosuessgott.github.io/vkv/01_quickstart) Guide to learn more about `vkv`
 
 ## Quickstart
 
 ```bash
 # Installation
-curl -OL https://github.com/FalcoSuessgott/vkv/releases/download/v0.4.0/vkv_$(uname)_$(uname -m).tar.gz
+curl -OL https://github.com/FalcoSuessgott/vkv/releases/download/v0.5.0/vkv_$(uname)_$(uname -m).tar.gz
 tar xzf vkv_$(uname)_$(uname -m).tar.gz
 chmod u+x vkv
 ./vkv version
-vkv 0.4.0
+vkv 0.5.0
 
 # set required env vars
 export VAULT_ADDR=https://vault-server:8200

diff --git a/cmd/server/server.go b/cmd/server/server.go
@@ -76,7 +76,7 @@ func NewServerCmd(writer io.Writer, vaultClient *vault.Vault) *cobra.Command {
 	cmd.Flags().SortFlags = false
 
 	// Input
-	cmd.Flags().StringVarP(&o.Port, "port", "P", o.Port, "HTTP Server Port (env: VKV_SERVER_PATH)")
+	cmd.Flags().StringVarP(&o.Port, "port", "P", o.Port, "HTTP Server Port (env: VKV_SERVER_PORT)")
 	cmd.Flags().StringVarP(&o.Path, "path", "p", o.Path, "KVv2 Engine path (env: VKV_SERVER_PATH)")
 	cmd.Flags().StringVarP(&o.EnginePath, "engine-path", "e", o.EnginePath, "engine path in case your KV-engine contains special characters such as \"/\", the path value will then be appended if specified (\"<engine-path>/<path>\") (env: VKV_SERVER_ENGINE_PATH)")
 	cmd.Flags().BoolVar(&o.SkipErrors, "skip-errors", o.SkipErrors, "dont exit on errors (permission denied, deleted secrets) (env: VKV_SERVER_SKIP_ERRORS)")

diff --git a/docs/10_advanced_examples/diff.md → docs/advanced_examples/diff.md b/docs/10_advanced_examples/diff.md → docs/advanced_examples/diff.md
diff --git a/docs/10_advanced_examples/direnv.md → docs/advanced_examples/direnv.md b/docs/10_advanced_examples/direnv.md → docs/advanced_examples/direnv.md
diff --git a/docs/10_advanced_examples/fzf.md → docs/advanced_examples/fzf.md b/docs/10_advanced_examples/fzf.md → docs/advanced_examples/fzf.md
diff --git a/docs/10_advanced_examples/kubernetes.md → docs/advanced_examples/kubernetes.md b/docs/10_advanced_examples/kubernetes.md → docs/advanced_examples/kubernetes.md
diff --git a/docs/10_advanced_examples/sops.md → docs/advanced_examples/sops.md b/docs/10_advanced_examples/sops.md → docs/advanced_examples/sops.md
diff --git a/docs/03_authentication/index.md → docs/authentication/index.md b/docs/03_authentication/index.md → docs/authentication/index.md
diff --git a/docs/cicd/azure.md b/docs/cicd/azure.md
@@ -0,0 +1,31 @@
+# Azure Devops
+
+Azure Devops Example for reading Secrets from Vault using `vkv`:
+
+```yaml
+resources:
+  containers:
+  - container: ghcr.io/falcosuessgott/vkv:latest
+    image: vkv
+    env:
+      VAULT_ADDR: https://vault.server.de
+
+      VKV_MODE: server
+      VKV_SERVER_PATH: secrets
+      VKV_LOGIN_COMMAND: |
+        vault login -token-only -method=userpass username=admin password="${VAULT_PASSWORD}"
+    ports:
+      - 8080:8080
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+services:
+  vkv: vkv
+
+steps:
+  - script: |
+      eval $(curl http://vkv:8080)
+      echo $secret
+    displayName: Read secrets as env vars using vkv
+```
diff --git a/docs/cicd/github.md b/docs/cicd/github.md
@@ -0,0 +1,28 @@
+# Github Action
+
+Github Action Example for reading Secrets from Vault using `vkv`:
+
+```yaml
+name: Vault Secrets using vkv
+on: push
+
+jobs:
+  job_name:
+    runs-on: ubuntu-latest
+    services:
+      vkv:
+        image: ghcr.io/falcosuessgott/vkv:latest
+        env:
+          VAULT_ADDR: https://vault.server.de
+          VKV_MODE: server
+          VKV_SERVER_PATH: secrets
+          VKV_LOGIN_COMMAND: |
+            vault login -token-only -method=userpass username=admin password="${VAULT_PASSWORD}"
+        ports:
+          - 8080:8080
+    steps:
+      - name: read secrets from vkv server
+        run: eval $(curl http://vkv:8080/export)
+      - name: output secrets now available as env vars
+        run: echo $secret
+```
diff --git a/docs/10_advanced_examples/gitlab.md → docs/cicd/gitlab.md b/docs/10_advanced_examples/gitlab.md → docs/cicd/gitlab.md
@@ -1,6 +1,6 @@
 # Gitlab CI
 
-Gitlab-CI Example for reading Secrets from Vault using vkv 
+Gitlab-CI Example for reading Secrets from Vault using `vkv`:
 
 ```yaml
 variables:
@@ -20,7 +20,7 @@ variables:
 default:
   # spin up a vkv service container in server mode, configure using variables/env vars
   services:
-    - name: ghcr.io/falcosuessgott/vkv:v0.5.0
+    - name: ghcr.io/falcosuessgott/vkv:latest
       command: ["server"]
       alias: vkv
   # global before_scripts block

diff --git a/docs/04_configuration/index.md → docs/configuration/index.md b/docs/04_configuration/index.md → docs/configuration/index.md
diff --git a/docs/11_development/index.md → docs/development/index.md b/docs/11_development/index.md → docs/development/index.md
diff --git a/docs/09_engines/index.md → docs/engines/index.md b/docs/09_engines/index.md → docs/engines/index.md
diff --git a/docs/05_export/formats.md → docs/export/formats.md b/docs/05_export/formats.md → docs/export/formats.md
diff --git a/docs/05_export/index.md → docs/export/index.md b/docs/05_export/index.md → docs/export/index.md
diff --git a/docs/06_import/index.md → docs/import/index.md b/docs/06_import/index.md → docs/import/index.md
diff --git a/docs/index.md b/docs/index.md
@@ -13,16 +13,17 @@
 `vkv` is a little CLI tool written in Go, which enables you to list, compare, import, document, backup & encrypt secrets from a [HashiCorp Vault KV-v2 engine](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2):
 
 
-### Features
+## Features
+* **CI/CD Integrations for [Gitlab, GitHub, Azure Devops](https://falcosuessgott.github.io/vkv/11_cicd/gitlab/)**
+* support all Vault Auth Env Vars and `VKV_LOGIN_COMMAND` for avoiding having to hardcode the `VAULT_TOKEN` ([example](https://falcosuessgott.github.io/vkv/03_authentication/#special-env-var-vkv_login_command))
 * recursively print secrets of any KVv2 Engine in `json`, `yaml`, `markdown` and [other formats](https://falcosuessgott.github.io/vkv/05_export/formats/)
 * engine export shows the secret version as well as its [custom metadata](https://developer.hashicorp.com/vault/docs/commands/kv/metadata)
 * customize the output (show only-keys, only-paths, mask/unmask secrets) via [flags or environment](https://falcosuessgott.github.io/vkv/05_export/)
 * print the CRUD-capabilities of the authenticated token for each KV-path (format: `policy`)
-* print secrets in `export <key>=<value>` format for variable exporting (format: `export`)
-* [import](https://falcosuessgott.github.io/vkv/06_import/) secrets back to Vault from `vkv`'s `json` or `yaml` format 
-* save and restore KVv2 snapshots (including namespaces) and running on [kubernetes](https://falcosuessgott.github.io/vkv/09_advanced_examples/kubernetes/)
-* list all engines or namespaces for scripting purposes
-* handy [snippets](https://falcosuessgott.github.io/vkv/09_advanced_examples/) for managing KVv2 engines using `fzf`, `sops` & `diff`
-* [Gitlab-CI Example](https://falcosuessgott.github.io/vkv/10_advanced_examples/gitlab/)
+* print secrets in `export <key>=<value>` format for env var exporting (format: `export`)
+* [import](https://falcosuessgott.github.io/vkv/06_import/) secrets back to Vault from `vkv`'s `json` or `yaml` format output
+* save and restore KVv2 snapshots (including namespaces) ([kubernetes](https://falcosuessgott.github.io/vkv/10_advanced_examples/kubernetes/) example)
+* list all KVv2-engines or namespaces for scripting purposes ([fzf](https://falcosuessgott.github.io/vkv/10_advanced_examples/fzf/) example)
+* more handy [snippets](https://falcosuessgott.github.io/vkv/09_advanced_examples/) using `fzf`, `sops` & `diff`,
 
 Checkout the [Quickstart](https://falcosuessgott.github.io/vkv/01_quickstart) Guide to learn more about `vkv`
diff --git a/docs/02_installation/index.md → docs/installation/index.md b/docs/02_installation/index.md → docs/installation/index.md
diff --git a/docs/08_namespaces/index.md → docs/namespaces/index.md b/docs/08_namespaces/index.md → docs/namespaces/index.md
diff --git a/docs/01_quickstart/index.md → docs/quickstart/index.md b/docs/01_quickstart/index.md → docs/quickstart/index.md
diff --git a/docs/server/index.md b/docs/server/index.md
@@ -0,0 +1,56 @@
+# server
+`vkv server` is a subcommand that starts simple http server that accepts `GET` request `/export` on port `8080` (change using `--port`).
+
+This is helps using `vkv` as a service container for usage during CI:
+
+
+## Server side
+```bash
+export VAULT_ADDR="..."
+export VAULT_TOKEN="..." 
+vkv server --path secret
+```
+
+## Client side
+```bash
+$> curl localhost:88080/export
+secret/
+├── v1: admin [key=value]  
+│   └── sub=********        
+├── v1: demo
+│   └── foo=***
+└── sub/
+    ├── v1: demo
+    │   ├── demo=***********
+    │   ├── password=******
+    │   └── user=*****
+    └── sub2
+        └── v2: demo [admin=false key=value]
+            ├── admin=***
+            ├── foo=***
+            ├── password=********
+            └── user=****
+```
+
+## Output Format
+you can speciy the output format by adding a `format`-URL Query Parameter:
+
+```bash
+$> curl localhost:88080/export?format=yaml
+secret/:
+  admin:
+    sub: '********'
+  demo:
+    foo: '***'
+  sub/:
+    demo:
+      demo: '***********'
+      password: '******'
+      user: '*****'
+    sub2/:
+      demo:
+        admin: '***'
+        foo: '***'
+        password: '********'
+        user: '****'
+```
diff --git a/docs/07_snapshot/restore.md → docs/snapshot/restore.md b/docs/07_snapshot/restore.md → docs/snapshot/restore.md
diff --git a/docs/07_snapshot/save.md → docs/snapshot/save.md b/docs/07_snapshot/save.md → docs/snapshot/save.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -15,37 +15,32 @@ plugins:
       enable_creation_date: false
 
 nav:
-  - vkv: 
-    - vkv: index.md
-    - Quickstart: 
-      - Quickstart: 01_quickstart/index.md
-    - Installation: 
-      - Installation: 02_installation/index.md
-    - Authentication: 
-      - Authentication: 03_authentication/index.md
-    - Configuration:
-      - Configuration: 04_configuration/index.md
-    - Export: 
-      - Export: 05_export/index.md
-      - Export Formats: 05_export/formats.md
-    - Import:
-      - Import: 06_import/index.md
-    - Snapshots:
-      - Snapshot Save: 07_snapshot/save.md
-      - Snapshot Restore: 07_snapshot/restore.md
-    - List Namespaces: 
-      - List Namespaces: 08_namespaces/index.md
-    - List Engines: 
-      - List Engines: 09_engines/index.md
-    - Advanced Examples: 
-      - 10_advanced_examples/diff.md
-      - 10_advanced_examples/fzf.md
-      - 10_advanced_examples/kubernetes.md
-      - 10_advanced_examples/sops.md
-      - 10_advanced_examples/direnv.md
-      - 10_advanced_examples/gitlab.md
-    - Development: 
-      - Development: 11_development/index.md
+  - vkv: index.md
+  - Quickstart: quickstart/index.md
+  - Installation: installation/index.md
+  - Authentication: authentication/index.md
+  - Configuration: configuration/index.md
+  - Export: 
+    - Export: export/index.md
+    - Export Formats: export/formats.md
+  - Import: import/index.md
+  - Snapshots:
+    - Snapshot Save: snapshot/save.md
+    - Snapshot Restore: snapshot/restore.md
+  - List Namespaces: namespaces/index.md
+  - List Engines: engines/index.md
+  - Server: server/index.md
+  - Advanced Examples: 
+    - advanced_examples/diff.md
+    - advanced_examples/fzf.md
+    - advanced_examples/kubernetes.md
+    - advanced_examples/sops.md
+    - advanced_examples/direnv.md
+  - CI/CD Integrations:
+    - cicd/gitlab.md
+    - cicd/github.md
+    - cicd/azure.md
+  - Development: development/index.md
 
 markdown_extensions:
   - pymdownx.superfences:
@@ -77,21 +72,15 @@ markdown_extensions:
   - toc:
       permalink: true
 
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/svalabs
-    - icon: fontawesome/brands/linkedin
-      link: https://www.linkedin.com/company/sva-system-vertrieb-alexander-gmbh
-
 theme:
   icon:
     edit: material/pencil
     view: material/eye
     repo: fontawesome/brands/github
   name: material
+
   favicon: assets/favicon.ico
-  #logo: assets/logo.png
+  logo: assets/logo.png
   language: en
   palette:
     # Palette toggle for light mode