diff --git a/docs/examples/bitwarden.md b/docs/examples/bitwarden.md index e5653c69ee..f1e81f9d02 100644 --- a/docs/examples/bitwarden.md +++ b/docs/examples/bitwarden.md @@ -2,27 +2,23 @@ Bitwarden is an integrated open source password management solution for individuals, teams, and business organizations. -## How is it working ? +## How does it work? -To make external-secret compatible with BitWarden, we need: +To make external-secrets compatible with Bitwarden, we need: -* External-Secret >= 0.8.0 -* To use the Webhook Provider -* 2 (Cluster)SecretStores +* External Secrets Operator >= 0.8.0 +* Multiple (Cluster)SecretStores using the webhook provider * BitWarden CLI image running `bw serve` -When you create a new external-secret object, -External-Secret Webhook provider will do a query to the Bitwarden CLI pod, -which is synced with the BitWarden server. +When you create a new external-secret object, the External Secrets webhook provider will query the Bitwarden CLI pod that is synced with the Bitwarden server. ## Requirements -* Bitwarden account (it works also with VaultWarden) -* A Kubernetes secret which contains your BitWarden Credentials -* You need a Docker image with BitWarden CLI installed. - You could use `ghcr.io/charlesthomas/bitwarden-cli:2023.12.1` or build your own. +* Bitwarden account (it also works with Vaultwarden!) +* A Kubernetes secret which contains your Bitwarden credentials +* A Docker image running the Bitwarden CLI. You could use `ghcr.io/charlesthomas/bitwarden-cli:2023.12.1` or build your own. -Here an example of Dockerfile use to build this image: +Here is an example of a Dockerfile used to build the image: ```dockerfile FROM debian:sid @@ -41,7 +37,7 @@ COPY entrypoint.sh / CMD ["/entrypoint.sh"] ``` -And the content of `entrypoint.sh` +And the content of `entrypoint.sh`: ```bash #!/bin/bash @@ -57,8 +53,7 @@ echo 'Running `bw server` on port 8087' bw serve --hostname 0.0.0.0 #--disable-origin-protection ``` - -## Deploy Bitwarden Credentials +## Deploy Bitwarden credentials ```yaml {% include 'bitwarden-cli-secrets.yaml' %} @@ -70,30 +65,37 @@ bw serve --hostname 0.0.0.0 #--disable-origin-protection {% include 'bitwarden-cli-deployment.yaml' %} ``` -> NOTE: Deploying a network policy is recommended since, there is no authentication to query the BitWarden CLI, which means that your secrets are exposed. +> NOTE: Deploying a network policy is recommended since there is no authentication to query the Bitwarden CLI, which means that your secrets are exposed. -> NOTE: In this example the Liveness probe is quering /sync to ensure that the BitWarden CLI is able to connect to the server and also to sync secrets. (The secret sync is only every 2 minutes in this example) +> NOTE: In this example the Liveness probe is querying /sync to ensure that the Bitwarden CLI is able to connect to the server and is also synchronised. (The secret sync is only every 2 minutes in this example) -## Deploy ClusterSecretStore (Or SecretStore) +## Deploy (Cluster)SecretStores -Here the two ClusterSecretStore to deploy +There are four possible (Cluster)SecretStores to deploy, each can access different types of fields from an item in the Bitwarden vault. It is not required to deploy them all. ```yaml {% include 'bitwarden-secret-store.yaml' %} ``` +## Usage + +(Cluster)SecretStores: + +* `bitwarden-login`: Use to get the `username` or `password` fields +* `bitwarden-fields`: Use to get custom fields +* `bitwarden-notes`: Use to get notes +* `bitwarden-attachments`: Use to get attachments + +remoteRef: -## How to use it ? +* `key`: ID of a secret, which can be found in the URL `itemId` parameter: + `https://myvault.com/#/vault?type=login&itemId=........-....-....-....-............`s -* If you need the `username` or the `password` of a secret, you have to use `bitwarden-login` -* If you need a custom field of a secret, you have to use `bitwarden-fields` -* If you need to use a Bitwarden Note for multiline strings (SSH keys, service account json files), you have to use `bitwarden-notes` -* The `key` is the ID of a secret, which can be find in the URL with the `itemId` value: - `https://myvault.com/#/vault?itemId=........-....-....-....-............` -* The `property` is the name of the field: - * `username` for the username of a secret (`bitwarden-login` SecretStore) - * `password` for the password of a secret (`bitwarden-login` SecretStore) - * `name_of_the_custom_field` for any custom field (`bitwarden-fields` SecretStore) +* `property`: Name of the field to access + * `username` for the username of a secret (`bitwarden-login` SecretStore) + * `password` for the password of a secret (`bitwarden-login` SecretStore) + * `name_of_the_custom_field` for any custom field (`bitwarden-fields` SecretStore) + * `id_or_name_of_the_attachment` for any attachment (`bitwarden-attachment`, SecretStore) ```yaml {% include 'bitwarden-secret.yaml' %} diff --git a/docs/snippets/bitwarden-secret-store.yaml b/docs/snippets/bitwarden-secret-store.yaml index 05201c1ce9..d398e976fb 100644 --- a/docs/snippets/bitwarden-secret-store.yaml +++ b/docs/snippets/bitwarden-secret-store.yaml @@ -34,4 +34,14 @@ spec: url: "http://bitwarden-cli:8087/object/item/{{ .remoteRef.key }}" result: jsonPath: "$.data.notes" +--- +apiVersion: external-secrets.io/v1beta1 +kind: ClusterSecretStore +metadata: + name: bitwarden-attachments +spec: + provider: + webhook: + url: "http://bitwarden-cli:8087/object/attachment/{{ .remoteRef.property }}?itemid={{ .remoteRef.key }}" + result: {} {% endraw %} diff --git a/docs/snippets/bitwarden-secret.yaml b/docs/snippets/bitwarden-secret.yaml index 81e279a232..d91d67ccae 100644 --- a/docs/snippets/bitwarden-secret.yaml +++ b/docs/snippets/bitwarden-secret.yaml @@ -2,11 +2,11 @@ apiVersion: external-secrets.io/v1beta1 kind: ExternalSecret metadata: - name: my-db-secrets + name: my-secrets namespace: default spec: target: - name: my-db-secrets + name: my-secrets deletionPolicy: Delete template: type: Opaque @@ -23,6 +23,8 @@ spec: postgresql://{{ .username }}:{{ .password }}@my-postgresql:5432/mydb service_account_key: |- {{ .service_account_key }} + ssh_pub_key: |- + {{ .ssh_pub_key }} data: - secretKey: username sourceRef: @@ -63,4 +65,12 @@ spec: kind: ClusterSecretStore # or SecretStore remoteRef: key: service_account_key + - secretKey: ssh_pub_key + sourceRef: + storeRef: + name: bitwarden-attachments + kind: ClusterSecretStore # or SecretStore + remoteRef: + key: aaaabbbb-cccc-dddd-eeee-000011112222 + property: id_rsa.pub {% endraw %} diff --git a/hack/api-docs/mkdocs.yml b/hack/api-docs/mkdocs.yml index c1de698ea9..974d6ea6d7 100644 --- a/hack/api-docs/mkdocs.yml +++ b/hack/api-docs/mkdocs.yml @@ -73,8 +73,8 @@ nav: - Find Secrets by Name or Metadata: guides/getallsecrets.md - Rewriting Keys: guides/datafrom-rewrite.md - Advanced Templating: - v2: guides/templating.md - v1: guides/templating-v1.md + - v2: guides/templating.md + - v1: guides/templating-v1.md - Kubernetes Secret Types: guides/common-k8s-secret-types.md - "Lifecycle: ownership & deletion": guides/ownership-deletion-policy.md - Decoding Strategies: guides/decoding-strategy.md