Skip to main content
Version: v2

Secrets and Configuration Management

wasmCloud components receive configuration through the localResources.environment field in a Workload or WorkloadDeployment manifest. This field supports three sources that can be used individually or combined: inline key-value pairs, Kubernetes ConfigMaps, and Kubernetes Secrets.

In this section of the Operator Manual, you'll learn how to:

  • Supply inline configuration to a component
  • Reference ConfigMaps and Secrets from a workload manifest
  • Combine multiple configuration sources

Inline configuration​

All values supplied through localResources.environment — regardless of source — are delivered to the component as POSIX-style environment variables via the wasi:cli/environment interface. Components read them the same way they would read any environment variable in their language of choice.

The simplest approach is to supply key-value pairs directly in the manifest under localResources.environment.config:

yaml
components:
  - name: http-component
    image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
    localResources:
      environment:
        config:
          LOG_LEVEL: info
          REGION: us-east-1

Inline values are suitable for non-sensitive configuration that is safe to store in version control.

ConfigMaps​

To supply configuration from a Kubernetes ConfigMap, reference it by name under configFrom:

yaml
components:
  - name: http-component
    image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
    localResources:
      environment:
        configFrom:
          - name: app-config

Each key-value pair in the referenced ConfigMap is delivered to the component as an environment variable. Multiple ConfigMaps may be listed; if the same key appears in more than one, the last entry in the list takes precedence.

Secrets​

To supply sensitive values from a Kubernetes Secret, reference it by name under secretFrom:

yaml
components:
  - name: http-component
    image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
    localResources:
      environment:
        secretFrom:
          - name: db-credentials

Secret values are delivered to the component as plain strings — no decoding is required in your component code. Multiple Secrets may be listed, and the last entry wins on key conflicts.

tip

The secretFrom field only accepts Secret names; values are never embedded in the manifest. Use Kubernetes RBAC to restrict which service accounts and users can read the referenced Secret resources.

Combining sources​

All three sources can be combined in a single component definition. When the same key appears in multiple sources, the order of precedence (lowest to highest) is: config → configFrom → secretFrom.

yaml
components:
  - name: http-component
    image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
    localResources:
      environment:
        config:
          LOG_LEVEL: debug
        configFrom:
          - name: app-config
        secretFrom:
          - name: db-credentials

All keys from app-config and db-credentials are merged with the inline values. Note that precedence is determined by source type, not by the order fields appear in the YAML: secretFrom always wins over configFrom, which always wins over config.

Complete example​

A WorkloadDeployment using all three configuration sources:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadDeployment
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 2
  template:
    spec:
      hostSelector:
        hostgroup: default
      components:
        - name: http-component
          image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
          localResources:
            environment:
              config:
                LOG_LEVEL: info          # inline values (lowest precedence)
              configFrom:
                - name: app-config       # non-sensitive config from a ConfigMap
              secretFrom:
                - name: db-credentials   # sensitive values from a Secret (highest precedence)
      hostInterfaces:
        - namespace: wasi
          package: http
          interfaces:
            - incoming-handler
          config:
            host: my-app.example.com

Secrets served by a host plugin​

Since 2.12.0 a secret can come from a host component plugin at bind time instead of a Kubernetes Secret. The operator declares the entry under runtime.hostGroups[].pluginSecrets and names it from a plugin entry's or binding's secretFrom; the plugin exports wasmcloud:host/secret-source and the host calls it on every granted workload bind.

Two things make this different from secretFrom on a workload:

  • The workload reads its secrets by key name; the operator decides which key names exist and who may have them. A workload manifest cannot name a pluginSecrets entry. The entry lists the key names it serves and the namespaces (and optionally the names) whose workloads may receive them; a workload outside the grant fails to deploy.
  • The host names the workload in every request, so one entry can serve each workload its own value when the source scopes its answer by that name. That is how a workload's own secrets reach it through the wasmcloud-secrets plugin with nothing per-workload in the host's configuration, and how each replica of a deployment can get its own database role.

A rotated value reaches the next bind. There is no volume to remount and no Reloader annotation involved, which is the practical reason to reach for it over a mounted Secret.

How the pieces fit together​

Take the workload-secrets entry from the Helm example, served by a vault-secrets plugin. The workload declares wasmcloud:secrets with no config of its own:

yaml
hostInterfaces:
  - namespace: wasmcloud
    package: secrets
    interfaces: [store, reveal]

and its code calls store.get("db-password"). When the host binds the workload, it:

  1. sees that the wasmcloud-secrets plugin entry names workload-secrets in its secretFrom;
  2. checks the workload's namespace and name against the entry's workloads grant;
  3. calls resolve on the vault-secrets plugin's secret-source export, passing the key db-password and the workload's namespace and name, and nothing the workload itself sent;
  4. hands the answer to wasmcloud-secrets as that workload's config, where store.get finds it.

The source decides where to look, for example a Vault path built from the namespace and name, so each workload gets its own value under the same key name. Three interfaces take part, and each has one job: the workload only ever sees wasmcloud:secrets; secret-source is exported by the source plugin and called only by the host; and a component plugin that consumes a secret on its binding reads it through binding-secrets instead of plain config.

What needs a host rollout​

The entry lives in the host group's Helm values, and changing those values rolls the host pods. Day-to-day secret changes do not touch them:

ChangeHost rollout?
Deploy a new workload that reads an existing key name, inside the grantNo
Rotate a value in the backendNo. It reaches each workload at its next bind
Add a key name to keys, or change the workloads grantYes
Change how the source plugin reaches its backend (its image, config, or allowedHosts in the Helm values)Yes

So pick key names that describe a role (db-password, api-token) rather than a single workload, and let the source plugin scope each answer by the workload it is told about.

Everything else on this page still applies to workload-level config, configFrom, and secretFrom, which remain the way a workload declares its own configuration.