Kubernetes #

If you have a large amount of machines and have Kubernetes installed, and you wish to dynamically adjust amount of runners, you should read this page.

Topology #

The whole design is to minimize secret crendential leak on the Runner instance, so a service called ‘KMS’ is used for handling runner registration(The PAT is only stored on ‘KMS’)

‘KMS’ #

To safely register a runner to GitHub without exposing Personal Access Token(PAT) to it, you should use this service.

First you need to create a docker-compose.yml file and write the following content.

version: '3'

services:
  kms:
    image: knatnetwork/github-runner-kms:latest
    restart: always
    environment:
      PAT_knatnetwork: 'ghp_Lxxxxxxxxxx2NUk5F'
      PAT_rust-lang: 'ghp_Lxxxxxxxxxx2NUk5F'
    ports:
      - 3000:3000

(If your org’s name is org_name, then environment should be PAT_org_name: 'ghp_Lxxxxxxxxxx2NUk5F')

After that you can use docker-compose up -d to start the KMS server, now the KMS service is listening on port 3000.

Runner #

With the ‘KMS’ running, it’s time to deploy runner, a simple way to approach this is to use a Deployment, you can copy the yml below and adjust necessary items.

In this example, dind is used to provide a Docker Daemon for Runner to avoid affecting Host while doing docker related operations.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: knat-network-runner-deployment
  labels:
    app: githubrunner
spec:
  replicas: 3
  selector:
    matchLabels:
      app: githubrunner
  template:
    metadata:
      labels:
        app: githubrunner
    spec:
      containers:
        - name: github-runner
          imagePullPolicy: Always
          image: 'knatnetwork/github-runner:focal-2.290.1'
          env:
            - name: RUNNER_REGISTER_TO
              value: "knatnetwork"
            - name: GOPROXY
              value: "http://goproxy.knat.network,https://proxy.golang.org,direct"
            - name: KMS_SERVER_ADDR
              value: "http://<KMS_HOST_IP>:3000"
            - name: RUNNER_LABELS
              value: "internal-cluster,docker"
            - name: DOCKER_HOST
              value: tcp://localhost:2375

        - name: dind
          imagePullPolicy: IfNotPresent
          image: docker:20.10.14-dind
          args: ["--registry-mirror=https://registry-mirror.knat.network"]
          securityContext:
            privileged: true
          env:
          - name: DOCKER_TLS_CERTDIR
            value: ""
          - name: DOCKER_HOST
            value: tcp://localhost:2375