10. Github Action Hosted Runner 생성

actions-runner-controller: Kubernetes 기반으로 Runner의 배포 및 관리를 자동화하는 컨트롤러
gha-runner-scale-set-controller: GitHub Scale Set Runner 기능을 Kubernetes 환경에서 구현 및 제어
gha-runner-scale-set: Scale Set Runners의 구체적인 설정 및 배포 리소스를 정의

1. actions-runner-controller

Kubernetes 클러스터에서 GitHub Actions 러너를 관리
자동 프로비저닝 및 수명 주기 관리를 처리
레포지토리, 조직 및 엔터프라이즈 수준의 배포를 지원
Kubernetes HPA를 사용하여 자동 스케일링을 지원

2. gha-runner-scale-set-controller

대규모 러너 배포를 관리
Scale Set Runners 기능을 활용
단일 엔드포인트를 통해 효율적인 러너 관리를 제공
GitHub의 Scale Set Runners API와 통합

3. gha-runner-scale-set

러너 스케일 세트를 구성하고 배포
GitHub Actions API를 통해 스케일링 및 수명 주기를 제어
워크플로와 러너 간의 통신을 최적화

1. actions-runner-controller

역할: GitHub Actions 호스트 러너를 Kubernetes 클러스터에서 관리하기 위한 컨트롤러이다.

주요 기능:
- GitHub Actions 러너를 자동으로 프로비저닝하고 관리한다.
- GitHub 레포지토리, 조직, 또는 엔터프라이즈 수준에서 러너를 배치할 수 있다.
- 러너의 수명 주기(생성, 삭제)를 Kubernetes 리소스(Runner CRD)를 통해 제어한다.
- Auto-scaling:
  - Kubernetes HPA(Horizontal Pod Autoscaler)를 사용하여 워크로드에 따라 러너의 수를 조정할 수 있다.
  - 특정 레포지토리나 워크플로우의 필요에 따라 러너를 동적으로 조정한다.

사용 사례:
- 여러 레포지토리에서 다양한 워크플로우를 실행할 때 러너를 세밀하게 관리하고 싶을 때.
- 자동 스케일링 및 배포를 통해 비용 효율성을 극대화하고 싶을 때.

2. gha-runner-scale-set-controller

역할: GitHub Actions 러너를 대규모로 관리하기 위한 스케일 세트 컨트롤러이다.

주요 기능:
- GitHub Actions에서 지원하는 Scale Set Runners 기능을 활용하여 러너를 효율적으로 관리한다.
- 러너를 단일 엔드포인트로 집계하여 레포지토리 또는 워크플로우에서 간단히 사용할 수 있도록 제공한다.
- 러너를 배치하고 스케일링할 때 기존 방식보다 더 높은 효율성을 제공한다.
- GitHub의 Scale Set Runners API와 통합되어 작동한다.

사용 사례:
- 대규모 CI/CD 환경에서 GitHub Actions 러너를 통합적으로 관리하고 싶을 때.
- 레포지토리나 워크플로우 단위로 러너의 효율성을 최적화해야 할 때.

3. gha-runner-scale-set

역할: 스케일 세트를 사용하여 러너를 관리하기 위한 구체적인 설정 및 배포 리소스이다.

주요 기능:
- gha-runner-scale-set-controller와 함께 사용되어, GitHub Actions 러너의 스케일 세트를 구체적으로 구성한다.
- GitHub Actions API와 직접 연결하여, 러너 그룹의 스케일링 및 수명 주기를 제어한다.
- 스케일 세트를 통해 GitHub Actions 워크플로우와 러너 간의 통신을 최적화한다.

사용 사례:
- 러너를 효율적으로 그룹화하고, 대규모 배포 환경에서 세밀한 제어가 필요할 때.
- 워크플로우 실행 요청이 많을 때, 러너를 자동으로 스케일링하고 비용 효율성을 확보하고 싶을 때.

주요 차이점 요약

컴포넌트	역할	주요 특징	사용 사례
actions-runner-controller	Kubernetes 기반으로 러너의 배포 및 관리를 자동화하는 컨트롤러	러너의 생성/삭제를 제어하고 Kubernetes HPA를 통해 동적으로 스케일링	여러 레포지토리에서 동적으로 러너를 관리하고 싶을 때.
gha-runner-scale-set-controller	GitHub의 Scale Set Runner 기능을 Kubernetes 환경에서 구현 및 제어	러너를 스케일 세트 단위로 관리하고 효율성을 최적화	대규모 CI/CD 환경에서 여러 워크플로우의 러너를 통합 관리하고 싶을 때.
gha-runner-scale-set	Scale Set Runners의 구체적인 설정과 배포 리소스를 정의	Scale Set API와 통합되어, 대규모 러너 그룹의 세부 구성 및 스케일링 제어	워크플로우 요청량에 따라 러너를 그룹화하고, 효율적으로 스케일링하고 싶을 때.

