Skip to content

Worker Secrets

A worker that needs credentials, such as an API key for an exchange, gets them by reference. CreateWorkerRequest.secrets maps an attribute name to a key of the deployment's worker secret:

{
  "mime_type": "application/x-dotnet-dll",
  "topics": ["x.myapp.handshake"],
  "config":  { "symbols": "BTC/USD,ETH/USD" },
  "secrets": { "alpacakey": "alpaca-paper-key", "alpacasecret": "alpaca-paper-secret" }
}

The worker reads the value like any config entry, as an extension attribute of the triggering CloudEvent: input["alpacakey"].

Why not config or tags?

Config and tags are fine for settings, but not for credentials:

  • ListWorkers returns them to every API-key holder.
  • The WorkManager stores them in plain text in its state store.
  • Tags can also be changed after creation, and filtered on.

With secrets, only the references (alpaca-paper-key) are stored and listed.

How it works

  1. CreateWorker validates the references and stores them with the worker. Values never reach the WorkManager.
  2. When the worker loads, the WorkManager Runtime reads the worker secret from its Dapr secret store and resolves every reference. If one is missing, the worker becomes LOAD_FAILED, and the load_failed event names the missing reference.
  3. On every trigger the Runtime stamps the values onto the CloudEvent, after the event's own attributes: a publisher cannot substitute a worker's credentials. The values are resolved per trigger (through the cache below), so a rotation shows on the next trigger after the cache expires.
  4. The Runtime drops the secret attributes from everything the worker returns, so a worker that hands its input back never publishes them.

Values are held in memory only, and refreshed every WORKER_SECRETS_TTL_SECONDS (60 by default), so a rotated secret reaches running workers within a minute. If the store is unreachable, the last values are kept.

Credentials used after Start

A worker gets its secrets twice over in its context (IWorkerContext):

Member What it is
Secrets The snapshot resolved when the worker started; it never changes during the activation.
GetSecretsAsync(ct) The secrets resolved now, through the Runtime's cache (at most WORKER_SECRETS_TTL_SECONDS old). Throws when a reference is no longer in the store (secret '<key>' not found, naming the key only).

A worker that holds a connection and logs in again on every reconnect (the WebSocketFeed's handshake=alpaca) calls GetSecretsAsync on every open, so a rotated Secret is used from the next reconnect without restarting the worker. Every value a worker was handed in the activation, the snapshot and each fresh one, stays refused by its State and stripped from its outputs. The Runtime logs Worker <id> resolved <n> worker secrets on request for each call (the count, never a value).

Hosts: the Runtime's in-process engines and the DotNetDll bridge (through the secrets host callback) resolve fresh. The C# source bridge, Python and native workers, and hosts without a resolver return the snapshot (the interface's default).

Rules

What Rule
Name A CloudEvent extension attribute name: 1-20 lower-case letters or digits
Name Not a reserved attribute (CloudEvents core attributes, correlationid, replytopic, publishtopic, traceparent, tracestate)
Name Not also a config key
Reference [A-Za-z0-9._-]{1,253}, the Kubernetes Secret key rules
Worker type Runtime-hosted types only (text/x-csharp, application/x-dotnet-dll, application/x-native-dll, text/x-python, application/x-python, text/x-typescript, application/x-npm)

A request that breaks a rule fails with INVALID_ARGUMENT. Secrets, like config, cannot be changed after creation: recreate the worker.

Limits

  • Every API-key holder can create a worker that references any key of the worker secret, and that worker can use or leak the value. Prefer low-privilege or expiring credentials.
  • A WebSocketFeed with handshake=alpaca computes the login inside the worker from its secrets (alpacakey, alpacasecret) on every open; the login never goes over pub/sub and is never stored. (The pub/sub handshake of the retired WebSocketManager and its AlpacaHandshake handler are gone.)

Setting up the store and managing the Secret: Manage worker secrets.