Dynamic and Runtime Application Configuration

Spin applications may define custom configuration which can be looked up by component code via the spin-config interface.

Custom Config Variables

Application-global custom config variables are defined in the top-level [variables] section. These entries aren’t accessed directly by components but are referenced by component config value templates. Each entry must either have a default value or be marked as required = true. “Required” entries must be provided with a value.

Configuration keys may only contain lowercase letters and underscores between letters:

api_host = { default = "api.example.com" }
api_key = { required = true }

Component Custom Config

The configuration entries available to a component are listed in its [component.config] section. Configuration values may reference config variables with simple mustache-inspired string templates:

# ...
api_base_url = "https://{{ api_host }}/v1"
api_key = "{{ api_key }}"

Custom Config Providers

Custom config variables values may be set at runtime by config “providers”. Currently, there are two providers: the environment variable provider and vault config provider.

Environment Variable Provider

The environment variable provider which gets config values from the spin process’s environment (not the component environment). Config keys are translated to environment variables by upper-casing and prepending with SPIN_CONFIG_:

$ export SPIN_CONFIG_API_KEY = "1234"  # Sets the `api_key` value.
$ spin up

Vault Config Provider

The Vault config provider gets secret values from HashiCorp Vault. Currently, only KV Secrets Engine - Version 2 is supported. You can set up v2 kv secret engine at any mount point and give Vault information in the runtime configuration file:

type = "vault"
url = ""
token = "root"
mount = "secret"
Vault Config Provider Example
  1. Install Vault.
  2. Start Vault:
$ vault server -dev -dev-root-token-id root
  1. Set a password:
$ export VAULT_TOKEN=root
$ export VAULT_ADDR=
$ vault kv put secret/password value="test_password"
$ vault kv get secret/password
  1. Go to spin/tests/http/vault-config-test folder.
  2. Start vault-config-test app:
$ spin build
$ spin up --runtime-config-file runtime_config.toml
  1. Test the app:
$ curl -i
HTTP/1.1 200 OK
content-length: 26
date: Tue, 18 Oct 2022 12:34:40 GMT

Got password test_password

Runtime Configuration

Runtime configuration contains config provider information like vault config provider. You can use the runtime configuration by giving --runtime-config-file in spin up command.

Did we miss something?

Let us know how we can improve this project, or contribute an edit to this page. We really appreciate your feedback, to help us build better tools.