GitHub Actions Self-Hosted Runner 大規模運用とセキュリティハードニングガイド

┌─────────────────┐     ┌──────────────────────┐
│   GitHub.com    │     │   Kubernetes Cluster  │
│                 │     │                       │
│  Job Queue      │◄───►│  ARC Controller       │
│  (workflow_job)  │     │    │                  │
│                 │     │    ▼                  │
│  Scale Set API  │◄───►│  ScaleSet Listener    │
│                 │     │    │                  │
└─────────────────┘     │    ▼                  │
                        │  EphemeralRunnerSet   │
                        │    │                  │
                        │    ├─► Runner Pod 1   │
                        │    ├─► Runner Pod 2   │
                        │    └─► Runner Pod N   │
                        └──────────────────────┘

# ARCコントローラー用の名前空間を作成
kubectl create namespace arc-systems

# Helmリポジトリの追加
helm install arc \
  --namespace arc-systems \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \
  --version 0.10.1

# GitHub Appシークレットの作成
kubectl create secret generic github-app-secret \
  --namespace arc-runners \
  --from-literal=github_app_id=12345 \
  --from-literal=github_app_installation_id=67890 \
  --from-file=github_app_private_key=./private-key.pem

# values.yaml - Runner Scale Set設定
githubConfigUrl: 'https://github.com/my-org'
githubConfigSecret: github-app-secret

# オートスケーリング設定
minRunners: 2 # 最小待機ランナー（コールドスタート防止）
maxRunners: 30 # 最大ランナー数（クラスターリソースを考慮）

# ランナーグループの指定（Enterprise/Orgレベル）
runnerGroup: 'production-runners'

# コンテナモード設定
containerMode:
  type: 'kubernetes'
  kubernetesModeWorkVolumeClaim:
    accessModes: ['ReadWriteOnce']
    storageClassName: 'gp3'
    resources:
      requests:
        storage: 50Gi

# Podテンプレートのカスタマイズ
template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/actions/actions-runner:latest
        resources:
          requests:
            cpu: '2'
            memory: '4Gi'
          limits:
            cpu: '4'
            memory: '8Gi'
        env:
          - name: RUNNER_GRACEFUL_STOP_TIMEOUT
            value: '60'
    # ノード選択（ビルド専用ノードプール）
    nodeSelector:
      workload-type: ci-runner
    tolerations:
      - key: 'ci-runner'
        operator: 'Equal'
        value: 'true'
        effect: 'NoSchedule'

# Runner Scale Setのデプロイ
helm install arc-runner-set \
  --namespace arc-runners \
  --create-namespace \
  -f values.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
  --version 0.10.1

# Dockerfile.runner - カスタムGitHub Actions Runnerイメージ
FROM ubuntu:22.04 AS base

# システムパッケージのインストール（最小限に維持）
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    git \
    jq \
    unzip \
    zip \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Runner専用ユーザーの作成
RUN useradd -m -d /home/runner -s /bin/bash runner

# Runnerバイナリのインストール
ARG RUNNER_VERSION=2.321.0
RUN curl -fsSL -o runner.tar.gz \
    "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz" \
    && mkdir -p /home/runner/actions-runner \
    && tar xzf runner.tar.gz -C /home/runner/actions-runner \
    && rm runner.tar.gz \
    && /home/runner/actions-runner/bin/installdependencies.sh

# Node.js 22 LTSのインストール
RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

# Docker CLIのインストール（DinDではなくCLIのみ）
RUN curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker.gpg \
    && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu jammy stable" \
    > /etc/apt/sources.list.d/docker.list \
    && apt-get update && apt-get install -y docker-ce-cli \
    && rm -rf /var/lib/apt/lists/*

# 自動更新の無効化（イメージビルドでバージョン管理）
ENV RUNNER_MANUALLY_TRAP_SIG=1
ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1

# 権限設定とユーザー切替
RUN chown -R runner:runner /home/runner
USER runner
WORKDIR /home/runner/actions-runner

ENTRYPOINT ["./run.sh"]

# イメージのビルドとプッシュ
docker build -t ghcr.io/my-org/actions-runner:v2.321.0-custom -f Dockerfile.runner .
docker push ghcr.io/my-org/actions-runner:v2.321.0-custom

# ワークフローでephemeralランナーの使用を確認
runs-on: arc-runner-set # ARCはデフォルトでephemeral

# VMベースのself-hostedランナーの場合
# ./config.sh --ephemeralフラグで登録

