Kubernetes hosted runners for Github Actions with ARC

Running GitHub Actions on Kubernetes with Actions Runner Controller GitHub Actions has become an integral part of modern CI/CD pipelines by allowing automation directly within your repository. With self-hosted runners, you can leverage your own infrastructure for enhanced control over execution environments. This guide will walk you through setting up GitHub Runners on a Kubernetes cluster using the latest version of Actions Runner Controller, which manages and scales these runners as native Kubernetes resources. Understanding GitHub Actions and Runners GitHub Actions supports automation workflows triggered by various events like push or pull requests. Runners are instances that execute the jobs defined in your workflow, with two types available: Hosted runners managed by GitHub Self-hosted runners, which you manage on your infrastructure This guide focuses on self-hosted runners deployed on Kubernetes. Setting Up Actions Runner Controller The Actions Runner Controller is designed to integrate seamlessly with Kubernetes, using Custom Resource Definitions (CRDs) to define and manage runner deployments. This makes it easier to scale and handle them as part of your cluster's resources. Prerequisites A Kubernetes cluster kubectl configured for your cluster Helm installed on your local machine Access to a GitHub repository where you can configure workflows Installing Actions Runner Controller Install the Custom Resource Definitions (CRDs) Begin by installing the CRDs necessary for managing runners: kubectl apply -f https://github.com/actions-runner-controller/actions-runner-controller/releases/latest/download/actions.runner-controller.crds.yaml Deploy the Controller Use Helm to deploy the runner controller in your Kubernetes cluster: helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller helm repo update helm install \ --namespace actions-runner-system \ --create-namespace \ --set=controller-manager.webhookPort=9443 \ --set=metrics.serve.enabled=true \ --set=metrics.serve.address=:8080 \ controller \ actions-runner-controller/actions-runner-controller Ensure you replace your-github-org with your GitHub organization or username and your_github_token with a personal access token that has the required scopes (repo, admin:org, and admin:repo_hook). Deploying Runners Create an arc.yaml file to define your runner configuration: apiVersion: actions.github.com/v1alpha1 kind: RunnerDeployment metadata: name: example-runnerdeploy spec: replicas: 2 template: spec: repository: "your-github-org/your-repo" Apply the configuration to your cluster: kubectl apply -f arc.yaml How Actions Runner Controller Works The Actions Runner Controller uses Kubernetes CRDs to represent runner deployments, ensuring they are managed efficiently as part of your cluster's resources. Long Polling Mechanism The controller employs a long polling strategy to determine when GitHub requires additional workers: Polling: The runner checks with GitHub periodically for pending jobs. Registration: If there are pending jobs, it registers itself as an available worker. Execution: It executes the job upon registration. Cleanup: After job completion, it deregisters and waits for new tasks. This approach optimizes resource usage by keeping runners idle until needed. Sequence Flow Diagram Below is a sequence flow diagram illustrating how the Actions Runner Controller operates within a Kubernetes cluster: +-----------------------------+ | GitHub (Waiting Jobs) | +------------+---------------+ | Polling for Jobs +------------v---------------+ | Runner Controller | +------------+---------------+ | Register Runner +------------v---------------+ | Runner Pod (Kubernetes) | +------------+---------------+ | Execute Job +------------v---------------+ | GitHub (Job Execution) | +-----------------------------+ This diagram simplifies the interaction between components, showing how runners are dynamically registered and deregistered based on job availability. Advantages of Using Actions Runner Controller Scalability: Easily adjust the number of runners in response to workload changes. Cost Efficiency: Optimize resource usage by running only as many instances as needed. Customization: Tailor environments according to specific requirements, including security and compliance standards. Considerations and Best Practices Security: Secure runner tokens using Kubernetes secrets for storing sensitive information like GitHub tokens. Resource Allocation: Adjust resource requests and limits on your pods to balance performance with cost. Monitoring and Logging: Implement robust mo

Feb 7, 2025 - 15:27

Kubernetes hosted runners for Github Actions with ARC

Running GitHub Actions on Kubernetes with Actions Runner Controller

GitHub Actions has become an integral part of modern CI/CD pipelines by allowing automation directly within your repository. With self-hosted runners, you can leverage your own infrastructure for enhanced control over execution environments. This guide will walk you through setting up GitHub Runners on a Kubernetes cluster using the latest version of Actions Runner Controller, which manages and scales these runners as native Kubernetes resources.

