kube_gha_runners
GHA Runners
This module provides deployments of self-hosted GHA runners that can be targeted in GHA workflows.
For installation instructions, see our guide.
Usage
Connecting the Runner to GitHub
Follow GitHub's documentation to provision a
Classic Personal Access Token (PAT) with the correct permissions. Provide this token
as an input via github_token.
For each runner,
set the github_config_url to the URL of your repository, organization, or enterprise. This is the entity
that the runners will belong to. We generally recommend making the runner available at the organization level
so that all of your organization's repositories can use the runner in their GHA workflows.
Referencing the Runner in a Workflow
The runner's name is the key that you use specify in the runners input:
inputs = {
runners = {
default = {
...
}
}
}
After you apply this module, you can specify which GHA workflow jobs will use the runner as follows:
jobs:
test:
runs-on: default
Reducing Startup Times
By default, this module does not provision any idle runners. As a result, when new workflow jobs are created, the jobs are delayed by 1-2 minutes as runners initialize.
For each runner, you can set min_replicas to a non-zero value to allow idle runners in your cluster. These
will be ready to receive new workflow jobs immediately and reduce your overall workflow runtimes.
However, these will also consume their full amount of allocated resources (CPU, memory, storage)
in the cluster while sitting idle.
Providers
The following providers are needed by this module:
-
helm (2.12.1)
-
kubectl (2.0.4)
-
kubernetes (2.27.0)
-
pf (0.0.3)
-
vault (3.25.0)
Required Inputs
The following input variables are required:
github_token
Description: The GitHub token that the runners will use to register with GitHub
Type: string
runners
Description: A mapping of runner names to their configuration values
Type:
map(object({
github_config_url = string # The url for the organization or repository that the runners will belong to
min_replicas = optional(number, 0)
max_replicas = optional(number, 25)
action_runner_image = optional(string)
action_runner_version = optional(string, "latest")
tmp_space_gb = optional(number, 1) # The number of GB of disk space to allocate to the runner
memory_mb = optional(number, 250) # The number of MB of memory to allocate to the runner
cpu_millicores = optional(number, 100) # The number of millicores of cpu to allocate to the runner
arm_nodes_enabled = optional(bool, true) # Whether to allow this runner to run on arm64 nodes
spot_nodes_enabled = optional(bool, true) # Whether to allow this runner to run on spot nodes
}))
Optional Inputs
The following input variables are optional (have default values):
extra_env_secrets
Description: A key-value mapping of extra secret environment variables for the runner pods
Type: map(string)
Default: {}
extra_pod_annotations
Description: Annotations to add to every runner pod
Type: map(string)
Default: {}
extra_pod_labels
Description: Labels to add to every runner pod
Type: map(string)
Default: {}
gha_runner_scale_set_helm_version
Description: The version of the actions-runner-controller-charts/gha-runner-scale-set helm chart to deploy
Type: string
Default: "0.9.3"
node_image_cache_enabled
Description: Whether to use kube-fledged to cache images locally for better startup performance
Type: bool
Default: true
panfactum_scheduler_enabled
Description: Whether to use the Panfactum pod scheduler with enhanced bin-packing
Type: bool
Default: true
pull_through_cache_enabled
Description: Whether to use the ECR pull through cache for the deployed images
Type: bool
Default: true
Outputs
No outputs.
Maintainer Notes
No notes.