Configuration for Spin Applications
Spin applications are comprised of general information (metadata), and a collection
of at least one component. Configuration for a Spin application lives in a TOML
file called spin.toml
(the application manifest). In the example below we can see
a simple HTTP application with a single component executed when the /hello
endpoint
is accessed:
spin_version = "1"
name = "spin-hello-world"
description = "A simple application that returns hello world."
trigger = { type = "http", base = "/" }
version = "1.0.0"
[[component]]
id = "hello"
description = "A simple component that returns hello world."
source = "target/wasm32-wasi/release/spinhelloworld.wasm"
[component.trigger]
route = "/hello"
[component.build]
command = "cargo build --target wasm32-wasi --release"
Application Manifest Reference
Application Configuration
The following are the fields supported by the spin.toml
manifest file:
spin_version
(REQUIRED): Spin API version. Currently, this value MUST be"1"
.name
(REQUIRED): Name of the application.version
(REQUIRED): Version of the application.description
(OPTIONAL): Description of the application.authors
(OPTIONAL): List with the authors of the application.trigger
(REQUIRED): Trigger for the application. Currently, the two implemented trigger types are:http
: All components of the application are invoked as a result of incoming HTTP requests. The HTTP trigger configuration has the following fields:type
(REQUIRED): The application trigger type with the value"http"
.base
(REQUIRED): The base path for the HTTP application which will be prepended to the routes of all components. (For example, ifbase = "/foo"
and a component hasroute = "/bar"
, the component will be invoked for requests on/foo/bar
.)
redis
: All components of the application are invoked as a result of messages being published on the queues of Redis instance. The Redis trigger configuration has the following fields:type
(REQUIRED): The application trigger type with the value"redis"
.address
(REQUIRED): The address of the Redis instance the components are using for message subscriptions.
variables
(OPTIONAL): Custom configuration variables.- A list of
component
objects (REQUIRED) defining the application components.
Component Configuration
Each component
object has the following fields:
id
(REQUIRED): unique (per application) ID of the component, used at runtime to select between multiple components of the same application.description
(OPTIONAL): Description of the component.source
(REQUIRED): Source for the WebAssembly module of the component. This field can be one the following:- a string with the path to a local file containing the WebAssembly module for the component; OR
- a pair of
reference
(REQUIRED) andparcel
(REQUIRED) fields pointing to a remote bindle package; OR - a pair of
url
(REQUIRED) anddigest
(REQUIRED) fields pointing to a Wasm file on the Web. Thedigest
must be in the formatsha256:...
and must match the content at the URL.
environment
(OPTIONAL): Environment variables to be made available inside the WebAssembly module at runtime.files
(OPTIONAL): Files to be made available inside the WebAssembly module at runtime. This is a list, each element of which is either:- a file path or glob relative to the
spin.toml
file (for examplefile.txt
, orcontent/static/**/*
) OR - a mapping of a
source
(REQUIRED), a directory relative tospin.toml
anddestination
(REQUIRED), the absolute mount path to be mapped inside the WebAssembly module. For example{ source = "content/", destination = "/"}
.
- a file path or glob relative to the
exclude_files
(OPTIONAL): List of file path or glob relative to thespin.toml
that don’t mount to wasm- When
exclude_files
conflict withfiles
config,exclude_files
take precedence
- When
allowed_http_hosts
(OPTIONAL): List of HTTP hosts the component is allowed to make HTTP requests totrigger
(REQUIRED): Trigger configuration for the component. Triggers are the components that generate events that cause the execution of components. The trigger configuration for a component must be compatible with the top-level trigger type of the application. As such, there are two possible trigger configurations for components, HTTP or Redis:http
: The configuration for an HTTP component. This has the following fields:route
(REQUIRED): The HTTP route the component will be invoked for. It can either be an exact route (for example/foo/test
), or it can contain a wildcard (/foo/test/...
) as the last path segment, which means the component will be invoked for every request starting with the/foo/test
prefix (for example/foo/test/abc/def
).executor
(REQUIRED): The executor for the HTTP component. There are currently two executortype
s:spin
(DEFAULT): the Spin HTTP executor, which uses the WebAssembly component model ORwagi
: the Wagi CGI executor, which can be used to write components in any language that compiles to WASI. The Wagi executor has the following optional fields:argv
(OPTIONAL): The string representation of theargv
list that should be passed into the handler.${SCRIPT_NAME}
will be replaced with the script name, and${ARGS}
will be replaced with the query parameters of the request, formatted as arguments. The default is to follow the CGI specification, and pass${SCRIPT_NAME} ${ARGS}
entrypoint
(OPTIONAL): The name of the function that should be called as the entry point to this handler. By default, it is_start
(which in most languages translates to callingmain
in the guest module).
redis
: The configuration for a Redis component. This has the following fields:channel
(REQUIRED): The Redis channel for which, whenever a new message is published, the component will be invoked.
config
(OPTIONAL): Custom configuration values.
Custom 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.
[variables]
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.
[[component]]
# ...
[component.config]
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_APP_
:
$ export SPIN_APP_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:
[[config_provider]]
type = "vault"
url = "http://127.0.0.1:8200"
token = "root"
mount = "secret"
Vault Config Provider Example
- Install Vault.
- Start Vault.
$ vault server -dev -dev-root-token-id root
- Set a password.
$ export VAULT_TOKEN=root
$ export VAULT_ADDR=http://127.0.0.1:8200
$ vault kv put secret/password value="test_password"
$ vault kv get secret/password
- Go to spin/tests/http/vault-config-test folder.
- Start
vault-config-test
app.
$ spin build
$ spin up --runtime-config-file runtime_config.toml
- Test the app.
$ curl -i http://127.0.0.1:3000
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.
Examples
- a Spin HTTP component that contains the files in
static/
mapped to/
:
[[component]]
source = "modules/spin_static_fs.wasm"
id = "fileserver"
files = [ { source = "static/", destination = "/" } ]
[component.trigger]
route = "/static/..."
- the same static file serving component, but getting the Wasm module from a public release instead of a local copy:
[[component]]
source = { url = "https://github.com/fermyon/spin-fileserver/releases/download/v0.0.1/spin_static_fs.wasm", digest = "sha256:650376c33a0756b1a52cad7ca670f1126391b79050df0321407da9c741d32375" }
id = "fileserver"
files = [ { source = "static/", destination = "/" } ]
[component.trigger]
route = "/static/..."
- a Wagi HTTP component that contains file mounts and sets the module
argv
and invokes a custom export function as the entry point:
[[component]]
source = "modules/env_wagi.wasm"
id = "env"
files = [ "content/**/*" , "templates/*", "scripts/*", "config/*"]
[component.trigger]
route = "/..."
executor = { type = "wagi", argv = "test ${SCRIPT_NAME} ${ARGS} done", entrypoint = "some-other-export-function" }
- a Redis component that is invoked for new messages on the
messages
channel:
[[component]]
id = "echo-message"
source = "spinredis.wasm"
[component.trigger]
channel = "messages"
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.