アクション ランナー コントローラーを使用してランナー スケール セットをデプロイする

ランナー スケール セットをデプロイする

ランナー スケール セットをデプロイするには、ARC が動作している必要があります。 詳しくは、「AUTOTITLE」をご覧ください。

ランナー スケール セットは、ARC の Helm チャートを使用するか、必要なマニフェストをデプロイすることでデプロイできます。 お勧めの方法は、ARC の Helm チャートを使用することです。これまでに ARC を使用した経験がない場合は特にそうです。

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

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

   • の値は慎重に更新してください。 インストール名は、ワークフローで の値として使用することになります。

   • 値を、ランナー ポッドを作成したい場所に更新してください。

   • 値を、リポジトリ、オーガニゼーション、またはエンタープライズのURLに設定します。 これはランナーが属するエンティティです。

   • このコマンド例では、最新バージョンの Helm チャートをインストールしています。 特定のバージョンをインストールするには、インストールするチャートのバージョンを指定した 引数を渡します。 リポジトリにリリースの一覧があります。

     Bash

     INSTALLATION_NAME="arc-runner-set"
     NAMESPACE="arc-runners"
     GITHUB_CONFIG_URL="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'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 を参照してください。

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

   Bash

   helm list -A
   

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

   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-systems     1               2023-04-12 11:46:13.451041354 +0000 UTC deployed        gha-runner-scale-set-0.4.0                  0.4.0
   

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

   Bash

   kubectl get pods -n arc-systems
   

   インストールが成功した場合、ポッドに の状態が表示されます。

   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
   

インストールが成功しなかった場合、トラブルシューティング情報については、「AUTOTITLE」を参照してください。

詳細な構成オプションを使用する

ARC には、いくつかの詳細な構成オプションが用意されています。

ランナー スケールセット名を設定する

ランナー スケール セット名を構成するには、 ファイルのコピーで、 を定義するか、 の値を設定します。

## The name of the runner scale set to create, which defaults to the Helm release name
runnerScaleSetName: "my-runners"

コマンドで ファイルを必ず渡してください。 詳しくは、「Helm のインストール」のドキュメントを参照してください。

ランナーのデスティネーションを選ぶ

ランナー スケール セットは、リポジトリ、Organization、または Enterprise レベルでデプロイできます。

ランナー スケール セットを特定のレベルにデプロイするには、 のコピー内で の値をリポジトリ、Organization、または Enterprise の URL に設定します。

次の例は、 にランナーを追加するように ARC を構成する方法を示しています。

githubConfigUrl: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>"

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

認証に GitHub App を使用する

Enterprise レベルのランナーを使用していない場合は、GitHub Apps を使用して、GitHub API によって認証できます。 詳しくは、「AUTOTITLE」をご覧ください。

Kubernetes シークレットを作成するか、 ファイル内で値を指定できます。

オプション 1: Kubernetes シークレットを作成する (推奨)

GitHub App を作成したら、Kubernetes シークレットを作成し、 ファイルのコピー内でそのシークレットへの参照を渡します。

kubectl create secret generic pre-defined-secret \
  --namespace=arc-runners \
  --from-literal=github_app_id=123456 \
  --from-literal=github_app_installation_id=654321 \
  --from-file=github_app_private_key=private-key.pem

のコピー内で、シークレット名を参照として渡します。

githubConfigSecret: pre-defined-secret

オプション 2: ファイル内に値を指定する

または、 ファイルのコピー内に 、、 の値を指定することもできます。

## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API.
## You can choose to use a GitHub App or a personal access token (classic)
githubConfigSecret:
  ## GitHub Apps Configuration
  ## IDs must be strings, use quotes
  github_app_id: "123456"
  github_app_installation_id: "654321"
  github_app_private_key: |
    -----BEGIN RSA PRIVATE KEY-----
    ...
    HkVN9...
    ...
    -----END RSA PRIVATE KEY-----

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

ランナー グループを使ってアクセスを管理する

