In this blog post, we will explore the process of hosting self-hosted runners on an Amazon Elastic Kubernetes Service (EKS) cluster. We will cover the steps involved in setting up and configuring the runners within the EKS environment. By leveraging EKS for runner hosting, you can take advantage of the scalability, flexibility, and manageability offered by Kubernetes while maintaining control over the execution environment. Stay tuned as we dive into the details of hosting self-hosted runners on an EKS cluster.
This platform is designed to facilitate the automation of your build, test, and deployment pipeline, commonly known as CI/CD. By utilising this platform, you can execute a workflow that automatically applies the necessary labels whenever a new issue is created in your repository.
GitHub offers Linux, Windows, and macOS virtual machines that you can utilise for running your workflows. Alternatively, you have the option to set up and use your own self-hosted runners within your own data center or cloud infrastructure.
Components
Events
A workflow run is initiated by a specific event or activity that occurs within a repository. This event serves as a trigger for the workflow to start executing
Jobs
A job refers to a collection of steps within a workflow that are executed on the same runner. These steps are executed sequentially as part of the job’s execution. By default, jobs have no dependencies and run in parallel. But you can configure dependencies.
Actions
An action is a custom application that is designed to perform complex and frequently repeated tasks. It serves as a reusable component within a workflow and can be easily integrated into different stages or steps of the workflow. Actions help automate and streamline common tasks, making workflow development and execution more efficient. There are two options available for incorporating actions into your workflows. Firstly, you have the flexibility to create your own custom actions tailored to your specific requirements. Secondly, you can explore the GitHub Marketplace, where you will find a wide range of pre-existing actions that you can readily incorporate into your workflows. The GitHub Marketplace offers a variety of actions contributed by the community, covering various use cases and functionalities.
Runners
A runner refers to a server that is responsible for executing your workflows whenever they are triggered. It serves as the execution environment for the workflows and performs the necessary steps and actions defined within them. A runner typically handles one job at a time, ensuring that each job is executed in a sequential and isolated manner.
Ephemeral Self hosted runners
GitHub suggests the implementation of auto scaling using ephemeral self-hosted runners, while it is not recommended to use persistent self-hosted runners for auto scaling purposes. In certain cases, GitHub cannot guarantee that jobs are not assigned to persistent runners while they are shut down.
By utilising ephemeral runners, GitHub ensures that only one job is assigned to a runner, thereby guaranteeing this behaviour. By adopting this approach, you can effectively manage your runners as ephemeral systems. This means that you can leverage automation to create a fresh and clean environment for each job, ensuring consistent and isolated execution. This approach helps to minimise the exposure of sensitive resources from previous jobs. By using ephemeral runners, the risk of a compromised runner receiving new jobs is also mitigated. This ensures better security and reduces the potential impact of any security breaches.
Deploying self hosted Runners
Self-hosted runners can be added at different levels within the management hierarchy:
- Repository-level runners: These runners are specifically dedicated to a single repository. They are configured and utilised within the context of that particular repository, enabling you to have more control over the execution environment for workflows associated with that repository.
- Organization-level runners: These runners are capable of processing jobs for multiple repositories within an organisation. They provide a shared execution environment for workflows across different repositories within the organisation, allowing for centralised management and resource allocation.
- Enterprise-level runners: These runners can be assigned to multiple organisations within an enterprise account. They offer a higher level of scalability and flexibility, as they can be utilised by multiple organisations within the enterprise. This allows for efficient resource utilisation and standardised workflows across the enterprise.
By adding self-hosted runners at different levels, you can tailor the execution environment to meet the specific needs of individual repositories, organisations, or the entire enterprise.
To create a setup for Github self hosted runners on EKS cluster, we would require the following as pre-requisites:
- EKS cluster
- Github Account
- Helm
Once this is setup we will begin the deployment of the self hosted runners. Follow the steps mentioned below:
1. Install cert manager
To ensure proper certificate management of the admission webhook, actions-runner-controller relies on cert-manager by default. Therefore, it is essential to have cert-manager installed on your Kubernetes cluster before proceeding with the installation of actions-runner-controller.
Before installing actions-runner-controller, you should verify that cert-manager is correctly set up and functioning on your Kubernetes cluster. This ensures that the necessary certificates and certificate management capabilities are in place for actions-runner-controller to operate securely.
helm repo add jetstack https://charts.jetstack.io
helm repo update
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml
helm install \
> cert-manager jetstack/cert-manager \
> --namespace cert-manager \
> --create-namespace \
> --version v1.11.0
kubectl --namespace cert-manager get all
2. Authentication for self hosted runner controller
To authenticate the self-hosted runner controller with the GitHub API, there are two methods available:
using a GitHub App or
Personal Access Token (PAT).
In this case, we will focus on using a Personal Access Token for authentication.
To create a Personal Access Token (PAT) for authentication with the GitHub API, follow these steps:
- Log in to your GitHub account.
- Click on your profile icon at the top right corner of the page and select “Settings” from the dropdown menu.
- In the left sidebar, click on “Developer Settings.”
- Choose “Personal Access Tokens” from the options.
- Click on the “Generate new token” button.
- Provide a descriptive note for the token to identify its purpose.
- Under “Select scopes,” choose the appropriate permissions for the token based on the access level required for the self-hosted runner controller. Make sure to grant the necessary permissions to access the repository.
- Once you have selected the desired scopes, click on the “Generate token” button at the bottom of the page.
- GitHub will generate the token and display it on the screen. Make sure to copy the token or save it in a secure location, as it will not be displayed again.
Remember to keep the generated Personal Access Token secure and treat it as sensitive information. Do not share it publicly or expose it in public repositories. It’s recommended to follow best practices for securely storing and managing access tokens.
Copy the personal access token created.
We will create a secret that is used by action runner controller deployment.
GITHUB_TOKEN=ghp_ExeXXXXXXuwedVxLolM7Z1XXXXXMihh
kubectl create ns actions-runner-system
kubectl create secret generic controller-manager -n actions-runner-system \
> --from-literal=github_token=${GITHUB_TOKEN}
3. Install Action Runner Controller on EKS
helm repo add actions-runner-controller https://actions-runner-controller.github.io/actions-runner-controller
helm repo update
helm upgrade --install --namespace actions-runner-system \
> --create-namespace --wait actions-runner-controller \
> actions-runner-controller/actions-runner-controller \
> --set syncPeriod=1m
Verify that the action-runner-controller is installed properly
kubectl --namespace actions-runner-system get all
Create a repository runner deployment to create self-hosted runners for running the workflows for the github repository vidushi-bansal/test
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
name: sh-runner
namespace: actions-runner-system
spec:
replicas: 1
template:
spec:
repository: vidushi-bansal/test
Apply the runner deployment yaml
kubectl apply -f runner-deployment.yaml
Check the runner deployment
kubectl get runnerdeployment -n actions-runner-system
kubectl get po -n actions-runner-system
Check the logs of runner pod to check if it has been configured and authenticated properly. The logs should look similar to what you can see in the image below if it has been configured correctly.
kubectl logs sh-runner-v6svw-8zpz2 -n actions-runner-system
As evident from the logs of the runner pod, it has been created and authenticated itself to github. We can check the same from github console as well.
4. Visualize the runners from the Github Repository
To access the runner settings for a specific repository in GitHub, follow these steps:
- Navigate to the GitHub repository you want to configure the runner settings for.
- Click on the “Settings” tab located on the repository’s menu bar.
- In the left sidebar, click on “Actions” under the “Options” section.
- Scroll down to the “Runners” section.
- Here, you will find the configuration options for the runners associated with the repository.
- You can view the list of available runners, their status, and labels.
- You can add self-hosted runners by clicking on the “Add runner” button.
- You can remove or disable specific runners by selecting them and using the respective options provided.
Note that access to the runner settings may require appropriate permissions and roles within the repository.
Your self hosted runner in EKS cluster has been authenticated successfully.
In coming blogs for this series we will explore example workflows that would run on the self hosted runners. I hope this blog was informative for you. If you have any questions/feedback regarding this blog, I am reachable at vidushi.bansal@nashtechglobal.com.
