Deploying a runner scale set

To deploy a runner scale set, you must have ARC up and running. For more information, seeQuickstart for Actions Runner Controller.

You can deploy runner scale sets with ARC's Helm charts or by deploying the necessary manifests. Using ARC's Helm charts is the preferred method, especially if you do not have prior experience using ARC.

1. To configure your runner scale set, run the following command in your terminal, using values from your ARC configuration.

   When you run the command, keep the following in mind.

   • Update theINSTALLATION_NAME value carefully. You will use the installation name as the value ofruns-on in your workflows.

   • Update theNAMESPACE value to the location you want the runner pods to be created.

   • Set theGITHUB_CONFIG_URL value to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to.

   • This example command installs the latest version of the Helm chart. To install a specific version, you can pass the--version argument with the version of the chart you want to install. You can find the list of releases in theactions-runner-controller repository.

     Bash

     INSTALLATION_NAME="arc-runner-set"NAMESPACE="arc-runners"GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>"GITHUB_PAT="<PAT>"helm install"${INSTALLATION_NAME}" \    --namespace"${NAMESPACE}" \    --create-namespace \    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \    --set githubConfigSecret.github_token="${GITHUB_PAT}" \    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

     For additional Helm configuration options, seevalues.yaml in the ARC repository.

2. To check your installation, run the following command in your terminal.

   Bash

   helm list -A

   You should see an output similar to the following.

   NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSIONarc             arc-systems     1               2023-04-12 11:45:59.152090536 +0000 UTC deployed        gha-runner-scale-set-controller-0.4.0       0.4.0arc-runner-set  arc-systems     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0

3. To check the manager pod, run the following command in your terminal.

   Bash

   kubectl get pods -n arc-systems

   If the installation was successful, the pods will show theRunning status.

   NAME                                                   READY   STATUS    RESTARTS   AGEarc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64sarc-runner-set-754b578d-listener                       1/1     Running   0          12s

If your installation was not successful, seeTroubleshooting Actions Runner Controller errors for troubleshooting information.

Using advanced configuration options

ARC offers several advanced configuration options.

Configuring the runner scale set name

To configure the runner scale set name, you can define anINSTALLATION_NAME or set the value ofrunnerScaleSetName in your copy of thevalues.yaml file.

## The name of the runner scale set to create, which defaults to the Helm release namerunnerScaleSetName:"my-runners"

Make sure to pass thevalues.yaml file in yourhelm install command. See theHelm Install documentation for more details.

Choosing runner destinations

Runner scale sets can be deployed at the repository, organization, or enterprise levels.

To deploy runner scale sets to a specific level, set the value ofgithubConfigUrl in your copy of thevalues.yaml to the URL of your repository, organization, or enterprise.

The following example shows how to configure ARC to add runners toocto-org/octo-repo.

githubConfigUrl:"https://github.com/octo-ent/octo-org/octo-repo"

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Using a GitHub App for authentication

If you are not using enterprise-level runners, you can use GitHub Apps to authenticate with the GitHub API. For more information, seeAuthenticating ARC to the GitHub API.

You can either create a Kubernetes secret, or specify values in yourvalues.yaml file.

Option 1: Create a Kubernetes secret (recommended)

Once you have created your GitHub App, create a Kubernetes secret and pass the reference to that secret in your copy of thevalues.yaml file.

kubectl create secret generic pre-defined-secret \  --namespace=arc-runners \  --from-literal=github_app_id=123456 \  --from-literal=github_app_installation_id=654321 \  --from-file=github_app_private_key=private-key.pem

In your copy of thevalues.yaml pass the secret name as a reference.

githubConfigSecret:pre-defined-secret

Option 2: Specify values in yourvalues.yaml file

Alternatively, you can specify the values ofapp_id,installation_id andprivate_key in your copy of thevalues.yaml file.

## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.## You can choose to use a GitHub App or a personal access token (classic)githubConfigSecret:## GitHub Apps Configuration## IDs must be strings, use quotesgithub_app_id:"123456"github_app_installation_id:"654321"github_app_private_key:|    -----BEGIN RSA PRIVATE KEY-----    ...    HkVN9...    ...    -----END RSA PRIVATE KEY-----

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Managing access with runner groups

You can use runner groups to control which organizations or repositories have access to your runner scale sets. For more information on runner groups, seeManaging access to self-hosted runners using groups.

