Create, Run, and Manage Workers

A Worker is two things in ConfigHub, and most Workers are only the first: an identity that automation authenticates as, and — optionally — a process you run to execute custom functions.

You do not need a running Worker to deploy configuration. Deployment happens by publishing a Release that a GitOps operator pulls; nothing is pushed from ConfigHub into your infrastructure.

Create a Worker

Creating a Worker registers it with ConfigHub and creates an identity and a secret for it.

cub worker create --space platform-dev deploy-bot

You can also create one via the UI (click Add on the workers page). You should then see it in the worker list:

cub worker list --space "*"

Use a Worker as a service identity

This is the common case, and it needs no running process. Fetch the credentials and hand them to whatever needs to talk to ConfigHub — a CI job, an event consumer, a script, or any API client:

eval "$(cub worker get-envs --space platform-dev deploy-bot)"

This sets CONFIGHUB_WORKER_ID and CONFIGHUB_WORKER_SECRET. A client exchanges them for a standard authentication token:

cub auth login --as-worker

Because the Worker is a first-class entity with its own permissions, you can scope its access to exactly what the automation needs, and its actions are attributed to it rather than to whoever created it.

Server workers (--is-server-worker) are hosted inside ConfigHub rather than run by you. These back Targets with ProviderType OCI — the mechanism that publishes configuration to the OCI endpoint. cub cluster up creates one for you; to create one by hand:

cub worker create --space platform-dev --is-server-worker --allow-exists server-worker

Run a Worker to execute custom functions

The only reason to run a Worker process is to execute functions you have written yourself. The function runs in your environment, with your credentials and network access; ConfigHub routes the call to the Worker and receives the result back.

To run our default worker build in a cluster, use cub worker install:

cub worker install cluster-worker --space platform-dev --export --include-secret | kubectl apply -f -

By default cub worker install --export doesn't output the secret. Use --include-secret to include it with the rest of the configuration, or --export-secret-only to output it separately so you can manage it with your secret management solution of choice, such as the external secrets operator.

The worker image is pinned to the latest release by default. To upgrade:

cub worker upgrade --filename worker.yaml

You can also store the worker's own configuration in ConfigHub as a unit and deploy it like anything else, with cub worker install --unit <name>. You still need to bootstrap the worker in the cluster initially:

cub worker install --space platform-dev cluster-worker --unit cluster-worker
cub unit data --space platform-dev cluster-worker | kubectl apply -f -
cub worker install --space platform-dev cluster-worker --export-secret-only | kubectl apply -f -

Once it is in a unit you can modify it with functions like any other configuration — set-image, set-env-var, set-container-resources, set-pod-defaults, and vet-schemas are all useful here — and roll out changes by publishing a Release for its space.

For running custom-built worker executables, locally or in a cluster, see custom function workers.

Use custom functions in triggers

Once a Worker is running and advertising its functions, you can invoke them imperatively or register them as triggers:

cub trigger create --space app-dev --worker platform-dev/cluster-worker custom-check Mutation Kubernetes/YAML my-custom-function

See validating configuration and enforcing policies for the full trigger workflow, including what happens when a worker is unavailable.

Manage

ConfigHub reports the connection status of a running Worker. The condition should be Ready if it is responding to invocations and heartbeat messages. It will be Connected just after it first connects, Disconnected if it is not connected, Unresponsive if it is connected but not responding to heartbeats, and NotReady if it responds to a heartbeat with an error.

% cub worker list --space "*"
NAME              CONDITION    SPACE            LAST-SEEN
cluster-worker    Ready        platform-prod    2025-10-23 22:05:44
cluster-worker    Ready        platform-dev     2025-10-23 22:05:33

If a worker has been in a condition other than Ready for long enough, invocations directed at it will start to fail immediately and triggers dependent on it will be automatically disabled.

A Worker used only as a service identity has no connection to report.

Delete a Worker

If you no longer need a worker and it is no longer running, you can delete it. Deleting a worker deletes any targets associated with it and removes them from units they are attached to.

You won't be able to delete a worker in use by triggers without first deleting those triggers or updating them to not use the worker.

cub worker delete --space platform-dev cluster-worker

Replicas and high availability

ConfigHub supports running multiple Worker instances with identical credentials to ensure continuous operation. When Workers connect using the same worker_id and secret, the system automatically manages active and standby connections for seamless failover.

The default configuration generated by cub worker install runs one replica in the active state, but sets maxSurge to 1 and maxUnavailable to 0 so that an additional replica is created before the running one is terminated.

First connection (active). The first Worker to connect becomes the active connection immediately and processes all operations.

Subsequent connections (standby). Additional Workers connecting with the same credentials register as standby connections and wait, ready to take over. ConfigHub sends keepalive messages to standby Workers every 30 seconds to maintain the connection. Workers log these and discard them. Keepalives are distinct from heartbeats, which Workers send to ConfigHub to report health.

Failover. When the active connection disconnects, ConfigHub detects the failure, removes the disconnected Worker from active management, checks the health of remaining standbys, and promotes the first healthy one. The newly active Worker re-queues any operations that were in flight to the previous active Worker but not yet completed, and begins processing immediately.