ランナー グループを使用して、どの Organization またはリポジトリがランナー スケール セットにアクセスできるかを制御できます。 ランナー グループの詳細については、「AUTOTITLE」を参照してください。

ランナー スケール セットをランナー グループに追加するには、ランナー グループが既に作成されている必要があります。 次に、 ファイルのコピー内で プロパティを設定します。 次の例では、ランナースケールセットを Octo-Group ラナーグループに追加する方法を示します。

runnerGroup: "Octo-Group"

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

送信プロキシを構成する

コントローラーとランナーの HTTP トラフィックが送信プロキシを通過するように強制するには、Helm チャートで次のプロパティを設定します。

proxy:
  http:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  https:
    url: http://proxy.com:1234
    credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys
  noProxy:
    - example.com
    - example.org

ARC では、匿名または認証済みのプロキシの使用がサポートされています。 認証済みプロキシを使用する場合は、Kubernetes シークレットを参照するように 値を設定する必要があります。 次のコマンドにより、プロキシ資格情報を使用してシークレットを作成できます。

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

  kubectl create secret generic proxy-auth \
    --namespace=arc-runners \
    --from-literal=username=proxyUsername \
    --from-literal=password=proxyPassword \

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

ランナーの最大数と最小数を設定する

および プロパティには、ARC セットアップをカスタマイズするためのさまざまなオプションが用意されています。

例: 無制限のランナー数

と の両方のプロパテをコメントアウトすると、ARC はランナー スケール セットに割り当てられたジョブの数までスケールアップし、アクティブなジョブがない場合は 0 にスケールダウンします。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
# minRunners: 0

例: ランナーの最小数

プロパティは任意の数に設定でき、ARC は、指定された数のランナーがアクティブで、ランナー スケール セットに割り当てられたジョブをいつでも引き受けることができるようにします。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
# maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

例: ランナーの最大数と最小数を設定する

この構成では、Actions Runner Controller は最大 ランナーまでスケールアップされ、ジョブが完了すると ランナーにスケールダウンされます。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 30

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 20

例: ジョブ キューのドレイン

特定のシナリオでは、ジョブ キューをドレインして問題のトラブルシューティングを行ったり、クラスターに対するメンテナンスを実行したりできます。 両方のプロパティを に設定すると、新しいジョブが使用可能になり割り当てられたときに、Actions Runner Controller で新しいランナー ポッドは作成されません。

## maxRunners is the max number of runners the auto scaling runner set will scale up to.
maxRunners: 0

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

カスタム TLS 証明書

一部の環境では、カスタム証明機関 (CA) によって署名された TLS 証明書が必要です。 カスタム証明機関の証明書はコントローラーまたはランナー コンテナーにバンドルされていないため、それぞれの信頼ストアに取り込む必要があります。

githubServerTLS:
  certificateFrom:
    configMapKeyRef:
      name: config-map-name
      key: ca.crt
  runnerMountPath: /usr/local/share/ca-certificates/

これを行う場合は、Privacy Enhanced Mail (PEM) 形式を使用していること、および証明書の拡張子が であることを確認します。 それ以外は無視されます。

コントローラーで次のアクションが実行されます。

• で指定された証明書を含む ボリュームを作成します。
• そのボリュームをパス にマウントします。
• 環境変数をその同じパスに設定します。
• 環境変数を に設定します (バージョン の時点では、これにより、ホストで証明書を再読み込みするようランナーに指示します)。

ARC はランナー ポッド テンプレートで設定された値を優先し、上書きしません。

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

プライベート コンテナー レジストリを使用する

プライベート コンテナー レジストリを使用するには、コントローラー イメージとランナー イメージをプライベート コンテナー レジストリにコピーします。 次に、それらのイメージへのリンクを構成し、 と の値を設定します。

コントローラー イメージを構成する

ファイルのコピーを更新し、 プロパティを次のように設定できます。