To add a runner scale set to a runner group, you must already have a runner group created. Then set therunnerGroup property in your copy of thevalues.yaml file. The following example adds a runner scale set to the Octo-Group runner group.

runnerGroup:"Octo-Group"

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Configuring an outbound proxy

To force HTTP traffic for the controller and runners to go through your outbound proxy, set the following properties in your Helm chart.

proxy:http:url:http://proxy.com:1234credentialSecretRef:proxy-auth# a Kubernetes secret with `username` and `password` keyshttps:url:http://proxy.com:1234credentialSecretRef:proxy-auth# a Kubernetes secret with `username` and `password` keysnoProxy:-example.com-example.org

ARC supports using anonymous or authenticated proxies. If you use authenticated proxies, you will need to set thecredentialSecretRef value to reference a Kubernetes secret. You can create a secret with your proxy credentials with the following command.

  kubectl create secret generic proxy-auth \    --namespace=arc-runners \    --from-literal=username=proxyUsername \    --from-literal=password=proxyPassword \

  kubectl create secret generic proxy-auth \    --namespace=arc-runners \    --from-literal=username=proxyUsername \    --from-literal=password=proxyPassword \

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Setting the maximum and minimum number of runners

ThemaxRunners andminRunners properties provide you with a range of options to customize your ARC setup.

Example: Unbounded number of runners

If you comment out both themaxRunners andminRunners properties, ARC will scale up to the number of jobs assigned to the runner scale set and will scale down to 0 if there aren't any active jobs.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.# maxRunners: 0## minRunners is the min number of idle runners. The target number of runners created will be## calculated as a sum of minRunners and the number of jobs assigned to the scale set.# minRunners: 0

Example: Minimum number of runners

You can set theminRunners property to any number and ARC will make sure there is always the specified number of runners active and available to take jobs assigned to the runner scale set at all times.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.# maxRunners: 0## minRunners is the min number of idle runners. The target number of runners created will be## calculated as a sum of minRunners and the number of jobs assigned to the scale set.minRunners:20

Example: Set maximum and minimum number of runners

In this configuration, Actions Runner Controller will scale up to a maximum of30 runners and will scale down to20 runners when the jobs are complete.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.maxRunners:30## minRunners is the min number of idle runners. The target number of runners created will be## calculated as a sum of minRunners and the number of jobs assigned to the scale set.minRunners:20

Example: Jobs queue draining

In certain scenarios you might want to drain the jobs queue to troubleshoot a problem or to perform maintenance on your cluster. If you set both properties to0, Actions Runner Controller will not create new runner pods when new jobs are available and assigned.

## maxRunners is the max number of runners the auto scaling runner set will scale up to.maxRunners:0## minRunners is the min number of idle runners. The target number of runners created will be## calculated as a sum of minRunners and the number of jobs assigned to the scale set.minRunners:0

Custom TLS certificates

Some environments require TLS certificates that are signed by a custom certificate authority (CA). Since the custom certificate authority certificates are not bundled with the controller or runner containers, you must inject them into their respective trust stores.

githubServerTLS:certificateFrom:configMapKeyRef:name:config-map-namekey:ca.crtrunnerMountPath:/usr/local/share/ca-certificates/

When you do this, ensure you are using the Privacy Enhanced Mail (PEM) format and that the extension of your certificate is.crt. Anything else will be ignored.

The controller executes the following actions.

• Creates agithub-server-tls-cert volume containing the certificate specified incertificateFrom.
• Mounts that volume on pathrunnerMountPath/<certificate name>.
• Sets theNODE_EXTRA_CA_CERTS environment variable to that same path.
• Sets theRUNNER_UPDATE_CA_CERTS environment variable to1 (as of version2.303.0, this will instruct the runner to reload certificates on the host).

ARC observes values set in the runner pod template and does not overwrite them.

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Using a private container registry

To use a private container registry, you can copy the controller image and runner image to your private container registry. Then configure the links to those images and set theimagePullPolicy andimagePullSecrets values.

Configuring the controller image

You can update your copy of thevalues.yaml file and set theimage properties as follows.

image:repository:"custom-registry.io/gha-runner-scale-set-controller"pullPolicy:IfNotPresent# Overrides the image tag whose default is the chart appVersion.tag:"0.4.0"imagePullSecrets:-name:<registry-secret-name>

The listener container inherits theimagePullPolicy defined for the controller.

Configuring the runner image

