Create a self-hosted GitHub Action Runner in EKS

One of my previous blog post, I have talked about how to create a self-hosted GitHub Action Runner in EC2 instance. GitHub Actions is a powerful CI/CD tool that enables developers to build, test, and deploy software using customizable workflows. It provides managed infrastructure for running actions, but there are instances when running workflows on your self-hosted infrastructure becomes essential. In this blog I am going to discuss about how to create GitHub Self Hosted Runner in EKS.

Prerequisites

Kubernetes Cluster

GitHub Repository

GitHub Personal Access Token

Helm installed in your system

Install Cert Manager in EKS Cluster

Before starting, you need to install cert-manager in your EKS cluster because by default, actions-runner-controller uses cert-manager for certificate management of Admission Webhook. Make sure you have already installed cert-manager before you install or you can install it by running the following command.

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.16.1 \
  --set crds.enabled=true

This command will install cert-manager on the cert-manager namespace as default. You can check if cert-manager is installed properly using the command below:

1	kubectl get pods -n cert-manager

Authenticating to the GitHub API

First, we need to set up a mechanism to authenticate the action runner controller to GitHub. This can be done in two ways:

PAT (Personal Access Token)

Using GitHub App

In this tutorial, I will be using the Personal Access Token method. To create a Personal Access Token, follow the steps below:

Create a Personal Access Token

Go to your GitHub account and click on the profile icon.
Click on the Settings option.
Click on the Developer settings option.
Click on the Personal access tokens option.
Click on the Generate new token button.
Enter a name for the token and select the repo scope.
Click on the Generate token button.
Copy the generated token and save it in a secure place.

Now you have successfully created a Personal Access Token. You will need this token to authenticate the action runner controller to GitHub.

Create a Kubernetes Secret

Next, you need to create a Kubernetes secret to store the Personal Access Token. Run the following command to create a Kubernetes secret:

## Create namspace for actions-runner-system
kubectl create ns actions-runner-system

## Create secret in actions-runner-system namespace
kubectl create secret generic controller-manager \
    -n actions-runner-system \
    --from-literal=github_token=<YOUR-GITHUB-PAT-TOKEN>

Install GitHub Action Runner Controller

Actions Runner Controller is an operator of Kubernetes that manages the self-hosted runners of GitHub actions. It makes sure that the required resources to run a workflow in available by automatically deploying, scaling, and monitoring the runners on the cluster according to the needs. To install Actions Runner Controller on your EKS cluster run the following commands:

## Add the Actions Runner Controller Helm repository
helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller

## Update the Helm repository
helm repo update

## Install Actions Runner Controller
helm upgrade --install --namespace actions-runner-system --create-namespace \
             --wait actions-runner-controller actions-runner-controller/actions-runner-controller

Custom Configuration

If you need to install action runner with specific values you can directly passing the values to the helm install command or you can create a values.yaml file and pass it to the helm install command.

Directly passing the values to the helm install command

helm upgrade --install --namespace actions-runner-system --create-namespace \
             --wait actions-runner-controller actions-runner-controller/actions-runner-controller \
             --set replicaCount=2 \
             & etc...

Using custom value file

Create a values.yaml file with custom values and pass it to the helm install command.:

1
2
3

helm upgrade --install --namespace actions-runner-system --create-namespace \
             --wait actions-runner-controller actions-runner-controller/actions-runner-controller \
             -f values.yaml

This is an example of a values.yaml file:

1
2
3

replicaCount: 2
labels: eks-self-hosted-runner
authSecret.name: controller-manager

Once the installation is done, run the command given below to verify if the action runner controller is installed properly.

1	kubectl get pods -n actions-runner-system

Create a Repository Runner

To create a GitHub runner, you need to create a GitHub runner resource in your EKS cluster. This resource will be used by the action runner controller to create a runner in your GitHub repository. To create a GitHub runner resource, you need to create a YAML file with the following content:

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
 name: k8s-action-runner
 namespace: actions-runner-system
spec:
 replicas: 2
 template:
   spec:
     repository: dinushchathurya/eks-self-hosted-runner
     labels:
       - eks-self-hosted-runner

Save the above content in a file named runner.yaml and run the following command to create the GitHub runner resource:

1	kubectl apply -f runner.yaml

Check that the pod is running using the below command:

1	kubectl get pod -n actions-runner-system \| grep -i "k8s-action-runner"

If everything goes well, you should see two action runners on the Kubernetes, and the same are registered on Github. Check under Settings > Actions > Runners of your repository.

Testing the Runner

To test the runner, you can create a simple workflow in your repository. Create a file named .github/workflows/test.yml with the following content:

name: Test Runner
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: eks-self-hosted-runner
    container:
      image: ubuntu:latest
    steps:
    - name: Checkout Repository
      uses: actions/checkout@v2
      with:
        ref: main

    - name: Echo Message
      run: echo "Hello World"

This YML file is configured like the workflow gets triggered whenever a change is pushed to the main branch and runs the build job on your GitHub Actions self-hosted runner. Make sure to specify your runner’s name in the above YML file.After creating the YML file, push the changes to your repository that will trigger the workflow. You can see if the build process has started by going to your GitHub repository and selecting the Actions tab.

Conclusion

In this tutorial, you have learned how to create a self-hosted GitHub action runner in EKS. You have installed cert-manager, created a Kubernetes secret to store the Personal Access Token, installed the action runner controller, and created a GitHub runner resource. Now you can run your workflows on your self-hosted runners in EKS.