# network-policy.yaml - Runner Podネットワーク制限
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: runner-network-policy
  namespace: arc-runners
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/component: runner
  policyTypes:
    - Egress
    - Ingress
  ingress: [] # 外部からRunnerへのインバウンドを遮断
  egress:
    # GitHub APIとActionsサービス
    - to:
        - ipBlock:
            cidr: 140.82.112.0/20 # github.com
        - ipBlock:
            cidr: 185.199.108.0/22 # GitHub Pages/CDN
      ports:
        - protocol: TCP
          port: 443
    # 内部コンテナレジストリ
    - to:
        - namespaceSelector:
            matchLabels:
              name: registry
      ports:
        - protocol: TCP
          port: 5000
    # DNS
    - to: []
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53

# rbac.yaml - Runner ServiceAccount最小権限
apiVersion: v1
kind: ServiceAccount
metadata:
  name: runner-sa
  namespace: arc-runners
automountServiceAccountToken: false # K8s APIトークンの自動マウントを無効化
---
# 必要な場合にのみ最小権限のRoleをバインド
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: runner-minimal
  namespace: arc-runners
rules: [] # デフォルトで権限なし

# 安全なワークフロー作成パターン
name: Secure CI Pipeline
on:
  pull_request:
    branches: [main]

# 最小権限トークン
permissions:
  contents: read
  packages: read

jobs:
  build:
    runs-on: arc-runner-set
    steps:
      # SHA固定でActionを使用（タグではない）
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      # 環境変数にシークレットを直接公開しない
      - name: Build
        run: |
          echo "Building..."
        env:
          # シークレットは必要なステップでのみ注入
          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

jobs:
  build:
    runs-on: arc-runner-set
    steps:
      - uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
        with:
          egress-policy: audit # まずauditでトラフィックパターンを把握
          # パターン把握後にblockに切替
          # egress-policy: block
          # allowed-endpoints: >
          #   github.com:443
          #   registry.npmjs.org:443
          #   ghcr.io:443

# ARC Runner Scale Set values.yamlにPVCを追加
template:
  spec:
    containers:
      - name: runner
        image: ghcr.io/my-org/actions-runner:latest
        volumeMounts:
          - name: cache-volume
            mountPath: /opt/cache
        env:
          - name: RUNNER_TOOL_CACHE
            value: /opt/cache/tool-cache
          - name: npm_config_cache
            value: /opt/cache/npm
          - name: GOPATH
            value: /opt/cache/go
    volumes:
      - name: cache-volume
        persistentVolumeClaim:
          claimName: runner-cache-pvc
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: runner-cache-pvc
  namespace: arc-runners
spec:
  accessModes:
    - ReadWriteMany # 複数のRunner Podが同時アクセス
  storageClassName: efs # AWS EFSまたはNFS
  resources:
    requests:
      storage: 100Gi

# MinIOベースのキャッシュサーバーデプロイ（同じVPC/リージョン内）
apiVersion: apps/v1
kind: Deployment
metadata:
  name: actions-cache-server
  namespace: arc-systems
spec:
  replicas: 1
  selector:
    matchLabels:
      app: actions-cache
  template:
    spec:
      containers:
        - name: minio
          image: minio/minio:latest
          args: ['server', '/data', '--console-address', ':9001']
          env:
            - name: MINIO_ROOT_USER
              valueFrom:
                secretKeyRef:
                  name: minio-credentials
                  key: user
            - name: MINIO_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: minio-credentials
                  key: password
          volumeMounts:
            - name: data
              mountPath: /data
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: minio-data-pvc

# ワークフローでBuildKitレジストリキャッシュを活用
- name: Build and Push
  uses: docker/build-push-action@48aba3b46d1b1fec4febb7c5d0c644b249a11355 # v6
  with:
    push: true
    tags: ghcr.io/my-org/my-app:${{ github.sha }}
    cache-from: type=registry,ref=ghcr.io/my-org/my-app:buildcache
    cache-to: type=registry,ref=ghcr.io/my-org/my-app:buildcache,mode=max

# Prometheus ServiceMonitor設定
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: arc-controller-monitor
  namespace: arc-systems
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: gha-runner-scale-set-controller
  endpoints:
    - port: metrics
      interval: 30s
      path: /metrics

# Alertmanagerルール
groups:
  - name: arc-runner-alerts
    rules:
      # ランナープール枯渇の警告
      - alert: RunnerPoolExhausted
        expr: |
          gha_runner_scale_set_desired_replicas
          >= gha_runner_scale_set_max_replicas * 0.9
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: 'ランナープールが90%以上使用中'
          description: 'maxRunnersの増設またはワークフローの最適化が必要'

      # ランナー登録失敗の検知
      - alert: RunnerRegistrationFailed
        expr: |
          rate(gha_runner_scale_set_registration_failures_total[5m]) > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: 'ランナー登録失敗が発生'
          description: 'GitHub App認証またはネットワークの確認が必要'

      # Pending Pod長時間待機
      - alert: RunnerPodPending
        expr: |
          kube_pod_status_phase{namespace="arc-runners", phase="Pending"} > 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: 'Runner Podが10分以上Pending状態'
          description: 'ノードリソース不足またはPVCバインディング失敗の可能性'

