Merge pull request #149 from external-secrets/docs/vault

feat(docs): add basic docs for vault

README.md

@@ -13,7 +13,7 @@ Multiple people and organizations are joining efforts to create a single Externa
 
 - [AWS Secrets Manager](https://external-secrets.io/provider-aws-secrets-manager/)
 - [AWS Parameter Store](https://external-secrets.io/provider-aws-parameter-store/)
-- Hashicorp Vault
+- [Hashicorp Vault](https://www.vaultproject.io/)
 - [Azure Key Vault](https://external-secrets.io/provider-azure-key-vault/) (being implemented)
 - [Google Cloud Secrets Manager](https://external-secrets.io/provider-google-secrets-manager/) (being implemented)
 

docs/provider-hashicorp-vault.md

@@ -1,5 +1,46 @@
+![HCP Vault](./pictures/diagrams-provider-vault.png)
 
-!!! bug "Not implemented"
-    This is currently **not yet** implemented. Feel free
-    to contribute. Please see [issue#21](https://github.com/external-secrets/external-secrets/issues/21)
-    for futher information.
+## Hashicorp Vault
+
+External Secrets Operator integrates with [HashiCorp Vault](https://www.vaultproject.io/) for secret
+management. Vault itself implements lots of different secret engines, as of now we only support the
+[KV Secrets Engine](https://www.vaultproject.io/docs/secrets/kv).
+
+### Authentication
+
+We support three different modes for authentication:
+[token-based](https://www.vaultproject.io/docs/auth/token),
+[appRole](https://www.vaultproject.io/docs/auth/approle) and
+[kubernetes-native](https://www.vaultproject.io/docs/auth/kubernetes), each one comes with it's own
+trade-offs. Depending on the authentication method you need to adapt your environment.
+
+#### Token-based authentication
+
+A static token is stored in a `Kind=Secret` and is used to authenticate with vault.
+
+```yaml
+{% include 'vault-token-store.yaml' %}
+```
+
+#### AppRole authentication example
+
+[AppRole authentication](https://www.vaultproject.io/docs/auth/approle) reads the secret id from a
+`Kind=Secret` and uses the specified `roleId` to aquire a temporary token to fetch secrets.
+
+```yaml
+{% include 'vault-approle-store.yaml' %}
+```
+
+#### Kubernetes authentication
+
+[Kubernetes-native authentication](https://www.vaultproject.io/docs/auth/kubernetes) has three
+options of optaining credentials for vault:
+
+1.  by using a service account jwt referenced in `serviceAccountRef`
+2.  by using the jwt from a `Kind=Secret` referenced by the `secretRef`
+3.  by using transient credentials from the mounted service account token within the
+    external-secrets operator
+
+```yaml
+{% include 'vault-kubernetes-store.yaml' %}
+```

docs/snippets/full-secret-store.yaml

@@ -6,12 +6,13 @@ metadata:
 spec:
 
   # Used to select the correct ESO controller (think: ingress.ingressClassName)
-  # The ESO controller is instantiated with a specific controller name and filters ES based on this property
+  # The ESO controller is instantiated with a specific controller name
+  # and filters ES based on this property
   # Optional
   controller: dev
 
-  # provider field contains the configuration to access the provider which contains the secret
-  # exactly one provider must be configured.
+  # provider field contains the configuration to access the provider
+  # which contains the secret exactly one provider must be configured.
   provider:
 
     # (1): AWS Secrets Manager
@@ -33,6 +34,47 @@ spec:
             name: awssm-secret
             key: secret-access-key
 
+    vault:
+      server: "https://vault.acme.org"
+      # Path is the mount path of the Vault KV backend endpoint
+      path: "secret"
+      # Version is the Vault KV secret engine version.
+      # This can be either "v1" or "v2", defaults to "v2"
+      version: "v2"
+      # vault enterprise namespace: https://www.vaultproject.io/docs/enterprise/namespaces
+      namespace: "a-team"
+      caBundle: "..."
+      auth:
+        # static token: https://www.vaultproject.io/docs/auth/token
+        tokenSecretRef:
+          name: "my-secret"
+          namespace: "secret-admin"
+          key: "vault-token"
+
+        # AppRole auth: https://www.vaultproject.io/docs/auth/approle
+        appRole:
+          path: "approle"
+          roleId: "db02de05-fa39-4855-059b-67221c5c2f63"
+          secretRef:
+            name: "my-secret"
+            namespace: "secret-admin"
+            key: "vault-token"
+
+        # Kubernetes auth: https://www.vaultproject.io/docs/auth/kubernetes
+        kubernetes:
+          mountPath: "kubernetes"
+          role: "demo"
+          # Optional service account reference
+          serviceAccountRef:
+            name: "my-sa"
+            namespace: "secret-admin"
+          # Optional secret field containing a Kubernetes ServiceAccount JWT
+          # used for authenticating with Vault
+          secretRef:
+            name: "my-secret"
+            namespace: "secret-admin"
+            key: "vault"
+
     # (TODO): add more provider examples here
 
 status:

docs/snippets/vault-approle-store.yaml

@@ -0,0 +1,24 @@
+apiVerson: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+  name: vault-backend
+  namespace: example
+spec:
+  provider:
+    vault:
+      server: "https://vault.acme.org"
+      path: "secret"
+      version: "v2"
+      auth:
+        # VaultAppRole authenticates with Vault using the
+        # App Role auth mechanism
+        # https://www.vaultproject.io/docs/auth/approle
+        appRole:
+          # Path where the App Role authentication backend is mounted
+          path: "approle"
+          # RoleID configured in the App Role authentication backend
+          roleId: "db02de05-fa39-4855-059b-67221c5c2f63"
+          secretRef:
+            name: "my-secret"
+            namespace: "secret-admin"
+            key: "vault-token"

docs/snippets/vault-kubernetes-store.yaml

@@ -0,0 +1,31 @@
+apiVerson: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+  name: vault-backend
+  namespace: example
+spec:
+  provider:
+    vault:
+      server: "https://vault.acme.org"
+      path: "secret"
+      version: "v2"
+      auth:
+        # Authenticate against Vault using a Kubernetes ServiceAccount
+        # token stored in a Secret.
+        # https://www.vaultproject.io/docs/auth/kubernetes
+        kubernetes:
+          # Path where the Kubernetes authentication backend is mounted in Vault
+          mountPath: "kubernetes"
+          # A required field containing the Vault Role to assume.
+          role: "demo"
+          # Optional service account field containing the name
+          # of a kubernetes ServiceAccount
+          serviceAccountRef:
+            name: "my-sa"
+            namespace: "secret-admin"
+          # Optional secret field containing a Kubernetes ServiceAccount JWT
+          #  used for authenticating with Vault
+          secretRef:
+            name: "my-secret"
+            namespace: "secret-admin"
+            key: "vault"

docs/snippets/vault-token-store.yaml

@@ -0,0 +1,18 @@
+apiVerson: external-secrets.io/v1alpha1
+kind: SecretStore
+metadata:
+  name: vault-backend
+  namespace: example
+spec:
+  provider:
+    vault:
+      server: "https://vault.acme.org"
+      path: "secret"
+      version: "v2"
+      auth:
+        # points to a secret that contains a vault token
+        # https://www.vaultproject.io/docs/auth/token
+        tokenSecretRef:
+          name: "my-secret"
+          namespace: "secret-admin"
+          key: "vault-token"