Understanding GitHub Actions and Runners

GitHub Actions supports automation workflows triggered by various events like push or pull requests. Runners are instances that execute the jobs defined in your workflow, with two types available:

Hosted runners managed by GitHub
Self-hosted runners, which you manage on your infrastructure

This guide focuses on self-hosted runners deployed on Kubernetes.

Setting Up Actions Runner Controller

The Actions Runner Controller is designed to integrate seamlessly with Kubernetes, using Custom Resource Definitions (CRDs) to define and manage runner deployments. This makes it easier to scale and handle them as part of your cluster's resources.

Prerequisites

A Kubernetes cluster
kubectl configured for your cluster
Helm installed on your local machine
Access to a GitHub repository where you can configure workflows

Installing Actions Runner Controller

Install the Custom Resource Definitions (CRDs)

Begin by installing the CRDs necessary for managing runners:

   kubectl apply -f https://github.com/actions-runner-controller/actions-runner-controller/releases/latest/download/actions.runner-controller.crds.yaml

Deploy the Controller

Use Helm to deploy the runner controller in your Kubernetes cluster:

   helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
   helm repo update

   helm install \
     --namespace actions-runner-system \
     --create-namespace \
     --set=controller-manager.webhookPort=9443 \
     --set=metrics.serve.enabled=true \
     --set=metrics.serve.address=:8080 \
     controller \
     actions-runner-controller/actions-runner-controller

Ensure you replace your-github-org with your GitHub organization or username and your_github_token with a personal access token that has the required scopes (repo, admin:org, and admin:repo_hook).

Deploying Runners

Create an arc.yaml file to define your runner configuration:

   apiVersion: actions.github.com/v1alpha1
   kind: RunnerDeployment
   metadata:
     name: example-runnerdeploy
   spec:
     replicas: 2
     template:
       spec:
         repository: "your-github-org/your-repo"

Apply the configuration to your cluster:

   kubectl apply -f arc.yaml

How Actions Runner Controller Works

The Actions Runner Controller uses Kubernetes CRDs to represent runner deployments, ensuring they are managed efficiently as part of your cluster's resources.

Long Polling Mechanism

The controller employs a long polling strategy to determine when GitHub requires additional workers:

Polling: The runner checks with GitHub periodically for pending jobs.
Registration: If there are pending jobs, it registers itself as an available worker.
Execution: It executes the job upon registration.
Cleanup: After job completion, it deregisters and waits for new tasks.

This approach optimizes resource usage by keeping runners idle until needed.

Sequence Flow Diagram

Below is a sequence flow diagram illustrating how the Actions Runner Controller operates within a Kubernetes cluster:

+-----------------------------+
| GitHub (Waiting Jobs)       |
+------------+---------------+
             | Polling for Jobs
+------------v---------------+
| Runner Controller           |
+------------+---------------+
             | Register Runner
+------------v---------------+
| Runner Pod (Kubernetes)     |
+------------+---------------+
             | Execute Job
+------------v---------------+
| GitHub (Job Execution)      |
+-----------------------------+

This diagram simplifies the interaction between components, showing how runners are dynamically registered and deregistered based on job availability.

Advantages of Using Actions Runner Controller

Scalability: Easily adjust the number of runners in response to workload changes.
Cost Efficiency: Optimize resource usage by running only as many instances as needed.
Customization: Tailor environments according to specific requirements, including security and compliance standards.

Considerations and Best Practices

Security: Secure runner tokens using Kubernetes secrets for storing sensitive information like GitHub tokens.
Resource Allocation: Adjust resource requests and limits on your pods to balance performance with cost.
Monitoring and Logging: Implement robust monitoring and logging solutions to track the health and performance of runners.
Networking: Ensure proper network policies are in place to allow secure communication between runners and GitHub.

Conclusion

Deploying GitHub Actions self-hosted runners using the Actions Runner Controller on Kubernetes provides flexibility, scalability, and control over your CI/CD processes. By adhering to best practices and understanding the system's workings, you can integrate this setup effectively into your development workflow.

References

By adopting the Actions Runner Controller, organizations can enhance their DevOps capabilities, ensuring efficient and reliable workflows for software delivery.