# 1. Listener Podのログ確認
kubectl logs -n arc-systems -l app.kubernetes.io/component=runner-scale-set-listener --tail=100

# 2. よくある原因：GitHub App認証の期限切れ
# - 秘密鍵ファイルの確認
# - Appインストレーションの状態確認（org settings > GitHub Apps）

# 3. ネットワーク問題：GitHub APIにアクセスできない
kubectl exec -n arc-systems deploy/arc-gha-runner-scale-set-controller -- \
  curl -s https://api.github.com/meta | jq '.actions[]'

kubectl create secret generic github-app-secret \
  --namespace arc-runners \
  --from-literal=github_app_id=12345 \
  --from-literal=github_app_installation_id=67890 \
  --from-file=github_app_private_key=./new-private-key.pem \
  --dry-run=client -o yaml | kubectl apply -f -

# Controllerの再起動
kubectl rollout restart deployment -n arc-systems arc-gha-runner-scale-set-controller

# Podイベントの確認
kubectl describe pod -n arc-runners -l actions.github.com/scale-set-name=arc-runner-set

# よくある原因別の対応
# 1. ノードリソース不足
kubectl top nodes
# -> Cluster Autoscalerが動作しているか確認、またはmaxRunnersを下方修正

# 2. PVCバインディング待ち
kubectl get pvc -n arc-runners
# -> StorageClass設定、アベイラビリティゾーンの不一致を確認

# 3. イメージPull失敗
kubectl get events -n arc-runners --sort-by='.lastTimestamp' | grep -i pull
# -> イメージタグ、レジストリ認証を確認

# Runner登録状態の確認
kubectl get ephemeralrunner -n arc-runners

# Runnerラベルの確認（runs-onと一致する必要がある）
kubectl get autoscalingrunnersets -n arc-runners -o yaml | grep -A5 labels

# GitHubでRunnerグループ設定の確認
# Settings > Actions > Runner groups > 該当グループにリポジトリが含まれているか確認

# 現在のRunnerバージョンの確認
kubectl exec -n arc-runners -it <runner-pod> -- ./config.sh --version

# イメージの更新（values.yaml修正後）
helm upgrade arc-runner-set \
  --namespace arc-runners \
  -f values.yaml \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

# 用途別Runner Scale Setの分離
# 1. 一般CI（軽量テスト、リント）
# values-ci-light.yaml
minRunners: 2
maxRunners: 20
template:
  spec:
    containers:
      - name: runner
        resources:
          requests:
            cpu: "1"
            memory: "2Gi"

# 2. ビルド専用（コンパイル、Dockerビルド）
# values-ci-build.yaml
minRunners: 1
maxRunners: 10
template:
  spec:
    containers:
      - name: runner
        resources:
          requests:
            cpu: "4"
            memory: "8Gi"

# 3. GPUワークロード（MLモデルテスト）
# values-gpu.yaml
minRunners: 0
maxRunners: 4
template:
  spec:
    containers:
      - name: runner
        resources:
          limits:
            nvidia.com/gpu: 1
    nodeSelector:
      accelerator: nvidia-a10g

template:
  spec:
    terminationGracePeriodSeconds: 3600 # 最大1時間待機
    containers:
      - name: runner
        env:
          - name: RUNNER_GRACEFUL_STOP_TIMEOUT
            value: '3500' # terminationGracePeriodSecondsより少し短く

# Karpenter NodePool例（CIランナー専用）
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: ci-runners
spec:
  template:
    metadata:
      labels:
        workload-type: ci-runner
    spec:
      taints:
        - key: ci-runner
          value: 'true'
          effect: NoSchedule
      requirements:
        - key: kubernetes.io/arch
          operator: In
          values: ['amd64']
        - key: karpenter.sh/capacity-type
          operator: In
          values: ['on-demand', 'spot']
        - key: node.kubernetes.io/instance-type
          operator: In
          values: ['m7i.xlarge', 'm7i.2xlarge', 'm6i.xlarge', 'm6i.2xlarge']
  limits:
    cpu: 200
    memory: 400Gi
  disruption:
    consolidationPolicy: WhenEmpty
    consolidateAfter: 60s