diff --git a/content/v4/dynamic-configuration.md b/content/v4/dynamic-configuration.md index 826875b8..25ba02db 100644 --- a/content/v4/dynamic-configuration.md +++ b/content/v4/dynamic-configuration.md @@ -11,6 +11,8 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/v4/dynamic-c - [Environment Variable Provider](#environment-variable-provider) - [Vault Application Variable Provider](#vault-application-variable-provider) - [Vault Application Variable Provider Example](#vault-application-variable-provider-example) + - [OpenBao Application Variable Provider](#openbao-application-variable-provider) + - [OpenBao Application Variable Provider Example](#openbao-application-variable-provider-example) - [Azure Key Vault Application Variable Provider](#azure-key-vault-application-variable-provider) - [Azure Key Vault Application Variable Provider Example](#azure-key-vault-application-variable-provider-example) - [Key Value Store Runtime Configuration](#key-value-store-runtime-configuration) @@ -46,7 +48,7 @@ Let's look at each configuration category in-depth below. When an application needs the value of an [application variable](./variables), it obtains it from a provider. By default, the only provider Spin considers is the [environment variables provider](#environment-variable-provider). That is, application variables are derived from the environment variables of the Spin process. -You can also tell Spin to use the [Vault provider](#vault-application-variable-provider) and/or the [Azure Key Vault provider](#azure-key-vault-application-variable-provider), by setting these up in the runtime config file. +You can also tell Spin to use the [Vault provider](#vault-application-variable-provider), [OpenBao provider](#openbao-application-variable-provider) and/or the [Azure Key Vault provider](#azure-key-vault-application-variable-provider), by setting these up in the runtime config file. You can tell Spin to use multiple application variable providers. Spin prioritises them in the order they appear in the runtime config file, with higher-listed providers taking precedence. The environment variable provider that Spin adds by default always has the lowest priority, and values passed on the command line via `spin up --variable` always have the highest. @@ -142,6 +144,75 @@ $ curl localhost:3000 --data "wrong_password" {"authentication": "denied"} ``` +### OpenBao Application Variable Provider + +The OpenBao application variable provider gets secret values from [OpenBao](https://openbao.org/). +Currently, only the [KV Secrets Engine - Version 2](https://openbao.org/docs/secrets/kv/kv-v2/) is supported. +You can set up the v2 kv secret engine at any mount point and provide Vault information in +the [runtime configuration](#runtime-configuration) file: + + + +```toml +[[config_provider]] +type = "open_bao" +url = "http://127.0.0.1:8200" +token = "root" +mount = "secrets" +``` + +#### OpenBao Application Variable Provider Example + +1. [Install OpenBao](https://openbao.org/docs/install/). +2. Start OpenBao: + + + +```bash +$ bao server -dev -dev-root-token-id="dev-only-token" +``` + +3. Set a password in kv: + + + +```bash +$ export VAULT_TOKEN="dev-only-token" +$ export VAULT_ADDR=http://127.0.0.1:8200 + +# Create a "demo-secrets" mount +$ bao secrets enable -path=secrets kv-v2 +$ bao kv put secrets/sample_secret value="secret_sauce" + +# Retrieve the "sample_secret" again +$ bao kv get secrets/sample_secret +``` + +4. Go to the [OpenBao variable provider example](https://github.com/fermyon/enterprise-architectures-and-patterns/tree/main/application-variable-providers/openbao-provider) application. +5. Build and run the `openbao-provider` app: + + + +```bash +$ spin build +$ spin up --runtime-config-file runtime-config.toml +``` + +6. Test the app: + + + +```bash +$ curl localhost:3000 --data "secret_sauce" +{"authentication": "accepted"} +``` + + +```bash +$ curl localhost:3000 --data "wrong_password" +{"authentication": "denied"} +``` + ### Azure Key Vault Application Variable Provider The Azure Key Vault application variable provider gets secret values from [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). diff --git a/content/v4/variables.md b/content/v4/variables.md index 40f570f3..782f03a2 100644 --- a/content/v4/variables.md +++ b/content/v4/variables.md @@ -16,7 +16,7 @@ url = "https://github.com/spinframework/spin-docs/blob/main/content/v4/variables Spin supports dynamic application variables. Instead of being static, their values can be updated without modifying the application, creating a simpler experience for rotating secrets, updating API endpoints, and more. -These variables are defined in a Spin application manifest (in the `[variables]` section), and their values can be set or overridden at runtime by an [application variables provider](./dynamic-configuration.md#application-variables-runtime-configuration), or the `--variable` flag to `spin up`. When running Spin locally, the variables provider can be [Hashicorp Vault](./dynamic-configuration.md#vault-application-variable-provider) for secrets, [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault), or host environment variables. [See below](#setting-variable-values) for more information. +These variables are defined in a Spin application manifest (in the `[variables]` section), and their values can be set or overridden at runtime by an [application variables provider](./dynamic-configuration.md#application-variables-runtime-configuration), or the `--variable` flag to `spin up`. When running Spin locally, the variables provider can be [Hashicorp Vault](./dynamic-configuration.md#vault-application-variable-provider) or [OpenBao](./dynamic-configuration.md#openbao-application-variable-provider) for secrets, [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault), or host environment variables. [See below](#setting-variable-values) for more information. ## Adding Variables to Your Applications @@ -47,7 +47,7 @@ api_uri = "\{{ api_uri }}" api_version = "v1" ``` -When a component variable references an application variable, its value will dynamically update as the application variable changes. For example, if the `api_token` variable is provided using the [Spin Vault provider](./dynamic-configuration.md#vault-application-variable-provider), it can be updated by changing the value in HashiCorp Vault. The next time the component gets the value of `token`, the latest value of `api_token` will be returned by the provider. See the [next section](#using-variables-from-applications) to learn how to use Spin's configuration SDKs to get configuration variables within applications. +When a component variable references an application variable, its value will dynamically update as the application variable changes. For example, if the `api_token` variable is provided using the [Spin Vault provider](./dynamic-configuration.md#vault-application-variable-provider) or [Spin OpenBao provider](./dynamic-configuration.md#openbao-application-variable-provider), it can be updated by changing the value either in HashiCorp Vault or OpenBao. The next time the component gets the value of `token`, the latest value of `api_token` will be returned by the provider. See the [next section](#using-variables-from-applications) to learn how to use Spin's configuration SDKs to get configuration variables within applications. Variables can also be used in other sections of the application manifest that benefit from runtime configuration. In these cases, the variables are substituted at application load time rather than dynamically updated while the application is running. For example, the `allowed_outbound_hosts` can be dynamically configured using variables as follows: @@ -58,7 +58,6 @@ Variables can also be used in other sections of the application manifest that be allowed_outbound_hosts = [ "\{{ api_uri }}" ] ``` - All in all, an application manifest with `api_token` and `api_uri` variables and a component that uses them would look similar to the following: @@ -285,7 +284,7 @@ When you run an application, you must provide values for all required variables, ### Providing Variable Values from a Secrets Store -You can provide variable values from a secrets store. The Spin CLI supports [Hashicorp Vault](./dynamic-configuration.md#vault-application-variable-provider) and [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). If you want to do this, you must set up the store in the runtime configuration file, and reference that file using `--runtime-config-file` on the command line. +You can provide variable values from a secrets store. The Spin CLI supports [Hashicorp Vault](./dynamic-configuration.md#vault-application-variable-provider), [OpenBao](./dynamic-configuration.md#openbao-application-variable-provider) and [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). If you want to do this, you must set up the store in the runtime configuration file, and reference that file using `--runtime-config-file` on the command line. For information about configuring application variables providers, refer to the [runtime configuration documentation](./dynamic-configuration.md#application-variables-runtime-configuration). @@ -340,4 +339,4 @@ If you run into the following error, you've most likely not configured the compo Handler returned an error: Error::Undefined("no variable for \"\".\"your-variable\"") ``` -To fix this, edit the `spin.toml` and add to the `[component..variables]` table a line such as ` = "\{{ app-variable }}".` See [above](#adding-variables-to-your-applications) for more information. \ No newline at end of file +To fix this, edit the `spin.toml` and add to the `[component..variables]` table a line such as ` = "\{{ app-variable }}".` See [above](#adding-variables-to-your-applications) for more information.