ARC를 GitHub API에 인증하기

ARC를 GitHub API에 인증하기

Actions Runner Controller(ARC)를 GitHub API에 인증하는 방법을 알아봐요. GitHub App 또는 개인 액세스 토큰(classic / 세밀)을 사용해 ARC를 인증할 수 있어요. Vault 통합을 통한 자격 증명 제공 방식도 살펴봐요.

출처: 문서

본문

Actions Runner Controller(ARC)는 GitHub App이나 개인 액세스 토큰(classic)을 사용해 GitHub API에 인증할 수 있어요.

Note

엔터프라이즈 수준의 러너에는 GitHub App으로 인증할 수 없어요. 자세한 내용은 그룹을 사용해 자체 호스팅 러너 접근 관리하기를 참고하세요.

GitHub App으로 ARC 인증하기

  1. 조직이 소유한 GitHub App을 만들어요. 자세한 내용은 GitHub App 등록하기를 참고하세요. GitHub App을 다음과 같이 구성해요.

    1. "Homepage URL"에 https://github.com/actions/actions-runner-controller을 입력해요.

    2. "Permissions" 아래에서 Repository permissions을 클릭해요. 그런 다음 드롭다운 메뉴를 사용해 다음 접근 권한을 선택해요.

      • Administration: Read and write

        Note

        Administration: Read and write는 Actions Runner Controller를 저장소 범위에서 등록하도록 구성할 때만 필요해요. 조직 범위에서 등록할 때는 필요하지 않아요.

      • Metadata: Read-only

    3. "Permissions" 아래에서 Organization permissions을 클릭해요. 그런 다음 드롭다운 메뉴를 사용해 다음 접근 권한을 선택해요.

      • Self-hosted runners: Read and write

  2. GitHub App을 만든 후 GitHub App 페이지에서 "App ID" 값을 기록해 두어요. 이 값을 나중에 사용할 거예요.

  3. "Private keys" 아래에서 Generate a private key을 클릭하고 .pem 파일을 저장해요. 이 키를 나중에 사용할 거예요.

  4. 페이지 왼쪽 상단 모서리의 메뉴에서 Install app을 클릭하고, 조직 옆에서 Install을 클릭해 조직에 앱을 설치해요.

  5. 조직의 설치 권한을 확인한 후 앱 설치 ID(app installation ID)를 기록해 두어요. 이 값을 나중에 사용할 거예요. 앱 설치 페이지에서 앱 설치 ID를 찾을 수 있으며, URL 형식은 다음과 같아요:

    https://github.com/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

  6. 이전 단계의 앱 ID, 설치 ID, 다운로드한 .pem 개인 키 파일을 Kubernetes 시크릿으로 등록해요.

    GitHub App의 값으로 Kubernetes 시크릿을 만들려면 다음 명령을 실행해요.

    Note

    gha-runner-scale-set 차트가 설치된 것과 같은 네임스페이스에 시크릿을 만들어요. 이 예제에서 네임스페이스는 퀵스타트 문서와 일치하도록 arc-runners예요. 자세한 내용은 Actions Runner Controller 시작하기를 참고하세요.

    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_app_id=123456 \
   --from-literal=github_app_installation_id=654321 \
   --from-literal=github_app_private_key='-----BEGIN RSA PRIVATE KEY-----********'

    그런 다음 values.yaml 파일의 사본에서 githubConfigSecret 속성을 사용해 시크릿 이름을 참조로 전달해요.

    githubConfigSecret: pre-defined-secret

추가 Helm 구성 옵션은 ARC 저장소의 values.yaml을 참고하세요.

개인 액세스 토큰(classic)으로 ARC 인증하기

ARC는 개인 액세스 토큰(classic)을 사용해 자체 호스팅 러너를 등록할 수 있어요.

  1. 필요한 스코프를 가진 개인 액세스 토큰(classic)을 만들어요. 필수 스코프는 저장소 수준 또는 조직 수준에서 러너를 등록하는지에 따라 달라져요. 개인 액세스 토큰(classic)을 만드는 방법에 대한 자세한 내용은 개인 액세스 토큰 관리하기를 참고하세요.

    다음은 ARC 러너에 필요한 개인 액세스 토큰 스코프 목록이에요.

    • 저장소 러너: repo
    • 조직 러너: admin:org

  2. 개인 액세스 토큰(classic)의 값으로 Kubernetes 시크릿을 만들려면 다음 명령을 사용해요.

    Note

    gha-runner-scale-set 차트가 설치된 것과 같은 네임스페이스에 시크릿을 만들어요. 이 예제에서 네임스페이스는 퀵스타트 문서와 일치하도록 arc-runners예요. 자세한 내용은 Actions Runner Controller 시작하기를 참고하세요.

    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_token='YOUR-PAT'

  3. values.yaml 파일의 사본에서 시크릿 이름을 참조로 전달해요.

    githubConfigSecret: pre-defined-secret

    추가 Helm 구성 옵션은 ARC 저장소의 values.yaml을 참고하세요.

세밀한 개인 액세스 토큰으로 ARC 인증하기