image:
  repository: "custom-registry.io/gha-runner-scale-set-controller"
  pullPolicy: IfNotPresent
  # Overrides the image tag whose default is the chart appVersion.
  tag: "0.4.0"

imagePullSecrets:
  - name: <registry-secret-name>

リスナー コンテナーは、コントローラーに対して定義された を継承します。

ランナー イメージを構成する

ファイルのコピーを更新して プロパティを設定し、特定のユース ケースのランナー ポッドを構成できます。

構成の例を次に示します。

template:
  spec:
    containers:
      - name: runner
        image: "custom-registry.io/actions-runner:latest"
        imagePullPolicy: Always
        command: ["/home/runner/run.sh"]
    imagePullSecrets:
      - name: <registry-secret-name>

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

ランナー ポッドのポッド仕様を更新する

ランナー ポッドの PodSpec を完全にカスタマイズできます。指定した構成がコントローラーによって適用されます。 ポッドの仕様の例を次に示します。

template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
        securityContext:
          readOnlyRootFilesystem: true
          allowPrivilegeEscalation: false
          capabilities:
            add:
              - NET_ADMIN

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

リスナー ポッドのポッド仕様を更新する

リスナー ポッドの PodSpec を完全にカスタマイズできます。指定した構成がコントローラーによって適用されます。 ポッドの仕様の例を次に示します。

listenerTemplate:
  spec:
    containers:
    # If you change the name of the container, the configuration will not be applied to the listener,
    # and it will be treated as a sidecar container.
    - name: listener
      securityContext:
        runAsUser: 1000
      resources:
        limits:
          cpu: "1"
          memory: 1Gi
        requests:
          cpu: "1"
          memory: 1Gi

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

コンテナーに Docker-in-Docker または Kubernetes モードを使用する

コンテナー ジョブおよびサービス、またはコンテナー アクションを使っている場合は、 の値を または に設定する必要があります。 カスタム コンテナー モードを使うには、 をコメント アウトするか削除し、 セクションに必要な構成を追加します。 「コンテナー モードのカスタマイズ」を参照してください。

• コンテナー ジョブとサービスの詳細については、「AUTOTITLE」を参照してください。
• コンテナー アクションの詳細については、「AUTOTITLE」を参照してください。

Docker-in-Docker モードを使用する

Docker-in-Docker モードは、Docker コンテナー内部で Docker を実行できる構成です。 この構成では、作成されたランナー ポッドごとに、ARC で次のコンテナーが作成されます。

• コンテナー
• コンテナー
• コンテナー

Docker-in-Docker モードを有効にするには、設定を以下のように行ってください。

containerMode:
  type: "dind"

は、次の既定の構成に更新されます。

Kubernetes のバージョンでは、サイドカー コンテナーを使用して Docker デーモンが実行されます。

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-runner:latest
        command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/docker.sock
          - --group=$(DOCKER_GROUP_GID)
        env:
          - name: DOCKER_GROUP_GID
            value: "123"
        securityContext:
          privileged: true
        restartPolicy: Always
        startupProbe:
          exec:
            command:
              - docker
              - info
          initialDelaySeconds: 0
          failureThreshold: 24
          periodSeconds: 5
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
          - name: RUNNER_WAIT_FOR_DOCKER_IN_SECONDS
            value: "120"
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

Kubernetes のバージョンでは、次の構成が適用されます。

template:
  spec:
    initContainers:
      - name: init-dind-externals
        image: ghcr.io/actions/actions-runner:latest
        command:
          ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
        volumeMounts:
          - name: dind-externals
            mountPath: /home/runner/tmpDir
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        command: ["/home/runner/run.sh"]
        env:
          - name: DOCKER_HOST
            value: unix:///var/run/docker.sock
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
      - name: dind
        image: docker:dind
        args:
          - dockerd
          - --host=unix:///var/run/docker.sock
          - --group=$(DOCKER_GROUP_GID)
        env:
          - name: DOCKER_GROUP_GID
            value: "123"
        securityContext:
          privileged: true
        volumeMounts:
          - name: work
            mountPath: /home/runner/_work
          - name: dind-sock
            mountPath: /var/run
          - name: dind-externals
            mountPath: /home/runner/externals
    volumes:
      - name: work
        emptyDir: {}
      - name: dind-sock
        emptyDir: {}
      - name: dind-externals
        emptyDir: {}