결론

actions-runner-controller는 일반적인 Kubernetes 러너 관리 컨트롤러이다.
gha-runner-scale-set-controller와 gha-runner-scale-set은 대규모 환경에서 Scale Set을 활용하여 더 효율적인 러너 관리를 목표로 한다.
대규모 CI/CD 환경에서는 Scale Set을 사용하는 것이 더 적합할 수 있으며, 소규모 환경에서는 actions-runner-controller로도 충분하다.

Github Action Hosted Runner 설치

Hosted Runner를 설치하기 전에 사전에 준비해야 할 것들이 있다.

사전준비

간단한 진행을 위해 PAT Token을 생성해서 Test 해본다.

Github PAT Token 생성 or Github App 생성 (두가지 중 하나 선택)

Github PAT Token 생성

Github 조직/계정 설정 → Settings → Developer settings → GitHub Personal Access Token

PAT Token 관련 권한은 아래의 내용을 참고하면 된다.

Required scopes:

Repository Level: repo, workflow
Organization Level: read:org, admin:org, workflow
Enterprise Level: admin:enterprise, workflow

Github App 생성

1. 기존 App이 있는 경우

해당 App 클릭
"About" 섹션에서 "App ID" 확인

2. 새로운 App 생성이 필요한 경우

"New GitHub App" 클릭
필수 정보 입력:
- GitHub App name
- Homepage URL
- Webhook URL (선택사항)
Repository permissions 설정:
- Actions: Read & Write
- Administration: Read & Write
- Metadata: Read-only
"Create GitHub App" 클릭

3. Installation ID 얻기

App 생성 후 "Install App" 클릭
조직/계정에 설치
설치 후 URL에서 Installation ID 확인
예: https://github.com/organizations/YOUR-ORG/settings/installations/INSTALLATION_ID

4. Private Key 생성

App 설정 페이지로 이동
"Private keys" 섹션에서 "Generate a private key" 클릭
다운로드된 .pem 파일의 내용을 values.yaml 의 github_app_private_key 에 붙여넣기

`values.yaml` 에 작성

authSecret:
  github_app_id: "123456"  # App 설정의 "About" 섹션
  github_app_installation_id: "987654321"  # 설치 URL에서 확인
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEA....
    -----END RSA PRIVATE KEY-----

Github Action Hosted Runner 설치

설치순서

# Helm repo 추가
helm repo add actions-runner-controller <https://actions-runner-controller.github.io/actions-runner-controller>

# Namespace 생성
kubectl create namespace actions-runner-system

# Helm으로 설치
helm install actions-runner-controller actions-runner-controller/actions-runner-controller \\
    -n actions-runner-system \\
    -f runner.yaml

kubectl apply -f runner-cr.yaml

`runner.yaml`

# Do set authSecret.enabled=false and set env if you want full control over
# the GitHub authn related envvars of the container.
# See https://github.com/actions/actions-runner-controller/pull/937 for more details.
authSecret:
  enabled: true
  create: true
  name: "controller-manager"
  annotations: {}
  ### GitHub Apps Configuration
  ## NOTE: IDs MUST be strings, use quotes
  #github_app_id: ""
  #github_app_installation_id: ""
  #github_app_private_key: |
  ### GitHub PAT Configuration
  github_token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxx"
  ### Basic auth for github API proxy
  #github_basicauth_username: ""
  #github_basicauth_password: ""

# http(s) should be specified for dockerRegistryMirror, e.g.: dockerRegistryMirror="https://<your-docker-registry-mirror>"
dockerRegistryMirror: ""
image:
  repository: "summerwind/actions-runner-controller"
  actionsRunnerRepositoryAndTag: "summerwind/actions-runner:latest"
  dindSidecarRepositoryAndTag: "docker:dind"
  pullPolicy: IfNotPresent
  # The default image-pull secrets name for self-hosted runner container.
  # It's added to spec.ImagePullSecrets of self-hosted runner pods.
  actionsRunnerImagePullSecrets: []

imagePullSecrets: []
nameOverride: ""
fullnameOverride: ""

runner:
  statusUpdateHook:
    enabled: false

rbac:
  # # This allows ARC to dynamically create a ServiceAccount and a Role for each Runner pod that uses "kubernetes" container mode,
  # # by extending ARC's manager role to have the same permissions required by the pod runs the runner agent in "kubernetes" container mode.
  # # Without this, Kubernetes blocks ARC to create the role to prevent a privilege escalation.
  # # See https://github.com/actions/actions-runner-controller/pull/1268/files#r917327010
  allowGrantingKubernetesContainerModePermissions: true