ARC는 세밀한 개인 액세스 토큰을 사용해 자체 호스팅 러너를 등록할 수 있어요.

  1. 필요한 스코프를 가진 세밀한 개인 액세스 토큰을 만들어요. 필수 스코프는 저장소 수준 또는 조직 수준에서 러너를 등록하는지에 따라 달라져요. 세밀한 개인 액세스 토큰을 만드는 방법에 대한 자세한 내용은 개인 액세스 토큰 관리하기를 참고하세요.

    다음은 ARC 러너에 필요한 개인 액세스 토큰 스코프 목록이에요.

    • 저장소 러너:

      • Administration: Read and write

    • 조직 러너:

      • Administration: Read
      • Self-hosted runners: Read and write

  2. 세밀한 개인 액세스 토큰의 값으로 Kubernetes 시크릿을 만들려면 다음 명령을 사용해요.

    Note

    gha-runner-scale-set 차트가 설치된 것과 같은 네임스페이스에 시크릿을 만들어요. 이 예제에서 네임스페이스는 퀵스타트 문서와 일치하도록 arc-runners예요. 자세한 내용은 Actions Runner Controller 시작하기를 참고하세요.

    kubectl create secret generic pre-defined-secret \
   --namespace=arc-runners \
   --from-literal=github_token='YOUR-PAT'

  3. values.yaml 파일의 사본에서 시크릿 이름을 참조로 전달해요.

    githubConfigSecret: pre-defined-secret

    추가 Helm 구성 옵션은 ARC 저장소의 values.yaml을 참고하세요.

Vault 시크릿으로 ARC 인증하기

Note

Vault 통합은 현재 Azure Key Vault에 대한 지원과 함께 공개 미리보기(public preview) 상태예요.

gha-runner-scale-set 버전 0.12.0부터 ARC는 외부 vault에서 GitHub 자격 증명을 검색하는 것을 지원해요. Vault 통합은 러너 스케일 세트마다 구성돼요. 즉, 보안 및 운영 요구 사항에 따라 일부 스케일 세트는 Kubernetes 시크릿을 사용하고 다른 스케일 세트는 vault 기반 시크릿을 사용하도록 실행할 수 있어요.

Vault 통합 활성화하기

러너 스케일 세트에 vault 통합을 활성화하려면:

  1. githubConfigSecret 필드를 values.yaml 파일에서 vault에 저장된 시크릿 키의 이름으로 설정해요. 이 값은 문자열이어야 해요.
  2. keyVault 섹션의 주석을 해제하고 values.yaml 파일에서 적절한 제공자와 접근 세부 정보로 구성해요.
  3. 필수 인증서(.pfx)를 컨트롤러와 리스너 양쪽에 제공해요. 이렇게 하려면:
    • 인증서를 포함해 컨트롤러 이미지를 다시 빌드하거나,
    • listenerTemplate 및 controllerManager 필드를 사용해 인증서를 컨트롤러와 리스너 양쪽에 볼륨으로 마운트해요.

시크릿 형식

Azure Key Vault에 저장된 시크릿은 JSON 형식이어야 해요. 구조는 사용 중인 인증 유형에 따라 달라져요:

예제: GitHub 토큰

{
  "github_token": "TOKEN"
}

예제: GitHub App

{
  "github_app_id": "APP_ID_OR_CLIENT_ID",
  "github_app_installation_id": "INSTALLATION_ID",
  "github_app_private_key": "PRIVATE_KEY"
}

Vault 통합을 위한 values.yaml 구성하기

인증서는 .pfx 파일로 저장되고 /akv/cert.pfx에서 컨테이너에 마운트돼요. 아래는 인증에 이 인증서를 사용하도록 keyVault 섹션을 구성하는 방법의 예시예요:

keyVault:
  type: "azure_key_vault"
  proxy:
    https:
      url: "PROXY_URL"
      credentialSecretRef: "PROXY_CREDENTIALS_SECRET_NAME"
    http: {}
    noProxy: []
  azureKeyVault:
    clientId: <AZURE_CLIENT_ID>
    tenantId: <AZURE_TENANT_ID>
    url: <AZURE_VAULT_URL>
    certificatePath: "/akv/cert.pfx"

컨트롤러와 리스너에 인증서 제공하기

ARC는 vault로 인증하려면 .pfx 인증서가 필요해요. 이 인증서는 컨트롤러를 설치하는 동안 컨트롤러와 리스너 구성 요소 양쪽에서 사용할 수 있어야 해요. values.yaml 파일에서 controllerManager와 listenerTemplate 필드를 사용해 인증서를 볼륨으로 마운트해 이를 할 수 있어요:

volumes:
  - name: cert-volume
    secret:
      secretName: my-cert-secret
volumeMounts:
  - mountPath: /akv
    name: cert-volume
    readOnly: true

listenerTemplate:
  volumeMounts:
    - name: cert-volume
      mountPath: /akv/certs
      readOnly: true
  volumes:
    - name: cert-volume
      secret:
        secretName: my-cert-secret

아래 코드는 스케일 세트 values.yml 파일의 예시예요.

listenerTemplate:
  spec:
    containers:
      - name: listener
        volumeMounts:
          - name: cert-volume
            mountPath: /akv
            readOnly: true
    volumes:
      - name: cert-volume
        secret:
          secretName: my-cert-secret

법적 고지

일부는 Apache-2.0 라이선스에 따라 https://github.com/actions/actions-runner-controller/에서 각색되었어요:

Copyright 2019 Moto Ishizawa

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.