<div id="readability-page-1" class="page"><div>
<figure><img decoding="async" width="1024" height="574" data-attachment-id="1959" data-permalink="https://01010011.blog/2024/04/20/github-arc-%eb%a1%9c-autoscale-%eb%90%98%eb%8a%94-actions-runner-%ea%b5%ac%ec%84%b1%ed%95%98%ea%b8%b0/image-1-3/" data-orig-file="https://i0.wp.com/01010011.blog/wp-content/uploads/2024/04/image-1.png?fit=1920%2C1076&amp;ssl=1" data-orig-size="1920,1076" data-comments-opened="1" data-image-meta="{&quot;aperture&quot;:&quot;0&quot;,&quot;credit&quot;:&quot;&quot;,&quot;camera&quot;:&quot;&quot;,&quot;caption&quot;:&quot;&quot;,&quot;created_timestamp&quot;:&quot;0&quot;,&quot;copyright&quot;:&quot;&quot;,&quot;focal_length&quot;:&quot;0&quot;,&quot;iso&quot;:&quot;0&quot;,&quot;shutter_speed&quot;:&quot;0&quot;,&quot;title&quot;:&quot;&quot;,&quot;orientation&quot;:&quot;0&quot;}" data-image-title="image-1" data-image-description="" data-image-caption="" data-medium-file="https://i0.wp.com/01010011.blog/wp-content/uploads/2024/04/image-1.png?fit=300%2C168&amp;ssl=1" data-large-file="https://i0.wp.com/01010011.blog/wp-content/uploads/2024/04/image-1.png?fit=1024%2C574&amp;ssl=1" src="https://i0.wp.com/01010011.blog/wp-content/uploads/2024/04/image-1.png?resize=1024%2C574&amp;ssl=1" alt="" sizes="(max-width: 1000px) 100vw, 1000px" data-recalc-dims="1"></figure>



<p>엔터프라이즈 환경에서 GitHub을 사용하다 보면 사정상 GitHub에서 관리하는 Actions Runner를 사용하지 못해 직접 CI 환경을 구성해야 하는 경우가 있다. 이렇게 직접 구성한 Self-Hosted Actions Runner 환경을 보다 컴팩트하게, 리소스 효율적으로, On Demand Scale 하여 사용하고자할 때 Action Runner Controller(=ARC) k8s Operator는 괜찮은 옵션이다.<br>이 글에서는 ARC로 빌드 환경을 구성하는 방법, 겪어봄직한 문제들, 리소스 효율적으로 ARC를 운영하는 방법 등을 다룬다.</p>



<ul>
<li>ARC(=Action Runner Controller) 소개</li>



<li>helm chart를 이용해 ARC를 설치하는 방법</li>



<li>운영 시 필요한 ARC 설정
<ul>
<li>minRunners / maxRunners</li>



<li>containerMode: dind vs k8s</li>



<li>githubServerTLS</li>



<li>template(=PodSpec)</li>
</ul>
</li>
</ul>



<h2>ARC 소개</h2>



<p>개인 프로젝트로 GitHub을 이용하거나, 엔터프라이즈 환경에서 GitHub Cloud를 쓰고 있다면 GitHub Hosted Runner의 완성도가 높고 훌륭한 개발자 경험을 제공하기 때문에 Actions Runner 구성으로 문제를 겪을 일은 많지 않을 것이다.</p>



<p>하지만 격리된 사설망 내부에 위치한 GitHub Enterprise Server에서 Actions를 사용하려면 반드시 Self-Hosted Actions Runner를 손수 구성하여야 한다. GitHub에서 제공하는 Runner Agent 설치 도구를 이용하면 간편하게 Runner환경을 구성할 수 있지만 회사의 규모가 커서 빌드가 빈번히 발생한다면 효율적으로 Runner를 관리하는 것은 쉽지 않은 일이다.</p>