の 値は自動的に挿入され、オーバーライドできません。 このセットアップをカスタマイズする場合は、設定 を解除してから、この構成をコピーし、 ファイルのコピーに直接適用する必要があります。

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

Kubernetes モードを使用する

Kubernetes モードでは、ARC はランナー コンテナー フックを使用して同じ名前空間に新しいポッドを作成し、サービス、コンテナー ジョブ、またはアクションを実行します。

前提条件

Kubernetes モードでは、ランナー ポッドとコンテナー ジョブ ポッドの間でジョブ データを共有するための 2 つの方法がサポートされています。 永続ボリュームを使用できます。これは、同時書き込みアクセスを必要とするシナリオで推奨されるオプションのままです。また、コンテナー ライフサイクル フックを使用して、RWX ボリュームに依存せずに、ポッド間でジョブ ファイル システムを復元およびエクスポートすることもできます。 ライフサイクル フック アプローチでは、ローカル ストレージを利用することで移植性とパフォーマンスが向上し、共有ストレージのないクラスターに最適です。

永続ボリュームを使用した Kubernetes モードの構成

Kubernetes モードを使用するには、ランナー ポッドが要求できる永続ボリュームを作成し、必要に応じてこれらのボリュームを自動的にプロビジョニングするソリューションを使用する必要があります。 テスト用には、OpenEBS などのソリューションを使用できます。

Kubernetes モードを有効にするには、ファイルで を に設定します。

containerMode:
  type: "kubernetes"
  kubernetesModeWorkVolumeClaim:
    accessModes: ["ReadWriteOnce"]
    storageClassName: "dynamic-blob-storage"
    resources:
      requests:
        storage: 1Gi

その他の Helm 構成のオプションについては、ARC リポジトリの values.yaml を参照してください。

コンテナー ライフサイクル フックを使用した Kubernetes モードの構成

コンテナー ライフサイクル フックを使用して Kubernetes モードを有効にするには、を ファイルでに設定します。

containerMode:
  type: "kubernetes-novolume"

Kubernetes モードのトラブルシューティング

Kubernetes モードが有効になっている場合、コンテナー ジョブで構成されていないワークフローは、次のようなエラーで失敗します。

Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator.

ジョブ コンテナーのないジョブの実行を許可するには、ランナー コンテナーで を に設定します。 これにより、ランナーにこのチェックを無効にするよう指示されます。

  template:
    spec:
      containers:
        - name: runner
          image: ghcr.io/actions/actions-runner:latest
          command: ["/home/runner/run.sh"]
          env:
            - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER
              value: "false"

コンテナー モードのカスタマイズ

Helm チャートの ファイルで を設定する場合は、次のいずれかの値を使用できます。

• または
• kubernetes

に対して設定した値に応じて、 Helm チャートの ファイルの セクションに構成が自動的に挿入されます。

• 構成 を確認してください。
• 構成 を確認してください。

仕様をカスタマイズするには、コメントアウトまたは削除し、必要な構成をセクションに追加してください。

例: の実行

の実行を決定する前に、既知の制限事項を認識していることを確認してください。

Kubernetes のバージョンでは、サイドカー コンテナーを使用して Docker デーモンが実行されます。

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >> /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///run/user/1001/docker.sock
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      restartPolicy: Always
      startupProbe:
        exec:
          command:
            - docker
            - info
        initialDelaySeconds: 0
        failureThreshold: 24
        periodSeconds: 5
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

Kubernetes のバージョンでは、次の構成を適用できます。

## githubConfigUrl is the GitHub url for where you want to configure runners
## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg
githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller"