You can update your copy of thevalues.yaml file and set thetemplate.spec properties to configure the runner pod for your specific use case.

The following is a sample configuration:

template:spec:containers:-name:runnerimage:"custom-registry.io/actions-runner:latest"imagePullPolicy:Alwayscommand: ["/home/runner/run.sh"]imagePullSecrets:-name:<registry-secret-name>

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Updating the pod specification for the runner pod

You can fully customize the PodSpec of the runner pod and the controller will apply the configuration you specify. The following is an example pod specification.

template:spec:containers:-name:runnerimage:ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]resources:limits:cpu:500mmemory:512MisecurityContext:readOnlyRootFilesystem:trueallowPrivilegeEscalation:falsecapabilities:add:-NET_ADMIN

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Updating the pod specification for the listener pod

You can customize the PodSpec of the listener pod and the controller will apply the configuration you specify. The following is an example pod specification.

listenerTemplate:spec:containers:# If you change the name of the container, the configuration will not be applied to the listener,# and it will be treated as a sidecar container.-name:listenersecurityContext:runAsUser:1000resources:limits:cpu:"1"memory:1Girequests:cpu:"1"memory:1Gi

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Using Docker-in-Docker or Kubernetes mode for containers

If you are using container jobs and services or container actions, you must set thecontainerMode value todind orkubernetes. To use a custom container mode, comment out or removecontainerMode, and add your desired configuration to thetemplate section. SeeCustomizing container modes.

• For more information on container jobs and services, seeRunning jobs in a container.
• For more information on container actions, seeCreating a Docker container action.

Using Docker-in-Docker mode

Docker-in-Docker mode is a configuration that allows you to run Docker inside a Docker container. In this configuration, for each runner pod created, ARC creates the following containers.

• Aninit container
• Arunner container
• Adind container

To enable Docker-in-Docker mode, set thecontainerMode.type todind as follows.

containerMode:type:"dind"

Thetemplate.spec will be updated to the following default configuration.

For versions of Kubernetes>= v1.29, sidecar container will be used to run docker daemon.

template:spec:initContainers:-name:init-dind-externalsimage:ghcr.io/actions/actions-runner:latestcommand: ["cp","-r","/home/runner/externals/.","/home/runner/tmpDir/"]volumeMounts:-name:dind-externalsmountPath:/home/runner/tmpDir-name:dindimage:docker:dindargs:-dockerd---host=unix:///var/run/docker.sock---group=$(DOCKER_GROUP_GID)env:-name:DOCKER_GROUP_GIDvalue:"123"securityContext:privileged:truerestartPolicy:AlwaysstartupProbe:exec:command:-docker-infoinitialDelaySeconds:0failureThreshold:24periodSeconds:5volumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/var/run-name:dind-externalsmountPath:/home/runner/externalscontainers:-name:runnerimage:ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]env:-name:DOCKER_HOSTvalue:unix:///var/run/docker.sock-name:RUNNER_WAIT_FOR_DOCKER_IN_SECONDSvalue:"120"volumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/var/runvolumes:-name:workemptyDir: {}-name:dind-sockemptyDir: {}-name:dind-externalsemptyDir: {}

For versions of Kubernetes< v1.29, the following configuration will be applied:

template:spec:initContainers:-name:init-dind-externalsimage:ghcr.io/actions/actions-runner:latestcommand:          ["cp","-r","/home/runner/externals/.","/home/runner/tmpDir/"]volumeMounts:-name:dind-externalsmountPath:/home/runner/tmpDircontainers:-name:runnerimage:ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]env:-name:DOCKER_HOSTvalue:unix:///var/run/docker.sockvolumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/var/run-name:dindimage:docker:dindargs:-dockerd---host=unix:///var/run/docker.sock---group=$(DOCKER_GROUP_GID)env:-name:DOCKER_GROUP_GIDvalue:"123"securityContext:privileged:truevolumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/var/run-name:dind-externalsmountPath:/home/runner/externalsvolumes:-name:workemptyDir: {}-name:dind-sockemptyDir: {}-name:dind-externalsemptyDir: {}

The values intemplate.spec are automatically injected and cannot be overridden. If you want to customize this setup, you must unsetcontainerMode.type, then copy this configuration and apply it directly in your copy of thevalues.yaml file.

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Using Kubernetes mode

In Kubernetes mode, ARC uses runner container hooks to create a new pod in the same namespace to run the service, container job, or action.

