GitHub API に対する認証を行う

GitHub で Actions Runner Controller を使用するために GitHub API に対する認証を行う方法について説明します。

この記事の内容

法的通知

概要

GitHub App または personal access token (classic) を使うことで、GitHub API に対して Actions Runner Controller (ARC) の認証を行うことができます。

メモ

Enterprise レベルでランナーの GitHub App を使って認証を行うことはできません。 詳しくは、「グループを使用してセルフホストランナーへのアクセスを管理する」をご覧ください。

GitHub App で ARC の認証を行う

  1. Organization が所有する GitHub App を作成します。 詳しくは、「GitHub App の登録」をご覧ください。 次のように GitHub App を構成します。

    1. [ホームページの URL] に「https://github.com/actions/actions-runner-controller」と入力します。

    2. [アクセス許可] で [リポジトリのアクセス許可] をクリックします。 次に、ドロップダウン メニューを使って、次のアクセス許可を選びます。

      • 管理: 読み取りと書き込み

        メモ

        Administration: Read and write は、リポジトリ スコープに登録するように Actions Runner Controller を構成する場合にのみ必要です。 Organization のスコープで登録する必要はありません。

      • メタデータ: 読み取り専用

    3. [アクセス許可] で、 [Organization のアクセス許可] をクリックします。 次に、ドロップダウン メニューを使って、次のアクセス許可を選びます。

      • セルフホステッド ランナー: 読み取りと書き込み

  2. GitHub App のページで GitHub App を作成した後、"アプリ ID" の値を書き留めます。 この値は後で使用します。

  3. [秘密キー] で、 [秘密キーの生成] をクリックし、.pem ファイルを保存します。 このキーは後で使用します。

  4. ページの左上隅のメニューで [アプリのインストール] をクリックし、Organization の横にある [インストール] をクリックして、Organization にアプリをインストールします。

  5. Organization でインストールのアクセス許可を確認した後、アプリのインストール ID を記録しておきます。 これは後で使用します。 アプリのインストール ID はアプリのインストール ページで確認でき、次の URL 形式になっています。

    https://HOSTNAME/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID

  6. アプリ ID、インストール ID、および前の手順でダウンロードした .pem 秘密キー ファイルを Kubernetes にシークレットとして登録します。

    GitHub App の値を使って Kubernetes シークレットを作成するには、次のコマンドを実行します。

    メモ

    gha-runner-scale-set グラフがインストールされているのと同じ名前空間にシークレットを作成します。 この例では、名前空間は arc-runners クイックスタート ドキュメントと一致します。 詳しくは、「アクション ランナー コントローラーのクイック スタート」をご覧ください。

    Bash
    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 を参照してください。

personal access token (classic) で ARC の認証を行う

ARC では、personal access tokens (classic) を使ってセルフホステッド ランナーを登録できます。

メモ

personal access token (classic) での ARC の認証は、Enterprise レベルでランナーを登録するためにサポートされている唯一の認証方法です。

  1. 必要なスコープを使って personal access token (classic) を作成します。 必要なスコープは、リポジトリ、Organization、または Enterprise のどのレベルでランナーを登録するかによって異なります。 personal access token (classic) の作成方法の詳細については、「個人用アクセス トークンを管理する」を参照してください。

    ARC ランナーに必要な personal access token スコープの一覧を次に示します。

    • リポジトリ ランナー: repo
    • Organization ランナー: admin:org
    • Enterprise ランナー: manage_runners:enterprise

  2. personal access token (classic) の値を使って Kubernetes シークレットを作成するには、次のコマンドを使います。

    メモ

    gha-runner-scale-set グラフがインストールされているのと同じ名前空間にシークレットを作成します。 この例では、名前空間は arc-runners クイックスタート ドキュメントと一致します。 詳しくは、「アクション ランナー コントローラーのクイック スタート」をご覧ください。

    Bash
    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 を参照してください。

fine-grained personal access token を使用した ARC の認証

ARC では、fine-grained personal access tokens を使ってセルフホステッド ランナーを登録できます。

メモ

personal access token (classic) での ARC の認証は、Enterprise レベルでランナーを登録するためにサポートされている唯一の認証方法です。

  1. 必要なスコープを使って fine-grained personal access token を作成します。 必要なスコープは、リポジトリまたは organization のどちらのレベルでランナーを登録するかによって異なります。 fine-grained personal access token の作成方法について詳しくは、「個人用アクセス トークンを管理する」をご覧ください。

    ARC ランナーに必要な personal access token スコープの一覧を次に示します。

    • リポジトリ ランナー:

      • 管理: 読み取りと書き込み

    • Organization ランナー:

      • 管理: 読み取り
      • セルフホステッド ランナー: 読み取りと書き込み

  2. fine-grained personal access token の値を使って Kubernetes シークレットを作成するには、次のコマンドを使います。

    メモ

    gha-runner-scale-set グラフがインストールされているのと同じ名前空間にシークレットを作成します。 この例では、名前空間は arc-runners クイックスタート ドキュメントと一致します。 詳しくは、「アクション ランナー コントローラーのクイック スタート」をご覧ください。

    Bash
    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 の認証

メモ

現在、コンテナー統合は、Azure Key Vault のサポートを使用してパブリック プレビューで利用できます。

gha-runner-scale-set バージョン 0.12.0 以降の ARC では、外部コンテナーからの GitHub 資格情報の取得がサポートされます。 コンテナー統合はランナーのスケール セットごとに構成されます。 つまり、セキュリティと運用の要件に応じて、一部のスケール セットは Kubernetes のシークレットを使って実行し、他のスケール セットではコンテナーベースのシークレットを使って実行することができます。

コンテナー統合の有効化

ランナー スケール セットのコンテナー統合を有効にするには:

  1. values.yaml ファイルの githubConfigSecret フィールドを、コンテナーに格納されているシークレット キーの名前に設定します。 この値には文字列を設定する必要があります。
  2. values.yaml ファイルの keyVault セクションのコメントを解除し、適切なプロバイダーとアクセスの詳細を使って構成します。
  3. コントローラーとリスナーの両方に、必要な証明書 (.pfx) を指定します。 これを行うには、証明書が含まれるコントローラー イメージをリビルドするか、listenerTemplate と controllerManager フィールドを使ってコントローラーとリスナーの両方で証明書をボリュームとしてマウントします。

シークレットの形式

Azure Key Vault には、JSON 形式のシークレットを格納する必要があります。 構造は、お使いの認証の種類によって異なります。

例: GitHub トークン

{
  "github_token": "TOKEN"
}

例: GitHub アプリ

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

コンテナー統合用の 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 では、コンテナーでの認証のために .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.