<p>개발자 <a href="https://github.com/summerwind">summerwind</a> 는 효율적으로 동작하는 Actions Runner 제공을 위해 k8s 환경에서 Containerized된 Actions Runner 를관리하는 오픈소스 프로젝트를 커뮤니티에 처음 공개하였고, 이 프로젝트가 현재 ARC 의 전신이다.<br>단순히 k8s에서 Actions Runner를 배포하는 것을 넘어, Runner의 생명주기 관리를 단순화, 자동화하는 Runner Controller Operator라는 훌륭한 프로젝트의 컨셉은 커뮤니티의 인기를 넘어 공식 GitHub 팀의 주목을 받게 되었으며, 2023년 6월, Autoscaling Runner Scale Sets Mode 라는 GitHub Actions Organization에 포함되는 공식 프로젝트가 되었다.(링크: <a href="https://github.com/actions/actions-runner-controller/discussions/2775">Autoscaling Runner Scale Sets mode is now generally available</a>)</p>



<blockquote>
<p>처음 ARC 문서를 보면 이 부분을 헷갈릴 수 있는데<br>arc github repository doc 디렉토리 하위의 문서는 GitHub Organization으로 옮기기 이전 버전의 ARC 문서이고, github.com 페이지 하위의 ARC 문서가 현재 프로젝트 공식 문서이다. <br>(네임스페이스에 summerwind 라는 문구가 들어가 있으면 예전 프로젝트라는 뜻이니 참고하도록 하자.)</p>
</blockquote>



<p>아무튼, GitHub에서 추가한 Runner Scale Sets Mode는 ARC의 설치와 설정, 사용을 단순화시켰기 때문에 쉽게 따라할 수 있을 것이다.</p>



<h2>helm chart 를 이용한 ARC 설치</h2>



<p>너무 쉽다.<br>공식 문서의 <a href="https://github.com/actions/actions-runner-controller/discussions/2775">Quick Start Guide</a>를 2번 복붙하면 설치 완료다.<br>첫번째 복붙은 Runner Scale Set Controller를 설치하고,<br>두번째 복붙은 Runner Scale Set을 설치한다.</p>



<h4>Runner Scale Set Controller 설치</h4>



<pre data-enlighter-language="bash" data-enlighter-theme="" data-enlighter-highlight="" data-enlighter-linenumbers="" data-enlighter-lineoffset="" data-enlighter-title="" data-enlighter-group="">NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller</pre>



<h4>Runner Scale Set 설치</h4>



<pre data-enlighter-language="bash" data-enlighter-theme="" data-enlighter-highlight="" data-enlighter-linenumbers="" data-enlighter-lineoffset="" data-enlighter-title="" data-enlighter-group="">INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/&lt;your_enterprise/org/repo&gt;"
GITHUB_PAT="&lt;PAT&gt;"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
</pre>



<h2>운영시 필요한 ARC 설정하기</h2>



<p>ARC는 helm chart를 이용하여 배포하였기 때문에 value로 운영시 필요한 설정을 변경할 수 있다.</p>



<h4>min / max Runners 설정</h4>



<p>minRunners / maxRunners 는 이름에서 유추할 수 있듯이 ARC가 Scale할 수 있는 Runner 개수의 최대 / 최소값이다.<br>minRunners를 0으로 만들어두어도 On Demand로 빌드 요청이 들어오면 필요한 만큼 scale out 하므로<br>효율적으로 운영하고 싶다면 minRunners를 0으로 설정하자. <br>참고로 필자는 runner 환경에 대한 다양한 troubleshooting이 필요하여 minRunners 값은 1로 두고 <br>문제 상황 재현 용도로 사용하였다.</p>



<h4>신뢰하는 CA Certification 추가</h4>