Prerequisites

Kubernetes mode relies on persistent volumes to share job details between the runner pod and the container job pod. For more information, see thePersistent Volumes section in the Kubernetes documentation.

To use Kubernetes mode, you must do the following.

• Create persistent volumes available for the runner pods to claim.
• Use a solution to automatically provision persistent volumes on demand.

For testing, you can use a solution likeOpenEBS.

Configuring Kubernetes mode

To enable Kubernetes mode, set thecontainerMode.type tokubernetes in yourvalues.yaml file.

containerMode:type:"kubernetes"kubernetesModeWorkVolumeClaim:accessModes: ["ReadWriteOnce"]storageClassName:"dynamic-blob-storage"resources:requests:storage:1Gi

For additional Helm configuration options, seevalues.yaml in the ARC repository.

Jobs without a job container are forbidden on this runner, please add a'container:' to your job or contact your self-hosted runner administrator.

template:spec:containers:-name:runnerimage:ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]env:-name:ACTIONS_RUNNER_REQUIRE_JOB_CONTAINERvalue:"false"

Customizing container modes

When you set thecontainerMode in thevalues.yaml file for thegha-runner-scale-set helm chart, you can use either of the following values:

• dind or
• kubernetes

Depending on which value you set for thecontainerMode, a configuration will automatically be injected into thetemplate section of thevalues.yaml file for thegha-runner-scale-set helm chart.

• See thedind configuration.
• See thekubernetes configuration.

To customize the spec, comment out or removecontainerMode, and append the configuration you want in thetemplate section.

Example: runningdind-rootless

Before deciding to rundind-rootless, make sure you are aware ofknown limitations.

For versions of Kubernetes >= v1.29, sidecar container will be used to run docker daemon.

## githubConfigUrl is the GitHub url for where you want to configure runners## ex: https://github.com/myorg/myrepo or https://github.com/myorggithubConfigUrl:"https://github.com/actions/actions-runner-controller"## githubConfigSecret is the k8s secrets to use when auth with GitHub API.## You can choose to use GitHub App or a PAT tokengithubConfigSecret:my-super-safe-secret## maxRunners is the max number of runners the autoscaling runner set will scale up to.maxRunners:5## minRunners is the min number of idle runners. The target number of runners created will be## calculated as a sum of minRunners and the number of jobs assigned to the scale set.minRunners:0runnerGroup:"my-custom-runner-group"## name of the runner scale set to create. Defaults to the helm release namerunnerScaleSetName:"my-awesome-scale-set"## template is the PodSpec for each runner Pod## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpectemplate:spec:initContainers:-name:init-dind-externalsimage:ghcr.io/actions/actions-runner:latestcommand: ["cp","-r","/home/runner/externals/.","/home/runner/tmpDir/"]volumeMounts:-name:dind-externalsmountPath:/home/runner/tmpDir-name:init-dind-rootlessimage:docker:dind-rootlesscommand:-sh--c-|          set -x          cp -a /etc/. /dind-etc/          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd          echo 'runner:x:1001:' >> /dind-etc/group          echo 'runner:100000:65536' >> /dind-etc/subgid          echo 'runner:100000:65536' >> /dind-etc/subuid          chmod 755 /dind-etc;          chmod u=rwx,g=rx+s,o=rx /dind-home          chown 1001:1001 /dind-homesecurityContext:runAsUser:0volumeMounts:-mountPath:/dind-etcname:dind-etc-mountPath:/dind-homename:dind-home-name:dindimage:docker:dind-rootlessargs:-dockerd---host=unix:///run/user/1001/docker.socksecurityContext:privileged:truerunAsUser:1001runAsGroup:1001restartPolicy:AlwaysstartupProbe:exec:command:-docker-infoinitialDelaySeconds:0failureThreshold:24periodSeconds:5volumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/run/user/1001-name:dind-externalsmountPath:/home/runner/externals-name:dind-etcmountPath:/etc-name:dind-homemountPath:/home/runnercontainers:-name:runnerimage:ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]env:-name:DOCKER_HOSTvalue:unix:///run/user/1001/docker.socksecurityContext:privileged:truerunAsUser:1001runAsGroup:1001volumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/run/user/1001volumes:-name:workemptyDir: {}-name:dind-externalsemptyDir: {}-name:dind-sockemptyDir: {}-name:dind-etcemptyDir: {}-name:dind-homeemptyDir: {}

