Control plane and executors

Envoy separates orchestration from data processing. The control plane is the persistent application service; executors are workers that run task subprocesses.

Local mode

With local execution, the server starts task subprocesses on its own host:

executor:
  type: local

This topology is appropriate for development or a single trusted machine. The server and task processes share the same filesystem and network boundary.

HTTP mode

With HTTP execution, the server dispatches work to registered executors:

executor:
  type: http
  config:
    callback_url: http://control-plane:3000
    executor_key: ${ENVOY_EXECUTOR_KEY}

Start an executor with at least one control-plane URL:

envoy executor \
  --control-plane http://control-plane:3000 \
  --port 9090 \
  --max-concurrent 10 \
  --advertise-url http://envoy-executor:9090

ENVOY_CONTROL_PLANES may provide comma-separated control-plane URLs. The CLI also accepts repeated or comma-separated --control-plane values.

Authentication

Control-plane and executor requests use the shared executor key. This key is separate from:

• the application encryption key;
• user sessions;
• API keys;
• connector credentials.

Use one executor key for the control planes and executors intentionally participating in the same pool. Rotate it as a coordinated deployment change; mismatched values prevent registration and callbacks.

Advertised URL

The executor's advertised URL must be reachable from the control plane. Do not advertise:

• localhost when services are in different containers;
• a browser-facing public URL when internal service discovery is intended;
• a hostname that resolves only on the executor itself.

In Compose, advertise the executor service or container DNS name. In Azure Container Apps, use its internal application name or FQDN.

Capacity

--max-concurrent limits active tasks on one executor. It does not change per-step concurrency; those controls operate at different levels:

• executor concurrency bounds simultaneous task processes;
• server runs.max_concurrent bounds active runs managed by the control plane;
• step concurrency bounds simultaneous record operations inside one task.

Size all three against CPU, memory, destination rate limits, and database connection pools.

Labels

Executors can advertise labels:

envoy executor \
  --control-plane http://control-plane:3000 \
  --labels='{"region":"eu","workload":"migration"}'

Labels appear on the Executors page and are available to executor selection logic. Do not treat labels as an authorization boundary.

Heartbeats and leases

Executors register on startup and send heartbeats. Heartbeats report active tasks and renew run leases. The Executors page shows:

• URL;
• healthy or unhealthy status;
• active tasks and maximum capacity;
• labels;
• last heartbeat.

The page refreshes every five seconds in HTTP mode.

If an executor disappears, the run reaper eventually fails abandoned pending or running work. It does not silently mark the work successful.

Restart safety

Restarting an executor terminates its task subprocesses. Before an executor deployment:

1. inspect active runs in the health endpoint or UI;
2. wait for work to drain;
3. stop or cancel work only through an intentional operator action;
4. deploy the executor;
5. confirm it re-registers and resumes heartbeats.

The supplied remote deployment script refuses to restart an executor while active leases exist unless drain waiting is explicitly enabled.

Control-plane-only restarts are less disruptive to an HTTP executor, but status callbacks and heartbeats still require the server to return. Verify active runs after any restart.

Network placement

Executors need:

• inbound reachability from the control plane on the executor port;
• outbound reachability to data sources, destinations, and required APIs;
• access to shared file mounts referenced by connector paths;
• no public browser ingress in the standard topology.

The control plane needs database, secret-provider, identity-provider, and executor connectivity. It does not need the same broad data-plane egress when all connector work is delegated.

Unregistering

Admins can unregister an executor in the UI. This removes the current registry entry, but a live executor can register again on its next heartbeat. Stop or reconfigure the executor process if it should stay removed.