<p>규모 있는 기업의 내부 개발망은 방화벽이나 프록시로 격리되어 있기 때문에 Outbound 통신을 하거나 Self Signed Cert를 Resolve하려면 추가적으로 신뢰할 수 있는 CA Certification 등록이 필요하다. 다양한 방법이 존재하나 ARC에서 제공하는 방식대로 추가하는 편이 가장 손이 덜 간다. 다음의 순서대로 진행하면 된다.</p>



<p>ConfigMap으로 cert 등록<br><code data-enlighter-language="bash">kubectl create configmap my-ca-cert --from-file=ca.crt</code></p>



<p>gha-runner-scale-set 의 values.yaml 에 githubServerTLS 설정</p>



<pre data-enlighter-language="yaml" data-enlighter-theme="" data-enlighter-highlight="" data-enlighter-linenumbers="" data-enlighter-lineoffset="" data-enlighter-title="" data-enlighter-group="">githubServerTLS:
    certificateFrom:
      configMapKeyRef:
        name: my-ca-cert
        key: ca.crt
    runnerMountPath: /usr/local/share/ca-certificates/</pre>



<p>template.spec.containers.env 에 RUNNER_UPDATE_CA_CERTS 값 “1”로 설정</p>



<p>다음과 같이 RUNNER_UPDATE_CA_CERTS 환경변수의 값을 1로 설정해두면 Runner Pod은 알아서 update-ca-certificates 를 수행한다.</p>



<pre data-enlighter-language="yaml" data-enlighter-theme="" data-enlighter-highlight="" data-enlighter-linenumbers="" data-enlighter-lineoffset="" data-enlighter-title="" data-enlighter-group="">spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        ...
        env:
            - name: RUNNER_UPDATE_CA_CERTS
            - value: "1"</pre>



<ol></ol>



<h4>containerMode: dind vs k8s</h4>



<p>containerMode 설정은 사전에 미리 작성해둔 template으로 Runner Pod을 dind(=Docker in Docker)로 동작시킬지 여부를 결정하는 옵션이다.<br>많은 경우 Build Runner에서 container image 빌드를 수행하기 때문에 익숙한 빌드도구인 docker buildx 를 쓰려면 Runner Pod을 dind 모드로 동작시켜야 한다.<br>하지만 dind는 k8s 노드의 docker.sock을 공유하기 때문에 격리된 Pod 외부로 의도하지 않은 영향을 끼칠 수 있는 보안 위협이 있을 수도 있다.(보통은 격리된 네트워크 환경에서 실행하기 때문에 이정도 리스크는 감수할 수도 있다.)<br>참고로, 필자는 dind mode를 사용하는 대신 <a href="https://github.com/GoogleContainerTools/kaniko">kaniko</a> 로 container image를 빌드하였다.</p>



<blockquote>
<p>dind 환경에서 동작하는 docker 이미지에서 빌드하다 x509 오류가 발생한다면<br>dind PodSpec template을 참고하여 initContainers 시점에 cert를 resolve 하는<br>dind template을 사용자 정의하여야 한다.<br>이 경우에는 반드시 containerMode 값을 비워둬야 한다.</p>
</blockquote>



<h2>그밖에</h2>



<p>Autoscale 되는 Runner를 더욱 효율적으로 사용하려면 <a href="https://karpenter.sh/">karpenter</a>를 구성하면 효과적이다.<br>현재까지 karpenter를 지원하는 Cloud 서비스는 AWS / Azure 둘 뿐이지만<br>ClusterAutoscaler 보다 개념적으로나 성능적으로 karpenter가 더 우수하므로<br>앞으로는 점차 지원하는 Cloud Provider가 많아질 것으로 예상한다.<br>만일 AWS나 Azure가 아닌 환경에서 karpenter를 테스트해보고 싶다면 <a href="https://github.com/kubernetes-sigs/kwok">kwok</a>(K8S WithOut Kubelet)을 설치하면 된다.</p>




</div></div>

01010011