For versions of Kubernetes< v1.29, the following configuration will be applied:

## githubConfigUrl is the GitHub url for where you want to configure runners## ex: https://github.com/myorg/myrepo or https://github.com/myorggithubConfigUrl:"https://github.com/actions/actions-runner-controller"## githubConfigSecret is the k8s secrets to use when auth with GitHub API.## You can choose to use GitHub App or a PAT tokengithubConfigSecret:my-super-safe-secret## maxRunners is the max number of runners the autoscaling runner set will scale up to.maxRunners:5## minRunners is the min number of idle runners. The target number of runners created will be## calculated as a sum of minRunners and the number of jobs assigned to the scale set.minRunners:0runnerGroup:"my-custom-runner-group"## name of the runner scale set to create. Defaults to the helm release namerunnerScaleSetName:"my-awesome-scale-set"## template is the PodSpec for each runner Pod## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpectemplate:spec:initContainers:-name:init-dind-externalsimage:ghcr.io/actions/actions-runner:latestcommand: ["cp","-r","/home/runner/externals/.","/home/runner/tmpDir/"]volumeMounts:-name:dind-externalsmountPath:/home/runner/tmpDir-name:init-dind-rootlessimage:docker:dind-rootlesscommand:-sh--c-|          set -x          cp -a /etc/. /dind-etc/          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd          echo 'runner:x:1001:' >> /dind-etc/group          echo 'runner:100000:65536' >> /dind-etc/subgid          echo 'runner:100000:65536' >> /dind-etc/subuid          chmod 755 /dind-etc;          chmod u=rwx,g=rx+s,o=rx /dind-home          chown 1001:1001 /dind-homesecurityContext:runAsUser:0volumeMounts:-mountPath:/dind-etcname:dind-etc-mountPath:/dind-homename:dind-homecontainers:-name:runnerimage:ghcr.io/actions/actions-runner:latestcommand: ["/home/runner/run.sh"]env:-name:DOCKER_HOSTvalue:unix:///run/user/1001/docker.socksecurityContext:privileged:truerunAsUser:1001runAsGroup:1001volumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/run/user/1001-name:dindimage:docker:dind-rootlessargs:-dockerd---host=unix:///run/user/1001/docker.socksecurityContext:privileged:truerunAsUser:1001runAsGroup:1001volumeMounts:-name:workmountPath:/home/runner/_work-name:dind-sockmountPath:/run/user/1001-name:dind-externalsmountPath:/home/runner/externals-name:dind-etcmountPath:/etc-name:dind-homemountPath:/home/runnervolumes:-name:workemptyDir: {}-name:dind-externalsemptyDir: {}-name:dind-sockemptyDir: {}-name:dind-etcemptyDir: {}-name:dind-homeemptyDir: {}

Understanding runner-container-hooks

When the runner detects a workflow run that uses a container job, service container, or Docker action, it will call runner-container-hooks to create a new pod. The runner relies on runner-container-hooks to call the Kubernetes APIs and create a new pod in the same namespace as the runner pod. This newly created pod will be used to run the container job, service container, or Docker action. For more information, see therunner-container-hooks repository.

Configuring hook extensions

As of ARC version 0.4.0, runner-container-hooks support hook extensions. You can use these to configure the pod created by runner-container-hooks. For example, you could use a hook extension to set a security context on the pod. Hook extensions allow you to specify a YAML file that is used to update thePodSpec of the pod created by runner-container-hooks.

There are two options to configure hook extensions.

• Store in yourcustom runner image. You can store the PodSpec in a YAML file anywhere in your custom runner image. For more information, seeActions Runner Controller.
• Store in aConfigMap. You can create a config map with the PodSpec and mount that config map in the runner container. For more information, seeConfigMaps in the Kubernetes documentation.

Example: Using config map to set securityContext

Create a config map in the same namespace as the runner pods. For example:

apiVersion:v1kind:ConfigMapmetadata:name:hook-extensionnamespace:arc-runnersdata:content:|    metadata:      annotations:        example: "extension"    spec:      containers:        - name: "$job" # Target the job container          securityContext:            runAsUser: 1000