## githubConfigSecret is the k8s secrets to use when auth with GitHub API.
## You can choose to use GitHub App or a PAT token
githubConfigSecret: my-super-safe-secret

## maxRunners is the max number of runners the autoscaling runner set will scale up to.
maxRunners: 5

## minRunners is the min number of idle runners. The target number of runners created will be
## calculated as a sum of minRunners and the number of jobs assigned to the scale set.
minRunners: 0

runnerGroup: "my-custom-runner-group"

## name of the runner scale set to create. Defaults to the helm release name
runnerScaleSetName: "my-awesome-scale-set"

## template is the PodSpec for each runner Pod
## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec
template:
  spec:
    initContainers:
    - name: init-dind-externals
      image: ghcr.io/actions/actions-runner:latest
      command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"]
      volumeMounts:
        - name: dind-externals
          mountPath: /home/runner/tmpDir
    - name: init-dind-rootless
      image: docker:dind-rootless
      command:
        - sh
        - -c
        - |
          set -x
          cp -a /etc/. /dind-etc/
          echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd
          echo 'runner:x:1001:' >> /dind-etc/group
          echo 'runner:100000:65536' >> /dind-etc/subgid
          echo 'runner:100000:65536' >> /dind-etc/subuid
          chmod 755 /dind-etc;
          chmod u=rwx,g=rx+s,o=rx /dind-home
          chown 1001:1001 /dind-home
      securityContext:
        runAsUser: 0
      volumeMounts:
        - mountPath: /dind-etc
          name: dind-etc
        - mountPath: /dind-home
          name: dind-home
    containers:
    - name: runner
      image: ghcr.io/actions/actions-runner:latest
      command: ["/home/runner/run.sh"]
      env:
        - name: DOCKER_HOST
          value: unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
    - name: dind
      image: docker:dind-rootless
      args:
        - dockerd
        - --host=unix:///run/user/1001/docker.sock
      securityContext:
        privileged: true
        runAsUser: 1001
        runAsGroup: 1001
      volumeMounts:
        - name: work
          mountPath: /home/runner/_work
        - name: dind-sock
          mountPath: /run/user/1001
        - name: dind-externals
          mountPath: /home/runner/externals
        - name: dind-etc
          mountPath: /etc
        - name: dind-home
          mountPath: /home/runner
    volumes:
    - name: work
      emptyDir: {}
    - name: dind-externals
      emptyDir: {}
    - name: dind-sock
      emptyDir: {}
    - name: dind-etc
      emptyDir: {}
    - name: dind-home
      emptyDir: {}

runner-container-hooks について

ランナーは、コンテナー ジョブ、サービス コンテナーまたは Docker アクションを使用するワークフローの実行を検出すると、runner-container-hooks を呼び出して新しいポッドを作成します。 ランナーは、runner-container-hooks に依存して Kubernetes API を呼び出し、ランナー ポッドと同じ名前空間に新しいポッドを作成します。 この新しく作成されたポッドは、コンテナー ジョブ、サービス コンテナーまたは Docker アクションの実行に使用されます。 詳細については、 リポジトリを参照してください。

フック拡張機能を構成する

ARC バージョン 0.4.0 以降、runner-container-hooks ではフック拡張機能がサポートされています。 これらを使用して、runner-container-hooks によって作成されたポッドを構成できます。 たとえば、フック拡張機能を使用して、ポッドにセキュリティ コンテキストを設定できます。 フック拡張機能を使用すると、runner-container-hooks によって作成されたポッドの PodSpec を更新するために使用される YAML ファイルを指定できます。

フック拡張機能を構成するには、2 つのオプションがあります。

• カスタム ランナー イメージに保存する。 PodSpec は、カスタム ランナー イメージ内の任意の場所にある YAML ファイルに格納できます。 詳しくは、「AUTOTITLE」をご覧ください。
• ConfigMap に格納する。 PodSpec を使用して構成マップを作成し、その構成マップをランナー コンテナーにマウントできます。 詳細については、Kubernetes ドキュメントの「ConfigMaps」を参照してください。

