Runner rules

Runner rules are attached to runners and define under which circumstances to use which runner.

Each environment will have exactly one runner linked to it at any time as a result of the runner rules. To create an environment you must have a runner which matches it.

The runner creates the link to the Terraform/OpenTofu state for that environment through its state storage configuration.

Orchestrator runners and configs

The environment remains linked to a runner even when the runner rules change until the refresh_runner API is called on the environment. This is because changing a runner may lead to dropping access to the previously used Terraform/OpenTofu state and thus a potentially undesired destruction of resources.

Basic example

Create an runner rule for the runner my-runner and the project my-project like this:

canyon create runner-rule --set=runner_id=my-runner --set=project_id=my-project

Manage runner rules

Manage runner rules using the canyon CLI:

# Create a runner rule
canyon create runner-rule --set=runner_id=my-runner --set=project_id=my-project

canyon list runner-rules                                       # List all runner rules of your organization
canyon get runner-rule 1f8a1ecd-2b06-41de-a646-34717b138582    # Get details on a runner rule
canyon delete runner-rule 1f8a1ecd-2b06-41de-a646-34717b138582 # Delete a runner rule

You cannot update a runner rule. Instead, delete the unwanted one and create a new runner rule with the desired configuration instead.

Runners will remain assigned to their environments even when the relevant runner rule has been deleted until you refresh the runner for an environment.

Configuration

A runner rule configuration consists of these elements:

  • The id of the runner where to attach the rule
  • An optional project_id to limit the runner to a specific project
  • An optional env_type_id to limit the runner to a specific environment type

Omitting both project_id and env_type_id creates an empty runner rule (“match anything”).

The Orchestrator will assign a runner rule a technical id in uuid format upon creation.

More than one runner rule can be attached to a runner.

There cannot be more than one runner rule with the same configuration.

Runner assignment to environments

A runner is assigned to an environment on environment creation or when the runner is refreshed. The most specific runner rule matching the environment determines the runner to be assigned.

Runner rules are evaluated from most to least specific in this order:

  1. A runner rule configured with project_id and env_type_id
  2. A runner rule configured with project_id only
  3. A runner rule configured with env_type_id only
  4. A runner rule with neither project_id nor env_type_id configured (“match anything”)

Example:

  • Runner rule configured for runner A with a project_id of my-project and an env_type_id of development
  • Runner rule configured for runner B with a project_id of my-project
  • New environment dev being created in project my-project with an environment type development

→ Runner A will be assigned because both runner rules match, but the first one is more specific.

Refresh the runner for an environment

An environment remains linked to a runner even when the runner rules change. Execute the refresh_runner command on the environment to re-assign a runner based on the current runner rules.

Use the dry_run flag to test the result of the command without applying any change.

If a runner could be identified for the environment, the command will return that runner’s id.

If no runner could be identified, the command will return an error.

Overview