Component Configuration and Secrets

Wasm components running on Cosmonic Control receive configuration and secrets through fields on the HTTPTrigger or WorkloadDeployment manifest. Values are delivered to the component via the wasi:config interface and read at runtime.

This page covers all configuration mechanisms available to a component: inline key-value pairs, references to Kubernetes ConfigMaps and Secrets, outbound network allowlisting, and private OCI registries for component images.

Inline configuration

Pass static key-value pairs directly in the manifest using localResources.environment.config:

apiVersion: control.cosmonic.io/v1alpha1
kind: HTTPTrigger
metadata:
  name: my-app
  namespace: default
spec:
  replicas: 1
  ingress:
    host: my-app.localhost.cosmonic.sh
    paths:
      - path: /
        pathType: Prefix
  template:
    spec:
      components:
        - name: app
          image: ghcr.io/my-org/my-app:1.0.0
          localResources:
            environment:
              config:
                LOG_LEVEL: info
                CACHE_TTL: "300"
                FEATURE_FLAG_DARK_MODE: "true"

Keys and values are arbitrary strings. The component reads them at runtime via wasi:config/runtime.

Configuration from a ConfigMap

Reference a Kubernetes ConfigMap to supply configuration without embedding it in the manifest. All keys in the ConfigMap are merged into the component's configuration:

kubectl create configmap my-app-config \
  --from-literal=LOG_LEVEL=info \
  --from-literal=CACHE_TTL=300 \
  -n default

spec:
  template:
    spec:
      components:
        - name: app
          image: ghcr.io/my-org/my-app:1.0.0
          localResources:
            environment:
              configFrom:
                - name: my-app-config

Multiple ConfigMaps may be listed. If the same key appears in more than one, the last entry in the list wins.

You can combine configFrom with inline config. Inline values are merged alongside the referenced ConfigMaps. In case of key conflicts, the last source in declaration order wins:

localResources:
  environment:
    config:
      FEATURE_FLAG_DARK_MODE: "true"   # inline override
    configFrom:
      - name: my-app-config            # base config from ConfigMap
      - name: my-app-config-overrides  # additional overrides

Secrets

Reference a Kubernetes Secret to inject sensitive values. Secret values are base64-decoded and UTF-8 decoded before being delivered to the component:

kubectl create secret generic my-app-secrets \
  --from-literal=DATABASE_URL=postgres://user:password@db.internal:5432/mydb \
  --from-literal=API_KEY=supersecretkey \
  -n default

spec:
  template:
    spec:
      components:
        - name: app
          image: ghcr.io/my-org/my-app:1.0.0
          localResources:
            environment:
              secretFrom:
                - name: my-app-secrets

Multiple Secrets may be listed. If the same key appears in more than one, the last entry takes precedence.

configFrom and secretFrom may be combined freely. All referenced ConfigMaps and Secrets are merged into a single flat key-value map delivered to the component:

localResources:
  environment:
    config:
      LOG_LEVEL: info
    configFrom:
      - name: my-app-config
    secretFrom:
      - name: my-app-secrets

note

The operator service account has get, list, and watch access to Secrets cluster-wide by default (see Kubernetes RBAC). Ensure your namespace RBAC restricts which tenants can create or read Secrets in each namespace.

Host interface configuration

Some host interfaces require their own configuration — for example, an outbound HTTP interface that needs a base URL, or a blobstore interface that needs a bucket name. These are separate from component configuration and are passed to the capability layer via hostInterfaces[].config:

spec:
  template:
    spec:
      components:
        - name: app
          image: ghcr.io/my-org/my-app:1.0.0
      hostInterfaces:
        - namespace: wasi
          package: blobstore
          version: 0.2.0-draft
          interfaces:
            - blobstore
          config:
            bucket: my-bucket
          secretFrom:
            - name: blobstore-credentials

hostInterfaces supports the same config, configFrom, and secretFrom fields as component localResources.

Outbound network access

By default, Wasm components have no outbound network access. Use allowedHosts to explicitly permit outbound HTTP calls to specific hosts:

localResources:
  allowedHosts:
    - https://api.example.com
    - https://auth.example.com

Calls to any host not in allowedHosts will be denied at the runtime level. Use the most specific URLs you can — preferring https://api.example.com over https://*.

note

allowedHosts controls outbound HTTP access from within the component (via wasi:http/outgoing-handler). It does not affect inbound traffic, which is controlled by the HTTPTrigger ingress configuration.

Private component registries

If your component image is in a private OCI registry, create a docker-registry pull secret and reference it on the component spec:

kubectl create secret docker-registry component-pull-secret \
  --docker-server=my-registry.corp.com \
  --docker-username=<username> \
  --docker-password=<password> \
  -n default

spec:
  template:
    spec:
      components:
        - name: app
          image: my-registry.corp.com/my-org/my-app:1.0.0
          imagePullSecret:
            name: component-pull-secret

Each component in a workload can reference a different pull secret if images come from different registries.

note

This secret is per-component, not per-HostGroup pod. The HostGroup itself does not need access to your application component registries — only the operator does, to resolve and distribute the component image.

Reference

All configuration fields are available under spec.template.spec.components[].localResources on both HTTPTrigger and WorkloadDeployment:

Field	Type	Description
localResources.environment.config	map[string]string	Inline key-value configuration delivered to the component
localResources.environment.configFrom	[]LocalObjectReference	References to ConfigMaps; all keys are merged
localResources.environment.secretFrom	[]LocalObjectReference	References to Secrets; values are base64+UTF-8 decoded
localResources.allowedHosts	[]string	Allowlist of outbound HTTP hosts
imagePullSecret	LocalObjectReference	Pull secret for the component's OCI image
hostInterfaces[].config	map[string]string	Inline config for a host interface
hostInterfaces[].configFrom	[]LocalObjectReference	ConfigMap references for a host interface
hostInterfaces[].secretFrom	[]LocalObjectReference	Secret references for a host interface