# Actions Runner Controller の開始方法

このチュートリアルでは、Actions Runner Controller の基本を試してみます。

## 前提条件

ARC を使用するには、以下のものがそろっていることを確認してください。

* Kubernetes クラスター
  * マネージド クラウド環境の場合は、AKS を使用できます。 詳細については、Azureドキュメントの[Azure Kubernetes Service](https://azure.microsoft.com/en-us/products/kubernetes-service)を参照してください。
  * ローカル セットアップの場合は、minikube または kind を使用できます。 詳しくは、minikube ドキュメントの 「[minikube start](https://minikube.sigs.k8s.io/docs/start/)」と kind ドキュメントの「[kind](https://kind.sigs.k8s.io/)」を参照してください。

* Helm 3
  * 詳しくは、Helm ドキュメントの「[Helm のインストール](https://helm.sh/docs/intro/install/)」を参照してください。

* ARC をデプロイする必要はありませんが、実稼働ワークフローに ARC をデプロイする前に、コントローラー、リスナー、一時的ランナーからログを収集して保持する方法を実装することをお勧めします。

## アクション ランナー コントローラーのインストール

1. オペレーターとカスタム リソース定義 (CRD) をクラスターにインストールするには、以下のようにします。

   1. Helm チャートで、`NAMESPACE` の値を、オペレーター ポッドを作成する場所に更新します。 この名前空間では、Kubernetes API サーバーへのアクセスを許可する必要があります。
   2. Helm チャートをインストールします。

   次の例では、チャートの最新バージョンをインストールしています。 特定のバージョンをインストールするには、インストールするチャートのバージョンを指定した `--version` 引数を渡します。 リリースの一覧は、[GitHub Container Registry](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set-controller) にあります。

   ```bash copy
   NAMESPACE="arc-systems"
   helm install arc \
       --namespace "${NAMESPACE}" \
       --create-namespace \
       oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller
   ```

   その他の Helm 構成オプションについては、ARC ドキュメントの [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) を参照してください。

2. ARC で GitHub に対して認証できるようにするには、personal access token (classic) を生成します。 詳細については、「[GitHub API への ARC の認証](/ja/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api#deploying-using-personal-access-token-classic-authentication)」を参照してください。

## ランナースケールセットの構成

1. ランナー スケール セットを構成するには、ARC 構成の値を使用して、ターミナルで次のコマンドを実行します。

   コマンドを実行するときは、次の点に注意してください。

   * `INSTALLATION_NAME` の値は慎重に更新してください。 インストール名は、ワークフローで `runs-on` の値として使用することになります。 詳細については、「[GitHub Actions　のワークフロー構文](/ja/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)」を参照してください。

   * `NAMESPACE` の値を、ランナー ポッドを作成する場所に更新します。

   * `GITHUB_CONFIG_URL` を、リポジトリ、Organization、または Enterprise の URL に設定します。 これはランナーが属するエンティティです。

   * リポジトリと組織のランナーの`GITHUB_PAT`と`repo`のスコープを使用して、`admin:org`を GitHub personal access token に設定します。

   * このコマンド例では、最新バージョンの Helm チャートをインストールしています。 特定のバージョンをインストールするには、インストールするチャートのバージョンを指定した `--version` 引数を渡します。 リリースの一覧は、[GitHub Container Registry](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set) にあります。

     > \[!NOTE]
     >
     > * セキュリティのベスト プラクティスとして、オペレーター ポッドを含む名前空間とは異なる名前空間にランナー ポッドを作成します。
     > * セキュリティのベスト プラクティスとして、Kubernetes シークレットを作成し、シークレット参照を渡します。 CLI を介してプレーンテキストでシークレットを渡すと、セキュリティ上のリスクが生じる可能性があります。詳細については、「[アクション ランナー コントローラーを使用してランナー スケール セットをデプロイする](/ja/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller)」を参照してください。

     ```bash copy
     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
     ```

     その他の Helm 構成オプションについては、ARC ドキュメントの [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) を参照してください。

2. ターミナルから次のコマンドを実行して、インストールをチェックします。

   ```bash copy
   helm list -A
   ```

   次のような出力が表示されます。

   ```bash
   NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                                       APP VERSION
   arc             arc-systems     1               2023-04-12 11:45:59.152090536 +0000 UTC deployed        gha-runner-scale-set-controller-0.4.0       0.4.0
   arc-runner-set  arc-runners     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0
   ```

3. マネージャー ポッドをチェックするには、ターミナルで次のコマンドを実行します。

   ```bash copy
   kubectl get pods -n arc-systems
   ```

   すべてが正常にインストールされた場合、ポッドの状態は **\[実行中]** と表示されます。

   ```bash
   NAME                                                   READY   STATUS    RESTARTS   AGE
   arc-gha-runner-scale-set-controller-594cdc976f-m7cjs   1/1     Running   0          64s
   arc-runner-set-754b578d-listener                       1/1     Running   0          12s
   ```

インストールが成功しなかった場合、トラブルシューティング情報については、「[Actions Runner Controller エラーのトラブルシューティング](/ja/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors)」を参照してください。

## ランナー スケール セットの使用

次に、ランナー スケール セット ランナーを使用する簡単なテスト ワークフローを作成して実行しましょう。

1. リポジトリに次の例のようなワークフローを作成します。
   `runs-on` の値は、自動スケーリング ランナー セットのインストール時に使用した Helm インストール名と一致する必要があります。

   リポジトリへのワークフローの追加の詳細については、「[GitHub Actionsのクイック スタート](/ja/actions/quickstart#creating-your-first-workflow)」を参照してください。

   ```yaml copy
   name: Actions Runner Controller Demo
   on:
     workflow_dispatch:

   jobs:
     Explore-GitHub-Actions:
       # You need to use the INSTALLATION_NAME from the previous step
       runs-on: arc-runner-set
       steps:
       - run: echo "🎉 This job uses runner scale set runners!"
   ```

2. ワークフローをリポジトリに追加したら、ワークフローを手動でトリガーします。 詳細については、「[ワークフローの手動実行](/ja/actions/managing-workflow-runs/manually-running-a-workflow)」を参照してください。

3. ワークフローを実行しながら作成中のランナー ポッドを表示するには、ターミナルから次のコマンドを実行します。

   ```bash copy
   kubectl get pods -n arc-runners -w
   ```

   成功した場合の出力は次のようになります。

   ```bash
   NAMESPACE     NAME                                                  READY   STATUS    RESTARTS      AGE
   arc-runners   arc-runner-set-rmrgw-runner-p9p5n                     1/1     Running   0             21s
   ```

## 次のステップ

Actions Runner Controller は、GitHub Actions ランナーを効率的に管理するのに役立ちます。 作業を開始する準備はできましたか? ARC を使う次のステップに進む際は、以下のリソースが役立ちます。

* 認証情報の詳細については、「[GitHub API への ARC の認証](/ja/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api)」を参照してください。
* ワークフローで ARC ランナーを使用する方法については、「[ワークフローでの Actions Runner Controller ランナーの使用](/ja/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow)」を参照してください。
* 配置情報については、「[アクション ランナー コントローラーを使用してランナー スケール セットをデプロイする](/ja/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller)」を参照してください。

## 法務上の通知

Apache-2.0 ライセンスのもとで <https://github.com/actions/actions-runner-controller/> から一部を引用しています。

```text
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.
```