Kubernetes 기반 GitHub Actions 러너 구축과 자동화 운영 가이드
개발팀이 빠르고 안전하게 코드를 배포하려면 CI/CD 파이프라인에 탄탄한 인프라가 필요합니다. 최근에는 GitHub Actions를 직접 호스팅해 구축하는 방식이 인기인데, 그 핵심에는 Kubernetes 기반의 셀프 호스티드 러너와 Flux2, 그리고 Actions Runner Controller(ARC)가 있습니다. ARC의 최신 버전(v0.12.1)은 배포 자동화와 확장성, 보안까지 대폭 강화했죠. 이 글에서는 AWS EKS 클러스터에서 Flux2와 ARC를 조합해, 스케일링 되는 GitHub Actions 러너를 직접 구축·운영하는 방법을 쉽고 재미있게 풀어봅니다. 실제 설정 파일 예시와 실전 팁도 알려드릴게요!
셀프 호스티드 GitHub Actions 러너: 왜 직접 운영해야 할까?
많은 개발자들이 처음엔 GitHub의 기본 러너를 사용하다가, 성능이나 커스터마이즈, 비용 문제로 고민합니다. 직접 호스팅하는 GitHub Actions 러너는 다음과 같은 이점이 있습니다:
환경 맞춤화: 필요한 소프트웨어나 보안 정책을 마음껏 적용할 수 있습니다.
고성능 빌드: 자체 인프라를 활용하므로 대형 빌드도 빠르게 처리 가능!
비용 절감: 특히 대형 워크플로우나 ‘굵은 러너’가 많을 땐 비용 차이가 큽니다.
강화된 보안성: 사내 네트워크 안에서 실행하며 민감한 데이터 보호도 수월합니다.
단, 관리가 복잡해질 수 있으니 자동화 툴과 클라우드 인프라로 설계하는 게 필수랍니다.
구축 아키텍처 한 눈에 보기: Flux2, ARC, Kubernetes, 그리고 시크릿 관리
실제 예시에서는 AWS EKS 1.33 버전의 Kubernetes 클러스터를 활용했습니다. 여기에 Flux2를 활용해 GitOps 방식으로 연동하고, ARC로 러너를 관리합니다. 핵심 구성은 다음과 같습니다:
Kubernetes (EKS 등): 러너와 컨트롤러의 실제 실행 터.
Flux2: 운영 코드와 클러스터 상태를 Git과 자동 동기화하는 GitOps 툴.
Actions Runner Controller (ARC): 러너의 배포, 업데이트, 확장/축소를 담당.
External Secrets Operator (ESO): GitHub 인증 토큰을 안전하게 주입하는 데 추천.
이런 구조는 확장성이 좋고, 선언적으로 관리되니 팀원 간 협업도 쉬워집니다!
네임스페이스 설계 노하우: 러너와 컨트롤러를 분리해 안전하게
Kubernetes에서는 네임스페이스로 리소스 경계를 나누는 게 기본입니다. 자주 실수하는 부분이 있는데, 러너와 ARC(컨트롤러&리스너) 컨테이너를 한 곳에 몰아넣지 마세요! 글에서 추천한 설계 패턴은 이렇습니다:
arc-systems: ARC 컨트롤러와 리스너만.
arc-runners: 실제 빌드 작업을 수행할 러너만.
이렇게 구성하면 보안적으로도 안전하고, 클러스터 운영도 훨씬 깔끔합니다.
Helm & Flux2로 ARC 설치: 자동화의 마법
수동 배포 시대는 끝! Helm Chart와 Flux2를 활용하면 ARC의 설치와 업그레이드가 완전히 자동화됩니다. 필요한 주요 설정 포인트는 다음과 같습니다:
Helm Repository(OCI 또는 URL 방식)와 HelmRelease를 선언적으로 정의
replicaCount등 기본 확장 파라미터 적용안정성과 복구성을 위해 설치 실패 시 재시도 설정
이렇게 하면 신규 버전 적용도 코드 한 줄만 바꾸면 끝나니 정말 편리하죠.
인증 토큰 관리 실전 팁: 쉽고 안전하게 비밀값 주입하기
러너가 GitHub와 연결되려면 인증 토큰이 필요합니다. 조금 더 간단한 실전 방법을 소개하면:
GitHub에서 Personal Access Token(필요 권한: ‘repo’ 또는 ‘admin:org’)을 발급.
아래처럼 kubectl 명령어로 시크릿 생성:
kubectl create secret generic gh-token-manual --namespace=arc-runners --from-literal=github_token='여러분의PAT'
External Secrets Operator를 사용하면 좀 더 유연하게 다양한 클라우드 비밀 스토어와 연동 가능합니다.
오토스케일링 Runner 배포: 자동으로 늘리고 줄이고
이제 러너를 대량으로 운영하는 데 가장 중요한 오토스케일링 기능을 설정할 차례입니다. 핵심은 HelmRelease에 Min/Max 러너 수, 리스너 템플릿, 리소스 한계치 등 실제 요구사항을 반영해주는 겁니다. 대표 예시는 아래와 같습니다:
실행 환경 (
githubConfigUrl,githubConfigSecret), 필요한 메모리·CPU 할당러너가 자동으로 1~10대까지 스케일링되는 Range 지정
빌드 실행 시
runs-on: arc-runner-set-test로 러너 직접 지정
이처럼 선언적 설정으로 팀의 사용량에 맞춰 유연하게 관리할 수 있답니다.
실제 배포 검증 방법: 제대로 작동하는지 꼭 확인!
설정하고 배포했다면, 아래 두 가지로 정상동작을 확인할 수 있습니다:
GitHub 저장소의 ‘Actions > Runners’ 메뉴에서 러너가 등록됐는지 살펴보기
테스트용 워크플로우를 아래처럼 실행해본다:
runs-on: arc-runner-set-test steps: - uses: actions/checkout@v3 - run: echo "Running on self-hosted runner"
문제가 있다면 오류 로그를 꼭 확인하세요! 이후 실제 운영에 들어가면, 빌드 속도나 확장성에서 확실한 차이를 느끼실 겁니다.
한눈에 정리: Kubernetes와 Flux2, ARC 조합의 실전 장점과 활용 팁
직접 Kubernetes 기반의 GitHub Actions 러너를 운영하는 것은, 폭넓은 확장성, 강력한 보안, 운영 자동화라는 세 마리 토끼를 동시에 잡을 수 있는 방법입니다.
Flux2와 Helm을 활용한 완전 자동화
ARC의 최신 확장성 기능으로 대규모 프로젝트 대응
네임스페이스 및 인증 토큰 분리로 보안 강화
클라우드 러너 특유의 비용 경쟁력
실제 현장에서는 “우리 팀 빌드 시간이 왜 이렇게 빠르지?” “개발 환경 커스터마이즈가 이렇게 쉬워도 되나?” 하는 반응을 쉽게 볼 수 있습니다.
개인적 실전 팁: 시작은 복잡하게 느껴질 수 있지만, 처음부터 IaC(코드로 인프라 관리)를 지향하세요. 작은 테스트부터 확장하면서, 오류 로그를 꼼꼼히 확인하는 습관이 큰 운영 사고를 막아줍니다.
여러분도 이 가이드를 참고해 개발 조직의 CI/CD를 한 단계 파워업 해보세요! 궁금한 점이나 실전 적용 후 경험도 댓글로 남겨 주시면 추가로 깊이 있는 팁을 공유드리겠습니다.
참고: