Merge pull request #13 from numberly/documentation-comparison-and-fix

Documentation comparison and fix
numberly · May 28, 2024 · 33a1381 · 33a1381
2 parents f350878 + 1c18ffb
commit 33a1381
Show file tree

Hide file tree

Showing 14 changed files with 80 additions and 144 deletions.
diff --git a/README.md b/README.md
@@ -16,6 +16,9 @@ Checkout the [Vault DB Injector documentation](https://numberly.github.io/vault-
 
 Contributions to the vault-db-injector are welcome. Please submit your pull requests or issues to the project's GitLab repository.
 
+## 4. <a name='Tool Comparison'></a>Projects Comparison
+
+Here you can find a comparison with many vault injector projects : [Comparaison](https://numberly.github.io/vault-db-injector/getting-started/comparison/)
 
 ##  5. <a name='Acknowledgements'></a>Acknowledgements
 

diff --git a/docs/getting-started/comparison.md b/docs/getting-started/comparison.md
@@ -0,0 +1,72 @@
+# Comparison
+
+A vault injector retrieves credentials from a vault database engine and injects them into pods' environment variables. This document compares different existing tools with the new vault injector being developed.
+
+## Summary
+
+##  1. <a name='WhyVault-Db-Injector'></a>Why Vault-Db-Injector?
+
+Before comparing Vault-Db-Injector with existing tools, we would like to share that we initially investigated various vault injector solutions designed to fetch credentials from Vault.
+
+After extensive research, we found no tools that matched our needs, and most of them were difficult to contribute to.
+
+Vault-Db-Injector is not a replacement for any existing vault injector but a tool more focused on security and the database engine.
+
+We didn't intend to reinvent the wheel but designed a tool that perfectly matches our needs and shared it with those who might be interested.
+
+##  2. <a name='ToolsComparison'></a>Tools Comparison
+
+Here are the major tools that we compare our injector to:
+
+- [Vault Agent Injector](https://developer.hashicorp.com/vault/docs/platform/k8s/injector)
+- [Bank Vault](https://github.com/bank-vaults/bank-vaults)
+- [Vals Operator](https://github.com/digitalis-io/vals-operator)
+- [Vault CSI Provider](https://developer.hashicorp.com/vault/docs/platform/k8s/csi)
+
+##  3. <a name='Ourneeds'></a>Our needs
+
+Here are our needs by importance in our research : 
+
+- Handle database engine
+- Injection through environment variables
+- Easy to use for developpers
+- Audit logging
+- Lease can be automatically renewed and revoked
+- State is available for debugging purpose and manual revocation also
+- Working with a single deployment
+
+
+##  4. <a name='ComparisonTable'></a>Comparison Table
+
+| Feature                              | Vault-Db-Injector     | Vault Agent Injector                | Bank Vault (webhook)               | Vals Operator                   | Vault CSI Provider              |
+|--------------------------------------|-----------------------|-------------------------------------|------------------------------------|---------------------------------|---------------------------------|
+| **Credential Source**                | Vault Database Engine | Multiple Engines                    | Secret Engine                      | Multiple Engine                 | K/V                             |
+| **Engine**                           | Database              | All                                 | K/V                                | Database and K/V                | K/V                             |
+| **Injection Method**                 | Pod Environment Vars  | Sidecar Container / Init Container  | Init Container (in-memory)         | Kubernetes Secrets              | CSI Volume                      |
+| **Dynamic Secret Rotation**          | 🚫 Not needed         | ✅ Yes                              | ✅ Yes                             | ❌ No                           | ✅ Yes                           |
+| **Access Control**                   | Role-Based Policies   | Role-Based Policies                 | Role-Based Policies                | Role-Based Policies             | Role-Based Policies             |
+| **Configuration Complexity**         | 🟢 Low                | 🔴 Very High                        | 🟢 Low                             | 🟠 Moderate                     | 🟠 Moderate                     |
+| **User Complexity**                  | 🟢 Low                | 🔴 Very High                        | 🟢 Low                             | 🟠 Moderate                     | 🟢 Low                          |
+| **Operation Mode**                   | Deployment            | Deployment                          | Deployment                         | Operator                        | Operator                        |
+| **Configuration Mode**               | Annotations           | Annotations                         | Through Env                        | CRDS                            | CRDS                            |
+| **Handle Environment**               | ✅ Yes                | ❌ No                               | ✅ Yes                             | ✅ Yes                          | ✅ Yes (secretRef)              |
+| **Secret Encryption**                | ✅ Yes                | ✅ Yes                              | ✅ Yes                             | ✅ Yes                          | ✅ Yes                           |
+| **Audit Logging**                    | ✅ Yes                | ✅ Yes                              | ✅ Yes                             | ✅ Yes                          | ✅ Yes                           |
+| **Accessible state**                 | ✅ Yes                | ❌ No                               | ❌ No                              | ❌ No                           | ❌ No                            |
+| **Lease Renew**                      | ✅ Yes                | ✅ Yes                              | -                                  | 🤔 With restarting              | -                                |
+| **Lease Revocation**                 | ✅ Yes                | ❌ No                               | -                                  | ❌ No                           | -                                |
+| **Community Support**                | 🌱 Growing            | 🟢 Established                      | 🟠 Moderate                        | 🟠 Moderate                     | 🟢 Established                   |
+
+###  4.1. <a name='Key'></a>Key
+
+- ✅ Yes
+- ❌ No
+- 🤔 Consideration (Intermediate)
+- 🚫 Not Needed
+- 🟢 Low
+- 🟠 Moderate
+- 🔴 High
+
+##  5. <a name='Conclusion'></a>Conclusion
+
+This comparison highlights the unique features and capabilities of the new vault injector. While similar in many ways to existing solutions, the new tool offers dynamic secret rotation without requiring pod restarts, moderate configuration complexity, and robust access control, making it a compelling choice for managing secrets in Kubernetes environments.
diff --git a/docs/getting-started/getting-started.md b/docs/getting-started/getting-started.md
@@ -1,24 +1,4 @@
 # getting-started
-<!-- vscode-markdown-toc -->
-* 1. [Requirements](#Requirements)
-* 2. [Vocabulary](#Vocabulary)
-* 3. [Vault Configuration](#VaultConfiguration)
-	* 3.1. [Create `all-rw` vault-policy](#Createall-rwvault-policy)
-	* 3.2. [Create `K/V Vault`](#CreateKVVault)
-	* 3.3. [Create `vault databases mount`](#Createvaultdatabasesmount)
-	* 3.4. [Create `vault databases backend connection`](#Createvaultdatabasesbackendconnection)
-	* 3.5. [Create a `kubernetes auth backend`](#Createakubernetesauthbackend)
-	* 3.6. [Create a `kubernetes auth backend role`](#Createakubernetesauthbackendrole)
-	* 3.7. [Create `vault databases backend role`](#Createvaultdatabasesbackendrole)
-* 4. [`Database` configuration](#Databaseconfiguration)
-* 5. [Deploy the vault db injector](#Deploythevaultdbinjector)
-* 6. [Deploy an example application :](#Deployanexampleapplication:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
 
 ##  1. <a name='Requirements'></a>Requirements
 

diff --git a/docs/how-it-works/configuration.md b/docs/how-it-works/configuration.md
@@ -1,19 +1,8 @@
 # Configuration
-<!-- vscode-markdown-toc -->
-	* 1. [Configuration](#Configuration)
-		* 1.1. [Mode Injector](#ModeInjector)
-		* 1.2. [Mode token-renewer](#Modetoken-renewer)
-		* 1.3. [Mode token-renewer](#Modetoken-renewer-1)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
 
 Here is the configuration for Vault Injector:
 
-####  1.1. <a name='ModeInjector'></a>Mode Injector
+#  1 <a name='ModeInjector'></a>Mode Injector
 The Injector mode is basic one that will handle all api-server request and handle all requests to vault to generate credentials to our DB
 The config file path can be parse by adding the path with : `- "--config=/injector/config.yaml"`
 ```yaml
@@ -33,7 +22,7 @@ injectorLabel: vault-db-injector
 defaultEngine: databases
 ```
 
-####  1.2. <a name='Modetoken-renewer'></a>Mode token-renewer
+#  1 <a name='Modetoken-renewer'></a>Mode token-renewer
 The Renewer one is a process that will run every hour and validate that all orphan token won't expire before pod is deleted 
 The config file path can be parse by adding the path with : `- "--config=/renewer/config.yaml"`
 ```yaml
@@ -52,7 +41,7 @@ injectorLabel: vault-db-injector
 defaultEngine: databases
 ```
 
-####  1.3. <a name='Modetoken-renewer-1'></a>Mode token-renewer
+#  1 <a name='Modetoken-renewer-1'></a>Mode token-renewer
 The Revoker one is a process that is going to watch pod deletion Kubernetes events filtered with the label `vault-db-injector: true` and will revoke token attached to the pod when it is deleted 
 The config file path can be parse by adding the path with : `- "--config=/revoker/config.yaml"`
 ```yaml

diff --git a/docs/how-it-works/healthcheck.md b/docs/how-it-works/healthcheck.md
@@ -1,14 +1,4 @@
 # Health Checks
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Key Responsibilities:](#KeyResponsibilities:)
-* 3. [Benefits:](#Benefits:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
 
 **Key File:** `pkg/healthcheck/healthcheck.go`
 

diff --git a/docs/how-it-works/how-it-work.md b/docs/how-it-works/how-it-work.md
@@ -1,24 +1,6 @@
 # How it Work
 
-<!-- vscode-markdown-toc -->
-* 1. [Vault-Injector](#Vault-Injector)
-	* 1.1. [Mechanism](#Mechanism)
-		* 1.1.1. [Vault Injector:](#VaultInjector:)
-	* 1.2. [Diagram](#Diagram)
-	* 1.3. [Vault Usage](#VaultUsage)
-	* 1.4. [Authentication](#Authentication)
-	* 1.5. [How token are handled ?](#Howtokenarehandled)
-	* 1.6. [How does injector work then ?](#Howdoesinjectorworkthen)
-	* 1.7. [Usage :](#Usage:)
-		* 1.7.1. [In mode classic](#Inmodeclassic)
-		* 1.7.2. [In mode URI](#InmodeURI)
-		* 1.7.3. [With multiple databases](#Withmultipledatabases)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->##  1. <a name='Vault-Injector'></a>Vault-Injector
+##  1. <a name='Vault-Injector'></a>Vault-Injector
 
 The Vault DB Injector is a Go program that is design to retrieve databases credentials from Hashicorp Vault, it use Kubernetes Mutating Webhook to intercept pod creation activated with a label and configured with annotations.
 After the credentials are provided, it will store them in a specific Vault KV and will handle the lifecycle of them such as : 

diff --git a/docs/how-it-works/injector.md b/docs/how-it-works/injector.md
@@ -1,15 +1,5 @@
 # Injector
 
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Benefits:](#Benefits:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 **Key File:** `pkg/injector/injector.go`
 
 ##  1. <a name='HowItWorks:'></a>How It Works:

diff --git a/docs/how-it-works/kubernetes.md b/docs/how-it-works/kubernetes.md
@@ -1,17 +1,5 @@
 # Kubernetes Integration
 
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Key Responsibilities:](#KeyResponsibilities:)
-* 3. [Benefits:](#Benefits:)
-	* 3.1. [Annotations :](#Annotations:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 **Key Files:** `pkg/k8s/connect.go`, `pkg/k8s/pod_utils.go`, `pkg/k8s/parse_annotations.go`
 
 ##  1. <a name='HowItWorks:'></a>How It Works:

diff --git a/docs/how-it-works/leaderelection.md b/docs/how-it-works/leaderelection.md
@@ -1,16 +1,5 @@
 # Leader Election
 
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Key Responsibilities:](#KeyResponsibilities:)
-* 3. [Benefits:](#Benefits:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 **Key File:** `pkg/leadership/leadership.go`
 
 ##  1. <a name='HowItWorks:'></a>How It Works:

diff --git a/docs/how-it-works/renewer.md b/docs/how-it-works/renewer.md
@@ -1,16 +1,5 @@
 # Renewer
 
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Key Responsibilities:](#KeyResponsibilities:)
-* 3. [Benefits:](#Benefits:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 **Key File:** `pkg/renewer/renewer.go`
 
 ##  1. <a name='HowItWorks:'></a>How It Works:

diff --git a/docs/how-it-works/revoker.md b/docs/how-it-works/revoker.md
@@ -1,16 +1,5 @@
 # Revoker
 
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Key Responsibilities:](#KeyResponsibilities:)
-* 3. [Benefits:](#Benefits:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 **Key File:** `pkg/revoker/revoker.go`
 
 ##  1. <a name='HowItWorks:'></a>How It Works:

diff --git a/docs/how-it-works/vault.md b/docs/how-it-works/vault.md
@@ -1,16 +1,5 @@
 # Vault Integration
 
-<!-- vscode-markdown-toc -->
-* 1. [How It Works:](#HowItWorks:)
-* 2. [Key Responsibilities:](#KeyResponsibilities:)
-* 3. [Benefits:](#Benefits:)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 **Key Files:** `pkg/vault/handle_token.go`, `pkg/vault/vault.go`
 
 ##  1. <a name='HowItWorks:'></a>How It Works:

diff --git a/docs/monitoring/alertmanager.md b/docs/monitoring/alertmanager.md
@@ -1,20 +1,5 @@
 # Alertmanager Configuration for VaultDb Injector
 
-<!-- vscode-markdown-toc -->
-* 1. [Alerts Configuration](#AlertsConfiguration)
-	* 1.1. [Service Account Denied](#ServiceAccountDenied)
-	* 1.2. [Token Renewal Failure](#TokenRenewalFailure)
-	* 1.3. [Lease Renewal Failure](#LeaseRenewalFailure)
-	* 1.4. [Token Expiration Warnings](#TokenExpirationWarnings)
-	* 1.5. [Lease Expiration Warnings](#LeaseExpirationWarnings)
-* 2. [Conclusion](#Conclusion)
-
-<!-- vscode-markdown-toc-config
-	numbering=true
-	autoSave=true
-	/vscode-markdown-toc-config -->
-<!-- /vscode-markdown-toc -->
-
 This configuration defines a set of alerts for monitoring the VaultDb Injector within a Kubernetes environment. Each alert is designed to notify the team of potential issues that could impact the availability, security, or functionality of the services relying on Vault for secret management.
 
 ##  1. <a name='AlertsConfiguration'></a>Alerts Configuration

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -45,6 +45,7 @@ nav:
   - Home: index.md
   - Getting Started:
     - getting-started/getting-started.md
+    - getting-started/comparison.md
     - getting-started/build.md
   - How it Works:
     - how-it-works/how-it-work.md