Overview
Runners are used by the Orchestrator to execute Terraform/OpenTofu modules securely inside your own infrastructure.
The Orchestrator will launch a runner to execute a deployment into a specific environment.
There are different runner types to support executing runners on specific kinds of compute, like Kubernetes clusters or serverless container runtimes. Each runner is configured to use a particular instance of such compute.
A runner is either launched by the Orchestrator itself if the target compute is reachable for it, or by an agent running in the target infrastructure and polling the Orchestrator for deployment events.
In addition, a runner uses a particular state storage to maintain Terraform/OpenTofu state in between invocations.
Basic example
This example creates a runner for execution on a GKE cluster and using a state storage in the runner namespace. It then creates a runner rule for that runner.
Runner config file gke-runner-config.yaml:
description: "GKE runner for my-cluster in europe-west3"
runner_configuration:
type: kubernetes-gke
cluster:
name: my-cluster
project_id: my-gcp-project
location: europe-west3
auth:
gcp_audience: //iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/my-wif-pool/providers/humanitec-runner
gcp_service_account: humanitec-orchestrator-runner@my-gcp-project.iam.gserviceaccount.com
job:
namespace: canyon-runner
service_account: canyon-runner
state_storage_configuration:
type: kubernetes
namespace: canyon-runner
Create a runner using this configuration:
# Create the runner
canyon create runner my-gke-runner [email protected]
# Create an empty rule that will always match
canyon create runner-rule --set=runner_id=my-gke-runner
Configuration
A runner configuration consists of these elements:
- A runner
id(supplied via the command line when using the CLI) - An optional
description - A
runner_configurationwith atypeand corresponding properties describing the infrastructure where to run - A
state_storage_configurationwith atypeand corresponding properties describing where to store state
The properties to set for the runner configuration and state storage configuration vary by their type. Refer to the individual sections for each runner type and state storage type to find the available configuration options and examples.
Runner types
Available runner types are:
State storage types
Available state storage types are:
Compatibilty matrix
Not all runner types can technically use every state storage type. The compatibility matrix shows the supported combinations.
| State storage type ➡️ Runner type ⬇️ |
kubernetes |
|---|---|
| kubernetes | ✅ |
| kubernetes-gke | ✅ |
Manage runners
Manage runners using the canyon CLI:
canyon create runner my-runner [email protected] # Create a new runner
canyon get runner my-runner # Get details on a runner
canyon list runners # List all runners of your organization
canyon update runner my-runner [email protected] # Update a runner with a runner config
canyon delete runner my-runner # Delete a runner
Runners and environments
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.
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.
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.
Runner agent
For each runner type, the Orchestrator will either launch runners itself or make use of an agent component to do so.
If the target compute for the runner execution is reachable for the Orchestrator, it can create a runner itself. This is true e.g. for runner types using a cloud-based service where the cloud API is publicly accessible, and shown as scenario (1) in the diagram below.
If the target compute for the runner execution is not reachable for the Orchestrator, the runner type comes with an agent which you install in your infrastructure. The agent creates an outbound, encrypted channel to the Orchestrator and continuously polls for deployment events. For each event, the agent launches a runner and relays the results back to the Orchestrator. This is shown as scenario (2) in the diagram below.
Runner image
A runner is based on a container image which is pulled from the public source ghcr.io/humanitec/canyon-runner by default, using one of the recent versions. The most current available version is 1.4.0.
The runner execution environment, e.g. a Kubernetes cluster, serverless runtime, or other compute, must be able to pull images from that source.
If you wish to pin the runner version or self-host the image in your own registry and have the runner pull from there, you can override the image for a runner by merging this pod_template snippet into your runner configuration:
Runner configuration for image override
This snippet shows how to configure the image source as well as related settings like imagePullPolicy and imagePullSecrets from the PodSpec . Omit them if not required.
The container name must be set exactly as shown.
runner_configuration:
job:
pod_template:
spec:
containers:
- name: canyon-runner
image: my-own-registry.com/humanitec/canyon-runner:vx.y.z
imagePullPolicy: IfNotPresent
imagePullSecrets:
- name: regcred