serviceAccount:
  # Specifies whether a service account should be created
  create: true
  # Annotations to add to the service account
  annotations: {}
  # The name of the service account to use.
  # If not set and create is true, a name is generated using the fullname template
  name: ""

`runner-cr.yaml`

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: example-runner
spec:
  replicas: 1
  template:
    spec:
      # 단일 repository 연결
      repository: "your-github-username/your-repository"
      # 또는 organization 전체 연결
      # organization: "your-organization"
      
      # Runner 라벨 (GitHub Actions workflow에서 사용)
      labels:
        - self-hosted
        - linux
        - x64
      # env:
      #   - name: RUNNER_FEATURE_FLAG_CUSTOM_COMMANDS
      #     value: "true"
      # # 시크릿 사용
      # envFrom:
      #   - secretRef:
      #       name: runner-secrets

      # GitHub Enterprise 사용시
      # ephemeral: true  # 작업 완료 후 runner 자동 제거
      # group: "default"  # runner group 지정
      # workDir: "/home/runner/work"  # 작업 디렉토리 지정

주요 고려사항

GitHub App 또는 PAT 인증 중 하나를 선택해야 한다
GitHub App 사용을 권장 (더 나은 보안과 권한 관리)
Runner에 필요한 권한과 리소스를 적절히 설정
네트워크 정책과 보안 설정 확인

설치 확인

k get po -n actions-runner-system 
NAME                                         READY   STATUS    RESTARTS   AGE
actions-runner-controller-6b775bb94f-9m6g8   2/2     Running   0          56s

k get runnerdeployments.actions.summerwind.dev 
NAME             ENTERPRISE   ORGANIZATION   REPOSITORY                   GROUP   LABELS                          DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
example-runner                               somaz94/k8s-namespace-sync           ["self-hosted","linux","x64"]   1         1         1            0           10s

Runner 연동확인

repo → settings → actions → runner

Github Workflow 설정

name: Generate changelog
on:
  release:
    types: [created, edited]
  workflow_dispatch:  

permissions: 
  contents: write
  pull-requests: write

jobs:
  generate-changelog:
    # runs-on: ubuntu-latest

    # 둘다 가능 
    runs-on: self-hosted
    # runs-on: [self-hosted, linux, x64]

cr을 배포하는 곳에 hosted runner가 생긴다.

kubectl get pods -A | grep runner
actions-runner-system   actions-runner-controller-6b775bb94f-9m6g8                        2/2     Running     0             6m40s
default                 example-runner-fhjd4-4855l                                        2/2     Running     0             39s
default                 example-runner-fhjd4-4zbnn                                        2/2     Running     0             39s

마무리

Kubernetes 기반의 GitHub Actions Hosted Runner는 자체 인프라를 최대한 활용하면서도 GitHub Actions의 편의성과 유연성을 그대로 유지할 수 있는 강력한 방법이다.

actions-runner-controller는 선언형 방식으로 손쉽게 러너를 관리할 수 있게 해주며,

Auto-scaling과 효율적인 리소스 관리까지 가능해 DevOps 환경의 완성도를 높여준다.

특히 대규모 빌드 파이프라인이나 여러 프로젝트에서 러너를 재사용하고자 하는 경우,

`gha-runner-scale-set` 과 같은 확장 컨트롤러를 통해 운영 효율을 극대화할 수 있다.

향후에는 Runner를 위한 커스텀 이미지 구성, GPU 러너 운영, 조직 단위의 보안 정책 적용 등 고급 사용 사례도 정리할 예정이다.

자신만의 러너 인프라를 구축하고 싶다면, 이 글이 좋은 출발점이 될 것이다.

Reference

https://github.com/actions/actions-runner-controller

https://marshallku.com/dev/setup-github-actions-custom-runner-with-kubernetes

https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners

https://opstree.com/blog/2023/04/18/github-self-hosted-runner-on-kubernetes/

728x90

'IaC > CI CD Tool' 카테고리의 다른 글

ArgoCD Slack Notification 설정 방법 (0)	2025.05.08
ArgoCD SSO 구성 가이드(Gitlab) (0)	2025.03.31
Github Changelog 자동화 (0)	2025.02.10
8. Gitlab Repository Mirroring 방법 (0)	2025.01.20
9. Github Action Steps Context 활용법 (0)	2024.11.10

현재글10. Github Action Hosted Runner 생성

Somaz의 IT 공부 일지