terraform-aws-eks-github-runner

Terraform module for deploying GitHub Actions Runner Operator inside a pre-existing EKS cluster.

Setting Up Authentication with GitHub API

There are two ways for actions-runner-controller to authenticate with the GitHub API (only 1 can be configured at a time however):

1. Using a GitHub App (not supported for enterprise level runners due to lack of support from GitHub)
2. Using a PAT

Functionality wise, there isn't much of a difference between the 2 authentication methods. The primarily benefit of authenticating via a GitHub App is an increased API quota.

If you are deploying the solution for a GitHub Enterprise Server environment you are able to configure your rate limiting settings making the main benefit irrelevant. If you're deploying the solution for a GitHub Enterprise Cloud or regular GitHub environment and you run into rate limiting issues, consider deploying the solution using the GitHub App authentication method instead.

Deploying Using GitHub App Authentication

You can create a GitHub App for either your user account or any organization, below are the app permissions required for each supported type of runner:

Note: Links are provided further down to create an app for your logged in user account or an organisation with the permissions for all runner types set in each link's query string

Required Permissions for Repository Runners:
Repository Permissions

• Actions (read)
• Administration (read / write)
• Metadata (read)

Required Permissions for Organisation Runners:
Repository Permissions

• Actions (read)
• Metadata (read)

Organization Permissions

• Self-hosted runners (read / write)

Note: All API routes mapped to their permissions can be found here if you wish to review

---

Setup Steps

If you want to create a GitHub App for your account, open the following link to the creation page, enter any unique name in the "GitHub App name" field, and hit the "Create GitHub App" button at the bottom of the page.

• Create GitHub Apps on your account

If you want to create a GitHub App for your organization, replace the :org part of the following URL with your organization name before opening it. Then enter any unique name in the "GitHub App name" field, and hit the "Create GitHub App" button at the bottom of the page to create a GitHub App.

• Create GitHub Apps on your organization

You will see an App ID on the page of the GitHub App you created as follows, the value of this App ID will be used later.

Download the private key file by pushing the "Generate a private key" button at the bottom of the GitHub App page. This file will also be used later.

Go to the "Install App" tab on the left side of the page and install the GitHub App that you created for your account or organization.

When the installation is complete, you will be taken to a URL in one of the following formats, the last number of the URL will be used as the Installation ID later (For example, if the URL ends in settings/installations/12345, then the Installation ID is 12345).

• https://github.com/settings/installations/${INSTALLATION_ID}
• https://github.com/organizations/eventreactor/settings/installations/${INSTALLATION_ID}

Finally, register the App ID (APP_ID), Installation ID (INSTALLATION_ID), and downloaded private key file (PRIVATE_KEY_FILE_PATH) to Kubernetes as Secret.

Deploying Using PAT Authentication

Personal Access Tokens can be used to register a self-hosted runner by actions-runner-controller.

Log-in to a GitHub account that has admin privileges for the repository, and create a personal access token with the appropriate scopes listed below:

Required Scopes for Repository Runners

• repo (Full control)

Required Scopes for Organization Runners

• repo (Full control)
• admin:org (Full control)
• admin:public_key (read:public_key)
• admin:repo_hook (read:repo_hook)
• admin:org_hook (Full control)
• notifications (Full control)
• workflow (Full control)

Usage

module "github_runner" {
  source  = "DNXLabs/eks-github-runner/aws"
  version = "0.1.0"

  cluster_name                     = module.eks.cluster_id
  cluster_identity_oidc_issuer     = module.eks.cluster_oidc_issuer_url
  cluster_identity_oidc_issuer_arn = module.eks.oidc_provider_arn

  github_app_app_id          = "123"
  github_app_installation_id = "123"
  github_organizations       = [
    {
      name     = "example_org"
      replicas = 1
      label    = "example_label"
    }
  ]
  github_repositories        = [
    {
      name     = "example_repo"
      replicas = 1
      label    = "example_label"
    }
  ]
  policy_arns                = ["arn:aws:iam::aws:policy/AdministratorAccess"]
  github_app_private_key     = <<EOT
-----BEGIN RSA PRIVATE KEY-----
<key>
-----END RSA PRIVATE KEY-----
EOT

}

GitHub self-hosted runners can be deployed at various levels in a management hierarchy:

• The repository level
• The organization level

There are two ways to use this controller:

• Manage runners one by one with Runner.
• Manage a set of runners with RunnerDeployment.

Manual Deploy Repository Runners

To launch a single self-hosted runner, you need to create a manifest file includes Runner resource as follows. This example launches a self-hosted runner with name example-runner for the actions-runner-controller/actions-runner-controller repository.

# runner.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: Runner
metadata:
  name: example-runner
spec:
  repository: summerwind/actions-runner-controller
  env: []

Apply the created manifest file to your Kubernetes.

$ kubectl apply -f runner.yaml
runner.actions.summerwind.dev/example-runner created

You can see that the Runner resource has been created.

$ kubectl get runners
NAME             REPOSITORY                             STATUS
example-runner   summerwind/actions-runner-controller   Running

You can also see that the runner pod has been running.

$ kubectl get pods
NAME           READY   STATUS    RESTARTS   AGE
example-runner 2/2     Running   0          1m

The runner you created has been registered to your repository.

Now you can use your self-hosted runner. See the official documentation on how to run a job with it.

Manual Deploy Organization Runners

To add the runner to an organization, you only need to replace the repository field with organization, so the runner will register itself to the organization.

# runner.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: Runner
metadata:
  name: example-org-runner
spec:
  organization: your-organization-name

Now you can see the runner on the organization level (if you have organization owner permissions).

RunnerDeployments