• The.metadata.labels andmetadata.annotations fields will be appended as is, unless their keys are reserved. You cannot override the.metadata.name andmetadata.namespace fields.
• The majority of the PodSpec fields are applied from the specified template, and will override the values passed from your Helm chartvalues.yaml file.
• If you specify additional volumes they will be appended to the default volumes specified by the runner.
• Thespec.containers are merged based on the names assigned to them.
  • If the name of the container is$job:
    • Thespec.containers.name andspec.containers.image fields are ignored.
    • Thespec.containers.env,spec.containers.volumeMounts, andspec.containers.ports fields are appended to the default container spec created by the hook.
    • The rest of the fields are applied as provided.
  • If the name of the container is not$job, the fields will be added to the pod definition as they are.

Enabling metrics

ARC can emit metrics about your runners, your jobs, and time spent on executing your workflows. Metrics can be used to identify congestion, monitor the health of your ARC deployment, visualize usage trends, optimize resource consumption, among many other use cases. Metrics are emitted by the controller-manager and listener pods in Prometheus format. For more information, seeExposition formats in the Prometheus documentation.

To enable metrics for ARC, configure themetrics property in thevalues.yaml file of thegha-runner-scale-set-controller chart.

The following is an example configuration.

metrics:controllerManagerAddr:":8080"listenerAddr:":8080"listenerEndpoint:"/metrics"

Once these properties are configured, your controller-manager and listener pods emit metrics via the listenerEndpoint bound to the ports that you specify in yourvalues.yaml file. In the above example, the endpoint is/metrics and the port is:8080. You can use this endpoint to scrape metrics from your controller-manager and listener pods.

To turn off metrics, update yourvalues.yaml file by removing or commenting out themetrics: object and its properties.

Available metrics for ARC

The following table shows the metrics emitted by the controller-manager and listener pods.

[1]: Listener metrics that have the counter type are reset when the listener pod restarts.

Upgrading ARC

Because there is no support for upgrading or deleting CRDs with Helm, it is not possible to use Helm to upgrade ARC. For more information, seeCustom Resource Definitions in the Helm documentation. To upgrade ARC to a newer version, you must complete the following steps.

1. Uninstall all installations ofgha-runner-scale-set.
2. Wait for resources cleanup.
3. Uninstall ARC.
4. If there is a change in CRDs from the version you currently have installed, to the upgraded version, remove all CRDs associated withactions.github.com API group.
5. Reinstall ARC again.

For more information, seeDeploying a runner scale set.

If you would like to upgrade ARC but are concerned about downtime, you can deploy ARC in a high availability configuration to ensure runners are always available. For more information, seeHigh availability and automatic failover.

Deploying a canary image

You can test features before they are released by using canary releases of the controller-manager container image. Canary images are published with tag formatcanary-SHORT_SHA. For more information, seegha-runner-scale-set-controller on the Container registry.

1. Update thetag in thegha-runner-scale-set-controllervalues.yaml file to:canary-SHORT_SHA
2. Update the fieldappVersion in theChart.yaml file forgha-runner-scale-set to:canary-SHORT_SHA
3. Re-install ARC using the updated Helm chart andvalues.yaml files.

High availability and automatic failover

ARC can be deployed in a high availability (active-active) configuration. If you have two distinct Kubernetes clusters deployed in separate regions, you can deploy ARC in both clusters and configure runner scale sets to use the samerunnerScaleSetName. In order to do this, each runner scale set must be assigned to a distinct runner group. For example, you can have two runner scale sets each namedarc-runner-set, as long as one runner scale set belongs torunner-group-A and the other runner scale set belongs torunner-group-B. For information on assigning runner scale sets to runner groups, seeManaging access to self-hosted runners using groups.

If both runner scale sets are online, jobs assigned to them will be distributed arbitrarily (assignment race). You cannot configure the job assignment algorithm. If one of the clusters goes down, the runner scale set in the other cluster will continue to acquire jobs normally without any intervention or configuration change.

Using ARC across organizations

A single installation of Actions Runner Controller allows you to configure one or more runner scale sets. These runner scale sets can be registered to a repository, organization, or enterprise. You can also use runner groups to control the permissions boundaries of these runner scale sets.

As a best practice, create a unique namespace for each organization. You could also create a namespace for each runner group or each runner scale set. You can install as many runner scale sets as needed in each namespace. This will provide you the highest levels of isolation and improve your security. You can use GitHub Apps for authentication and define granular permissions for each runner scale set.

Legal notice

Portions have been adapted fromhttps://github.com/actions/actions-runner-controller/ under the Apache-2.0 license:

Copyright 2019 Moto IshizawaLicensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at    http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.