Skip to main content
Version: 1.x

Configure

Capability providers can be passed a map of configuration at runtime to use when executing. This configuration should first be defined using wash or as a part of your wadm manifest, and then given to the capability provider at runtime.

Define Configuration​

If you're using wadm to declaratively define applications, you can use the config field to define configuration for your provider. Wadm will automatically manage creating the configuration for you and supplying it to the provider at runtime.

yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: hello-world
  annotations:
    version: v0.0.1
    description: 'Capability provider that uses wasi:http and runtime configuration'
spec:
  components:
    - name: http-server
      type: capability
      properties:
        image: file://./build/http-server.par.gz
        config: 
          - name: custom-config
            properties: 
              foo: bar
              log-level: debug
      traits:
        # Govern the spread/scheduling of the component
        - type: spreadscaler
          properties:
            instances: 1

Using Configuration​

Capability providers are given configuration at startup and as a part of each link. You can use the

The HostData contains configuration for the provider at startup:

rust
pub async fn run() -> anyhow::Result<()> {
    initialize_observability!(
        "my-provider",
        std::env::var_os("FLAMEGRAPH_PATH")
    );

    let host_data = load_host_data().context("failed to load host data")?;
    let config = host_data.config;
    let my_provider = MyProvider::new(config)
        .context("failed to create provider from hostdata configuration")?;
    let shutdown = run_provider(my_provider, "my-provider")
        .await
        .context("failed to run provider")?;
    shutdown.await;
    Ok(())
}

The functions on the Provider trait in the SDK allow for handling links and fetching the configuration when it's established:

rust
impl Provider for MyProvider {
  async fn receive_link_config_as_source(
    &self,
    link: LinkConfig<'_>,
  ) -> anyhow::Result<()> {
    let config = link.config;
    Ok(())
  }

  async fn receive_link_config_as_target(
    &self,
    link: LinkConfig<'_>,
  ) -> anyhow::Result<()> {
    let config = link.config;
    Ok(())
  }
}

Supplying multiple configurations​

In both the above wadm and wash methods of defining configuration, you can actually supply multiple named configurations to components, providers, and links. This is useful both to reuse common pieces of configuration and provide overrides for specific instances.

Let's a case where we have a set of reasonable defaults for connections to a database that we want multiple components to use, but we also want to be able to override the connection string for specific instances. This can be accomplished by defining the default configuration and then overriding it for specific instances.

We'll use the wasmCloud HTTP Server settings as an example. We'll link the HTTP server to a component, supplying a default configuration with reasonable values and an additional configuration to change the address for that specific component. To create the default configuration, we can use the wash config put command:

bash
wash config put default-http max_content_len=5M readonly_mode=true address=0.0.0.0:80

By default, we'll limit the max content length to 5MB and ensure that components are only accepting GET and HEAD requests using the readonly_mode configuration. We'll also supply a default listen address of 0.0.0.0:80.

For our component, we can use the default configuration by supplying the default-http configuration name, and then override the address configuration for this specific instance:

yaml
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: hello-world
  annotations:
    version: v0.0.1
    description: 'Component that uses wasi:http'
spec:
  components:
    - name: http-component
      type: component
      properties:
        image: file://./build/http_hello_world_s.wasm
      traits:
        # Govern the spread/scheduling of the component
        - type: spreadscaler
          properties:
            instances: 1
    # Add a capability provider that enables HTTP access
    - name: httpserver
      type: capability
      properties:
        image: ghcr.io/wasmcloud/http-server:0.22.0
      traits:
        - type: link
          properties:
          target: http-component
          namespace: wasi
          package: http
          interfaces: [incoming-handler]
          source_config:
            - name: default-http
            - name: custom-config
              properties: 
                address: 0.0.0.0:4000

Configuration is merged together in a left-folding manner, meaning that the last configuration supplied will override any previous configurations. In the above example, the address configuration will be overridden to 0.0.0.0:4000, but the max_content_len and readonly_mode configurations will remain the same as the default configuration. Put another way, the configuration this provider will receive with the link is:

json
{
  "max_content_len": "5M",
  "readonly_mode": true,
  "address": "0.0.0:4000"
}