Skip to content

Start a worker from the registry (and upgrade it)

Goal: create a worker from the worker registry with its config and secret references, start it, and later load a newer version of its package in place.

Prerequisites

  • Signed in as an admin.
  • The target context is active; on a protected context each write asks first.
  • The registry entry is one the web app can create: it uses the virtufin server credential and a published package (entries with a personal credential or a local source are marked (not in the web app)).

Steps: create and start

  1. Open Infra > Workers (route /infra/workers).
  2. Press New… The dialog New worker from the registry opens.
  3. Pick the Worker (its description is shown) and the Version (newest first, (latest); the package URL is shown under it).
  4. Topics: comma-separated. Templates such as {pair} bind the config's comma-separated values; the line Subscribes to: … shows the resolved topics.
  5. Config: fill the form (required fields are marked *; enums and booleans are drop-downs). A world field (act or hyp.<NAME>) re-binds every world-scoped topic. Properties the form cannot offer are named (Not offered here …). Optional Reply topic for command replies.
  6. Secret references: the names of secrets in the cluster's worker Secret, never their values.
  7. Create. The worker is created tagged type and source, not started.
  8. Start it: select its row and press Start (protected context: confirm).

Steps: upgrade in place

  1. On Infra > Workers, the count line says N with a newer version when some can be upgraded.
  2. Select the worker and press Upgrade…. The dialog says which version runs and whether a newer one exists.
  3. Pick the Version ((running), (latest)) and press Load <version>.
  4. Several at once: mark them (checkbox, or Space on the selected row) — or mark none to use every worker the filter shows — and press Upgrade under Marked / All shown; confirm. Each loads its package's latest version; a report lists ✓/✗ per worker.

What you should see

  • The new worker's row, Status STOPPED, then LOADING and RUNNING after Start.
  • Detail (or Enter): its config, secret references, tags, code history and the lifecycle events since connecting.
  • After an upgrade the worker keeps its id, topics, config, secrets and tags; a running worker stops, loads the new code and starts again (its in-memory state starts fresh). The code history gets the new version.
  • Infra > Changes: one entry each for the create, the start (Start worker <name>) and the upgrade.

Troubleshooting

Symptom Cause and fix
Entry marked (not in the web app) / Cannot be created here: … It needs a personal credential or a local source: create it from the TUI or a notebook.
Create disabled A required config field is empty or invalid (the error is under it), a secret reference has bad characters (letters, digits, . _ -), or the topics do not resolve.
Status LOAD_FAILED The package could not be loaded: Detail → Last failure; Infra > Alerts has the failure too.
Upgrade… says nothing to load Its code is not a versioned registry package (inline or a custom URL).
Buttons disabled, read only You are not an admin.

More: Views > Workers.