Runners
Overview
A Runner is a resource that defines a target for Module job execution. One or more Runner Instances connect to a Runner to pick up and execute Jobs.
Runner
A Runner defines the configuration for job execution, including which Service Principal is used for authentication and whether the runner is available to all modules.
| Field | Description |
|---|---|
name |
Unique name of the Runner |
service_principal_id |
ID of the Service Principal used by Runner Instances to authenticate |
is_assigned_to_all_modules |
When true, any Module can use this Runner |
is_disabled |
When true, the Runner will not accept new Jobs |
allow_multiple_instances |
When true, multiple Runner Instances can connect simultaneously |
You can find the full Runner specification here.
Runner Instance
A Runner Instance is the actual worker process that executes Jobs. Each instance identifies itself with a Self Declared Runner Name when it connects.
- When
allow_multiple_instancesisfalse(default), only one instance can connect to the Runner at a time - When
allow_multiple_instancesistrue, multiple instances (e.g., a Kubernetes StatefulSet with multiple replicas) can connect simultaneously
Runner Instance Selection
When a Job starts, Snap CD must select a specific Runner Instance to execute all steps of that Job. There are two selection methods:
Automatic Selection (Default)
The Snap CD Server broadcasts a request to all connected instances. The first instance to respond is selected and handles all subsequent steps (init, plan, apply, etc.) for that Job.
Explicit Selection
You can set the runner_instance_name field on a Module to always use a specific Runner Instance. When set, requests go directly to that instance without broadcasting.
Allowing a Module to use a Runner
Before a Module can submit Jobs to a Runner, an assignment must exist. Assignments can be configured at different scopes:
| Method | Description |
|---|---|
is_assigned_to_all_modules on Runner |
Allows any Module to use this Runner |
| Runner Stack Assignment | All Modules within the Stack can use the Runner |
| Runner Namespace Assignment | All Modules within the Namespace can use the Runner |
| Runner Module Assignment | Only the specified Module can use the Runner |
Security Model
Runners execute Terraform/OpenTofu commands with the permissions granted to the underlying infrastructure (e.g., cloud credentials, Kubernetes service accounts). By restricting which Modules can use which Runners, you can enforce least-privilege access:
- Create Runners with narrowly scoped permissions
- Assign Runners only to Modules that require those specific permissions
- Use separate Runners for different environments (dev, staging, production)