엔터프라이즈 환경에서 GitHub을 사용하다 보면 사정상 GitHub에서 관리하는 Actions Runner를 사용하지 못해 직접 CI 환경을 구성해야 하는 경우가 있다. 이렇게 직접 구성한 Self-Hosted Actions Runner 환경을 보다 컴팩트하게, 리소스 효율적으로, On Demand Scale 하여 사용하고자할 때 Action Runner Controller(=ARC) k8s Operator는 괜찮은 옵션이다.
이 글에서는 ARC로 빌드 환경을 구성하는 방법, 겪어봄직한 문제들, 리소스 효율적으로 ARC를 운영하는 방법 등을 다룬다.
ARC(=Action Runner Controller) 소개
helm chart를 이용해 ARC를 설치하는 방법
운영 시 필요한 ARC 설정
minRunners / maxRunners
containerMode: dind vs k8s
githubServerTLS
template(=PodSpec)
ARC 소개
개인 프로젝트로 GitHub을 이용하거나, 엔터프라이즈 환경에서 GitHub Cloud를 쓰고 있다면 GitHub Hosted Runner의 완성도가 높고 훌륭한 개발자 경험을 제공하기 때문에 Actions Runner 구성으로 문제를 겪을 일은 많지 않을 것이다.
하지만 격리된 사설망 내부에 위치한 GitHub Enterprise Server에서 Actions를 사용하려면 반드시 Self-Hosted Actions Runner를 손수 구성하여야 한다. GitHub에서 제공하는 Runner Agent 설치 도구를 이용하면 간편하게 Runner환경을 구성할 수 있지만 회사의 규모가 커서 빌드가 빈번히 발생한다면 효율적으로 Runner를 관리하는 것은 쉽지 않은 일이다.
개발자 summerwind 는 효율적으로 동작하는 Actions Runner 제공을 위해 k8s 환경에서 Containerized된 Actions Runner 를관리하는 오픈소스 프로젝트를 커뮤니티에 처음 공개하였고, 이 프로젝트가 현재 ARC 의 전신이다.
단순히 k8s에서 Actions Runner를 배포하는 것을 넘어, Runner의 생명주기 관리를 단순화, 자동화하는 Runner Controller Operator라는 훌륭한 프로젝트의 컨셉은 커뮤니티의 인기를 넘어 공식 GitHub 팀의 주목을 받게 되었으며, 2023년 6월, Autoscaling Runner Scale Sets Mode 라는 GitHub Actions Organization에 포함되는 공식 프로젝트가 되었다.(링크: Autoscaling Runner Scale Sets mode is now generally available)
처음 ARC 문서를 보면 이 부분을 헷갈릴 수 있는데
arc github repository doc 디렉토리 하위의 문서는 GitHub Organization으로 옮기기 이전 버전의 ARC 문서이고, github.com 페이지 하위의 ARC 문서가 현재 프로젝트 공식 문서이다. 
(네임스페이스에 summerwind 라는 문구가 들어가 있으면 예전 프로젝트라는 뜻이니 참고하도록 하자.)
아무튼, GitHub에서 추가한 Runner Scale Sets Mode는 ARC의 설치와 설정, 사용을 단순화시켰기 때문에 쉽게 따라할 수 있을 것이다.
helm chart 를 이용한 ARC 설치
너무 쉽다.
공식 문서의 Quick Start Guide를 2번 복붙하면 설치 완료다.
첫번째 복붙은 Runner Scale Set Controller를 설치하고,
두번째 복붙은 Runner Scale Set을 설치한다.
Runner Scale Set Controller 설치
NAMESPACE="arc-systems"
helm install arc \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
Runner Scale Set 설치
INSTALLATION_NAME="arc-runner-set"
NAMESPACE="arc-runners"
GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>"
GITHUB_PAT="<PAT>"
helm install "${INSTALLATION_NAME}" \
    --namespace "${NAMESPACE}" \
    --create-namespace \
    --set githubConfigUrl="${GITHUB_CONFIG_URL}" \
    --set githubConfigSecret.github_token="${GITHUB_PAT}" \
    oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set