例: 構成マップを使用して securityContext を設定する

ランナー ポッドと同じ名前空間に構成マップを作成します。 次に例を示します。

apiVersion: v1
kind: ConfigMap
metadata:
  name: hook-extension
  namespace: arc-runners
data:
  content: |
    metadata:
      annotations:
        example: "extension"
    spec:
      containers:
        - name: "$job" # Target the job container
          securityContext:
            runAsUser: 1000

• フィールドと フィールドは、キーが予約されていない限りそのまま追加されます。 フィールドと フィールドをオーバーライドすることはできません。
• PodSpec フィールドの大部分は、指定されたテンプレートから適用され、Helm チャート ファイルから渡された値をオーバーライドします。
• 追加のボリュームを指定すると、ランナーによって指定されたデフォルトのボリュームに追加されます。
• は割り当てられた名前に基づいてマージされます。
• コンテナーの名前が の場合:
  • フィールドと フィールドは無視されます。
  • 、、 フィールドは、フックによって作成された既定のコンテナー仕様に追加されます。
  • 残りのフィールドは、指定されたとおりに適用されます。
• コンテナーの名前が ではない場合、フィールドはポッド定義にそのまま追加されます。

メトリックの有効化

ARC は、ランナー、ジョブ、ワークフローの実行に費やされた時間に関するメトリックを出力できます。 メトリックを使用すると、輻輳の特定、ARC デプロイの正常性の監視、使用状況の傾向の視覚化、リソース使用量の最適化などの多くのユース ケースを行うことができます。 メトリックは、コントローラー マネージャーポッドとリスナー ポッドによって Prometheus 形式で出力されます。 詳細については、 Prometheus ドキュメントの「表示形式」を参照してください。

ARC のメトリックを有効にするには、 グラフの ファイルで プロパティを構成します。

構成ファイルの例を次に示します。

metrics:
  controllerManagerAddr: ":8080"
  listenerAddr: ":8080"
  listenerEndpoint: "/metrics"

これらのプロパティが構成されると、コントローラー マネージャーポッドとリスナー ポッドは、 ファイルで指定したポートにバインドされた listenerEndpoint を介してメトリックを出力します。 上記の例では、エンドポイントは で、ポートは です。 このエンドポイントを使用して、コントローラー マネージャーとリスナー ポッドからメトリックをスクレーピングできます。

メトリックをオフにするには、 オブジェクトとそのプロパティを削除またはコメントアウトして ファイルを更新します。

ARCに使用可能なメトリックは次のとおりです。

次の表は、コントローラー マネージャーポッドとリスナー ポッドによって出力されるメトリックを示しています。

1

Dependabot と code scanning での ARC の使用

Actions Runner Controller を使用して、GitHub Enterprise Server インスタンスのための専用ランナーを作成し、これにより Dependabot がエンタープライズのリポジトリで使用される依存関係の保護と維持を支援できるようにします。 詳しくは、「AUTOTITLE」をご覧ください。

また、ARC をCodeQL と使うと、コード内の脆弱性とエラーを特定することができます。 詳しくは、「AUTOTITLE」をご覧ください。 既に code scanning を使用していて、既定のセットアップを使用するようにランナー スケール セットを構成する場合は、 を設定します。 code scanning の既定のセットアップの詳細については、「AUTOTITLE」を参照してください。

Actions Runner Controller では、ジョブを特定のランナー スケール セットにルーティングするのに複数のラベルを利用しません。 代わりに、Dependabot の更新やcode scanningで CodeQL を使用してランナー スケール セットを指定するには、Helm チャートに説明的なインストール名 (例: や など) を使用します。 その後、ワークフロー内の値を単一のラベルとしてインストール名に設定し、指定されたランナーのスケールセットを使って、Dependabot の更新や code scanning ジョブを実行できます。

code scanning の既定の設定を使っている場合、分析ではインストール名 でランナー スケール セットが自動的に検索されますが、個々のリポジトリで異なるランナー スケール セットを使用できるように、構成でカスタム名を指定することもできます。 「AUTOTITLE」を参照してください。

