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:
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-1Inline 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:
components:
- name: http-component
image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
localResources:
environment:
configFrom:
- name: app-configEach 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:
components:
- name: http-component
image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
localResources:
environment:
secretFrom:
- name: db-credentialsSecret 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.
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.
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-credentialsAll 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:
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.comSecrets 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
pluginSecretsentry. 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-secretsplugin 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:
hostInterfaces:
- namespace: wasmcloud
package: secrets
interfaces: [store, reveal]and its code calls store.get("db-password"). When the host binds the workload, it:
- sees that the
wasmcloud-secretsplugin entry namesworkload-secretsin itssecretFrom; - checks the workload's namespace and name against the entry's
workloadsgrant; - calls
resolveon thevault-secretsplugin'ssecret-sourceexport, passing the keydb-passwordand the workload's namespace and name, and nothing the workload itself sent; - hands the answer to
wasmcloud-secretsas that workload's config, wherestore.getfinds 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:
| Change | Host rollout? |
|---|---|
| Deploy a new workload that reads an existing key name, inside the grant | No |
| Rotate a value in the backend | No. It reaches each workload at its next bind |
Add a key name to keys, or change the workloads grant | Yes |
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.
Related documentation
- Custom Resource Definitions — field reference for
localResources,hostInterfaces(including backend config andallowedHosts), and other CRD fields - Roles and Role Bindings — RBAC configuration for the operator and host pods
- Filesystems and Volumes — mounting volume data into components via
localResources.volumeMounts - Private Registries — managing image pull secrets for private OCI registries