운영시 필요한 ARC 설정하기
ARC는 helm chart를 이용하여 배포하였기 때문에 value로 운영시 필요한 설정을 변경할 수 있다.
min / max Runners 설정
minRunners / maxRunners 는 이름에서 유추할 수 있듯이 ARC가 Scale할 수 있는 Runner 개수의 최대 / 최소값이다.
minRunners를 0으로 만들어두어도 On Demand로 빌드 요청이 들어오면 필요한 만큼 scale out 하므로
효율적으로 운영하고 싶다면 minRunners를 0으로 설정하자. 
참고로 필자는 runner 환경에 대한 다양한 troubleshooting이 필요하여 minRunners 값은 1로 두고 
문제 상황 재현 용도로 사용하였다.
신뢰하는 CA Certification 추가
규모 있는 기업의 내부 개발망은 방화벽이나 프록시로 격리되어 있기 때문에 Outbound 통신을 하거나 Self Signed Cert를 Resolve하려면 추가적으로 신뢰할 수 있는 CA Certification 등록이 필요하다. 다양한 방법이 존재하나 ARC에서 제공하는 방식대로 추가하는 편이 가장 손이 덜 간다. 다음의 순서대로 진행하면 된다.
ConfigMap으로 cert 등록
kubectl create configmap my-ca-cert --from-file=ca.crt
gha-runner-scale-set 의 values.yaml 에 githubServerTLS 설정
githubServerTLS:
    certificateFrom:
      configMapKeyRef:
        name: my-ca-cert
        key: ca.crt
    runnerMountPath: /usr/local/share/ca-certificates/
template.spec.containers.env 에 RUNNER_UPDATE_CA_CERTS 값 “1”로 설정
다음과 같이 RUNNER_UPDATE_CA_CERTS 환경변수의 값을 1로 설정해두면 Runner Pod은 알아서 update-ca-certificates 를 수행한다.
spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        ...
        env:
            - name: RUNNER_UPDATE_CA_CERTS
            - value: "1"
containerMode: dind vs k8s
containerMode 설정은 사전에 미리 작성해둔 template으로 Runner Pod을 dind(=Docker in Docker)로 동작시킬지 여부를 결정하는 옵션이다.
많은 경우 Build Runner에서 container image 빌드를 수행하기 때문에 익숙한 빌드도구인 docker buildx 를 쓰려면 Runner Pod을 dind 모드로 동작시켜야 한다.
하지만 dind는 k8s 노드의 docker.sock을 공유하기 때문에 격리된 Pod 외부로 의도하지 않은 영향을 끼칠 수 있는 보안 위협이 있을 수도 있다.(보통은 격리된 네트워크 환경에서 실행하기 때문에 이정도 리스크는 감수할 수도 있다.)
참고로, 필자는 dind mode를 사용하는 대신 kaniko 로 container image를 빌드하였다.
dind 환경에서 동작하는 docker 이미지에서 빌드하다 x509 오류가 발생한다면
dind PodSpec template을 참고하여 initContainers 시점에 cert를 resolve 하는
dind template을 사용자 정의하여야 한다.
이 경우에는 반드시 containerMode 값을 비워둬야 한다.
그밖에
Autoscale 되는 Runner를 더욱 효율적으로 사용하려면 karpenter를 구성하면 효과적이다.
현재까지 karpenter를 지원하는 Cloud 서비스는 AWS / Azure 둘 뿐이지만
ClusterAutoscaler 보다 개념적으로나 성능적으로 karpenter가 더 우수하므로
앞으로는 점차 지원하는 Cloud Provider가 많아질 것으로 예상한다.
만일 AWS나 Azure가 아닌 환경에서 karpenter를 테스트해보고 싶다면 kwok(K8S WithOut Kubelet)을 설치하면 된다.

GitHub ARC 로 Autoscale 되는 Actions Runner 구성하기

댓글