ARC のアップグレード

Helm を使用した CRD のアップグレードまたは削除はサポートされていないため、Helm を使用して ARC をアップグレードすることはできません。 詳細については、Helm ドキュメントの「リソース定義のカスタマイズ」を参照してください。 ARC を新しいバージョンにアップグレードするには、次の手順を実行する必要があります。

1. のすべてのインストールをアンインストールします。
2. リソースがクリーンアップされるまで待ちます。
3. ARC をアンインストールします。
4. 現在インストールしているバージョンからアップグレードされたバージョンに CRD に変更がある場合は、 API グループに関連付けられているすべての CRD を削除します。
5. ARC を再インストールします。

詳細については、「ランナー スケール セットの配置」を参照してください。

ARC をアップグレードしたいが、ダウンタイムが懸念される場合は、高可用性構成で ARC をデプロイして、ランナーが常に使用可能なようにできます。 詳細については、「高可用性と自動フェールオーバー」を参照してください。

          [community でサポートされているバージョンの ARC](https://github.com/actions/actions-runner-controller/discussions/2775) からGitHubサポートされているバージョンへの移行は、アーキテクチャの大幅な変更です。 GitHubサポートされているバージョンには、ARC の多くのコンポーネントの再設計が含まれます。 これは、ソフトウェアのマイナー アップグレードではありません。 このような理由から、まず運用環境に一致するステージング環境で新しいバージョンをテストすることをお勧めします。 これにより、運用環境にデプロイする前のセットアップの安定性と信頼性が確保されます。

カナリア イメージのデプロイ

コントローラー マネージャー コンテナー イメージのカナリア リリースを使用して、リリース前に機能をテストできます。 カナリア イメージはタグ形式 で公開されます。 詳細については、Container registry をご覧ください。

1. gha-runner-scale-set-controllerファイル内の内容を次のように更新します。
2. ファイル [file] 内のフィールド [field] の内容を次のように更新します。
3. 更新された Helm チャートと ファイルを使用して ARC を再インストールします。

高可用性/自動フェールオーバー

ARC は、高可用性 (アクティブ/アクティブ) 構成でデプロイできます。 2 つの異なる Kubernetes クラスターが別々のリージョンにデプロイされている場合は、両方のクラスターに ARC をデプロイし、同じ クラスターを使用するようにランナー スケール セットを構成できます。 これを行うには、各ランナー スケール セットを個別のランナー グループに割り当てる必要があります。 たとえば、1 つのランナー スケール セットが に属し、もう 1 つのランナー スケール セットが に属している限り、 という名前で 2 つのランナー スケール セットを指定できます。 ランナー スケール セットをランナー グループに割り当てる方法については、「AUTOTITLE」を参照してください。

両方のランナー スケール セットがオンラインの場合、それらに割り当てられたジョブは任意に分散されます (割り当てレース)。 ジョブ割り当てアルゴリズムを構成することはできません。 クラスターの 1 つがダウンした場合、他のクラスターのランナー スケール セットは、介入や構成の変更なしで通常どおりジョブを取得し続けます。

組織間で ARC を使用する

Actions Runner Controller の単一インストールで 1 つまたは複数のランナー スケール セットを構成できます。 これらのランナー スケール セットは、リポジトリ、Organization、または Enterprise に登録できます。 ランナー グループを使用して、これらのランナー スケール セットの権限境界を制御することもできます。

ベスト プラクティスとして、Organization ごとに固有の名前空間を作成します。 また、ランナー グループごと、またはランナー スケール セットごとに名前空間を作成することもできます。 それぞれの名前空間に、必要な数だけランナー スケール セットをインストールできます。 これにより、最高レベルの分離が提供され、セキュリティが向上します。 認証には GitHub Apps を使用し、ランナー スケール セットごとにきめ細かいアクセス許可を定義できます。

法務上の通知

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.