There are RunnerReplicaSet and RunnerDeployment that corresponds to ReplicaSet and Deployment but for Runner.

You usually need only RunnerDeployment rather than RunnerReplicaSet as the former is for managing the latter.

# runnerdeployment.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: example-runnerdeploy
spec:
  replicas: 2
  template:
    spec:
      repository: mumoshu/actions-runner-controller-ci
      env: []

Apply the manifest file to your cluster:

$ kubectl apply -f runnerdeployment.yaml
runnerdeployment.actions.summerwind.dev/example-runnerdeploy created

You can see that 2 runners have been created as specified by replicas: 2:

$ kubectl get runners
NAME                             REPOSITORY                             STATUS
example-runnerdeploy2475h595fr   mumoshu/actions-runner-controller-ci   Running
example-runnerdeploy2475ht2qbr   mumoshu/actions-runner-controller-ci   Running

Runner Labels

To run a workflow job on a self-hosted runner, you can use the following syntax in your workflow:

jobs:
  release:
    runs-on: self-hosted

When you have multiple kinds of self-hosted runners, you can distinguish between them using labels. In order to do so, you can specify one or more labels in your Runner or RunnerDeployment spec.

# runnerdeployment.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: custom-runner
spec:
  replicas: 1
  template:
    spec:
      repository: summerwind/actions-runner-controller
      labels:
        - custom-runner

Once this spec is applied, you can observe the labels for your runner from the repository or organization in the GitHub settings page for the repository or organization. You can now select a specific runner from your workflow by using the label in runs-on:

jobs:
  release:
    runs-on: custom-runner

Note that if you specify self-hosted in your workflow, then this will run your job on any self-hosted runner, regardless of the labels that they have.

Runner Groups

Runner groups can be used to limit which repositories are able to use the GitHub Runner at an organization level. Runner groups have to be created in GitHub first before they can be referenced.

To add the runner to the group NewGroup, specify the group in your Runner or RunnerDeployment spec.

# runnerdeployment.yaml
apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: custom-runner
spec:
  replicas: 1
  template:
    spec:
      group: NewGroup

Using IRSA (IAM Roles for Service Accounts) in EKS

actions-runner-controller v0.15.0 or later has support for IRSA in EKS.

As similar as for regular pods and deployments, you firstly need an existing service account with the IAM role associated. Create one using e.g. eksctl. You can refer to the EKS documentation for more details.

Once you set up the service account, all you need is to add serviceAccountName and fsGroup to any pods that uses the IAM-role enabled service account.

For RunnerDeployment, you can set those two fields under the runner spec at RunnerDeployment.Spec.Template:

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: example-runnerdeploy
spec:
  template:
    spec:
      repository: USER/REO
      serviceAccountName: my-service-account
      securityContext:
        fsGroup: 1000

Requirements

Name	Version
terraform	>= 0.13
aws	>= 3.13, < 4.0
helm	>= 1.0, < 3.0
kubectl	>= 1.9.4
kubernetes	>= 1.10.0, < 3.0.0

Providers

Name	Version
aws	>= 3.13, < 4.0
helm	>= 1.0, < 3.0
kubectl	>= 1.9.4
kubernetes	>= 1.10.0, < 3.0.0

Inputs

Name	Description	Type	Default	Required
cluster_identity_oidc_issuer	The OIDC Identity issuer for the cluster.	string	n/a	yes
cluster_identity_oidc_issuer_arn	The OIDC Identity issuer ARN for the cluster that can be used to associate IAM roles with a service account.	string	n/a	yes
cluster_name	The name of the cluster.	string	n/a	yes
create_iam_role	Variable indicating whether it creates iam role.	bool	true	no
create_namespace	Whether to create Kubernetes namespace with name defined by namespace.	bool	true	no
enabled	Variable indicating whether deployment is enabled.	bool	true	no
ephemeral_runner	Variable indicating whether the runner restarts after running jobs.	bool	true	no
github_app_app_id	The ID of your GitHub App. This can't be set at the same time as github_token	string	n/a	yes
github_app_installation_id	The ID of your GitHub App installation. This can't be set at the same time as github_token	string	n/a	yes
github_app_private_key	The multiline string of your GitHub App's private key. This can't be set at the same time as github_token	string	n/a	yes
github_organizations	n/a	list(object({ name = string replicas = number label = string }))	[]	no
github_repositories	n/a	list(object({ name = string replicas = number label = string }))	[]	no
github_token	Your chosen GitHub PAT token. This can't be set at the same time as the github_app_*	string	""	no
helm_chart_name	GitHub Runner Controller Helm chart name.	string	"actions-runner-controller"	no
helm_chart_release_name	GitHub Runner Controller Helm chart release name.	string	"actions-runner-controller"	no
helm_chart_repo	GitHub Runner Controller Helm repository name.	string	"https://actions-runner-controller.github.io/actions-runner-controller"	no
helm_chart_version	GitHub Runner Controller Helm chart version.	string	"0.12.2"	no
mod_dependency	Dependence variable binds all AWS resources allocated by this module, dependent modules reference this variable.	any	null	no
namespace	GitHub Runner Controller Helm chart namespace which the service will be created.	string	"actions-runner-system"	no
policy_arns	n/a	list(string)	[]	no
service_account_iam_role_arn	Variable indicating the iam role arn to be used by the service account.	string	""	no
service_account_name	GitHub runner service account name.	string	"github-actions-runner-controller"	no
settings	Additional settings which will be passed to the Helm chart values, see https://github.com/actions-runner-controller/actions-runner-controller/blob/master/charts/actions-runner-controller/README.md	map	{}	no

Outputs

No output.

Authors

Module managed by DNX Solutions.

License

Apache 2 Licensed. See LICENSE for full details.