Terraformのライセンス変更以降、OpenTofuへ移行したいという相談は確実に増えています。とはいえ現場の本音は「理屈は分かるが、stateが壊れたら終わる」「本番を止めずに移行できるのか不安」です。

結論から言うと、移行は十分可能です。ただし「CLIを置き換えるだけ」で済むケースは限定的で、実際は providerバージョン整合・state lock・CI/CD・運用Runbook までまとめて整える必要があります。

本記事では、既にTerraformを本番運用しているチーム向けに、OpenTofuへ段階移行する実践手順をまとめます。

1. 移行方針を先に決める

最初に決めるべきは「一気に切り替えるか」「ワークスペース単位で段階移行するか」です。実務では次の方針が安全です。

1. 低リスク環境（dev/sandbox）から先行
2. 本番は最終フェーズで移行
3. 旧TerraformとOpenTofuを一定期間並行運用
4. ロールバック手順を文書化してから実施

この順序を守るだけで、移行事故の大半を避けられます。

2. 互換性の棚卸し（最重要）

まずは現状のIaC資産を棚卸しします。

• Terraformバージョン（例: 1.5.x / 1.6.x）
• 使用provider（AWS/Azure/GCP/Kubernetes等）
• backend（S3 + DynamoDB lock、Terraform Cloud、GCSなど）
• moduleの参照方式（registry / git / local）
• CI実行環境（GitHub Actions, GitLab CI, Jenkins）

2.1 依存を固定化してから移行する

.terraform.lock.hcl を必ずコミットし、providerを固定します。移行時にproviderまで同時更新すると、差分原因の切り分けが困難になります。

1
2
3
4
5
6
7
8
9

terraform {
  required_version = ">= 1.6.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.40"
    }
  }
}

移行フェーズでは「ツール差分」と「provider差分」を分離してください。

3. ローカル検証の基本手順

OpenTofuを導入したら、既存プロジェクトで次を実行します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 現状確認
terraform version

# OpenTofu側確認
tofu version

# 初期化（既存backendを利用）
tofu init -upgrade=false

# 差分確認
 tofu plan -out=tfplan

plan が完全一致しない場合、いきなり適用してはいけません。主な原因は以下です。

• providerの暗黙更新
• data sourceの評価タイミング差
• 標準関数・型変換の微差
• module内部のversion制約

差分は「構文差分」より「実行時評価差分」で出ることが多い点に注意してください。

4. Stateを守る設計（壊したら復旧が重い）

IaC移行の本質的リスクはstateです。ここを守るために、以下を移行前チェックリストに組み込みます。

• state backendのバックアップ取得
• lock機構が有効か確認（DynamoDB等）
• apply 権限を移行担当者に限定
• 並列実行ジョブを停止（同時apply禁止）

4.1 S3 backendの例

1
2
3
4
5
6
7
8
9

terraform {
  backend "s3" {
    bucket         = "prod-iac-state"
    key            = "network/prod.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "terraform-locks"
    encrypt        = true
  }
}

OpenTofuでもこのbackend構成は継続利用できます。重要なのは「誰がいつlockするか」を運用で統制することです。

5. CI/CDをOpenTofu対応に置換

CLI切替はローカルだけでは不十分です。実運用ではCIがapply主体です。

5.1 GitHub Actions移行例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

name: iac-plan
on:
  pull_request:
    paths:
      - "infra/**"

jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: infra
    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.8.5
      - run: tofu init -input=false
      - run: tofu validate
      - run: tofu plan -input=false -no-color

ポイントは、tofu_version を固定し、突然のツール更新を防ぐことです。

5.2 Planの品質ゲート

• tofu fmt -check
• tofu validate
• tflint
• checkov や tfsec によるセキュリティ検査

この4点をPRゲート化すると、移行直後の品質低下を防げます。

6. 段階移行の実践フロー

本番で安全に移行するなら、次の順番が現実的です。

1. dev workspaceをOpenTofuに切替
2. 1週間運用し、差分・事故を記録
3. stg workspaceを切替
4. 本番はメンテウィンドウで切替
5. 切替後48時間は変更凍結（緊急以外apply禁止）

移行で一番危険なのは「切替当日に通常の機能変更を混ぜる」ことです。必ず分離してください。

7. よくある障害と対策

7.1 plan 差分が毎回揺れる

原因:

• data sourceに非決定的値（timestamp等）が混在
• providerバージョン不統一

対策:

• 変動値をlocalsに隔離
• provider lockを全環境で統一

7.2 import済み資源が再作成扱いになる

原因:

• module path変更
• resource address変更（count→for_each）

対策:

• moved ブロックを使い論理移動を明示
• 必要時のみ state mv を計画的に実施

7.3 lock解放漏れでapplyが詰まる

原因:

• CI異常終了
• 手動中断

対策:

• lock timeoutを定義
• 強制unlock手順をRunbook化
• Slack通知でlock継続を可視化

8. 運用Runbookに必ず入れる項目

• OpenTofuバージョン更新手順
• backend障害時の復旧手順
• lock競合時の対応フロー
• 監査ログ（誰がいつapplyしたか）
• ロールバック条件（差分件数・重大リスク判定）

「ツール移行成功」は、CLIが動くことではなく、運用が回ることです。

9. 具体的な移行チェックリスト

• .terraform.lock.hcl を全リポジトリで固定
• OpenTofu版CIテンプレート作成
• dev/stg/prodの順に移行計画作成
• stateバックアップの自動化
• lock競合監視の通知導入
• apply実行権限を限定
• 切替後の変更凍結ルールを明文化

まとめ

TerraformからOpenTofuへの移行は、単純なCLI置換ではなく IaC運用基盤の再整備 です。

• 差分原因を分離して検証する
• state保護を最優先に設計する
• CIとRunbookをセットで更新する
• 段階移行でリスクを局所化する

この4点を守れば、既存システムを止めずに移行できます。まずはdev環境で「同一plan再現性」を検証し、そこから本番へ広げるのが最短かつ安全です。

付録: 切替当日の実行チェック（時系列）

移行当日は、作業手順よりも「順番管理」が事故防止に効きます。以下は実務で使える時系列テンプレートです。

• T-30分: 変更凍結を全チームへ告知、未マージPRを棚卸し
• T-20分: tofu version と lockfile整合性確認、CI変数最終確認
• T-10分: backend到達確認、stateバックアップ取得
• T+0分: dev→stg→prodの順で tofu plan 実行（差分をレビュー）
• T+15分: 許容差分のみ tofu apply 実行、結果を監査ログへ転記
• T+30分: 主要監視（APIエラー率、レイテンシ、コスト）を15分監視

さらに、切替時に最も有効なのは「中止判断ライン」を先に決めることです。例えば、plan差分件数が想定の2倍以上 や apply失敗が2連続 の場合は即時中断し、旧フローへ戻す、といった基準を明文化しておくと現場判断がぶれません。

Kubernetes運用で一番つらい事故は、クラスタが壊れるよりも「本来防げたはずのミスがそのまま本番へ入る」ことです。たとえば、latest タグのイメージが本番に入り再現不能になる、resources 未設定でノードが詰まる、privileged コンテナが混入する。これらは人の注意力だけに依存すると必ず再発します。

そこで有効なのが Admission Policy（入場制御）です。本記事では Kyverno を使って、現場で本当に運用できるポリシー群を段階導入する手順をまとめます。単なる「denyの例」ではなく、監査→警告→強制の移行、例外管理、CI連携まで含めて解説します。

1. なぜKyvernoなのか

OPA Gatekeeper も強力ですが、Kyvernoは以下の特徴があり、初期導入が比較的スムーズです。

• YAML中心で書ける（Rego学習コストを後回しにしやすい）
• validate / mutate / generate / verifyImages を一貫して扱える
• PolicyReportにより違反可視化がしやすい
• Pod SecurityやSupply Chain対策との相性が良い

「まずルールを回し始める」目的なら、Kyvernoは現実的な選択肢です。

2. 先に決めるべき設計原則

導入前に、以下だけは先に決めておきます。

1. 導入フェーズ: Audit → Enforce を基本にする
2. 責任分界: プラットフォームチームが共通ポリシー、各チームがアプリ固有例外
3. 例外の期限: 永久例外は禁止。期限付きで必ず棚卸し
4. 観測性: 違反数・対象Namespace・上位違反ルールをダッシュボード化

この原則なしにルールだけ増やすと、運用が破綻します。

3. 最小導入手順（30〜60分）

3.1 Kyvernoのインストール

1
2
3
4
5
6
7
8
9

helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update

helm upgrade --install kyverno kyverno/kyverno \
  -n kyverno --create-namespace \
  --set admissionController.replicas=2 \
  --set backgroundController.replicas=2 \
  --set cleanupController.replicas=1 \
  --set reportsController.replicas=1

本番では可用性のため、admission/backgroundは最低2レプリカ推奨です。

3.2 まずはAuditモードで3ルール

最初に効くルールは、次の3つです。

• イメージタグに latest を禁止
• CPU/Memory requests/limits必須
• privileged: true を禁止

例: latest タグ禁止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-latest-tag
spec:
  validationFailureAction: Audit
  background: true
  rules:
    - name: validate-image-tag
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "latestタグは禁止です。固定タグまたはdigestを使用してください。"
        foreach:
          - list: "request.object.spec.containers"
            deny:
              conditions:
                any:
                  - key: "{{ element.image }}"
                    operator: Matches
                    value: ".*:latest$"

3.3 レポートで現状把握

1
2
3

kubectl get policyreport -A
kubectl get clusterpolicy
kubectl describe clusterpolicy disallow-latest-tag

導入直後は違反が大量に出るのが普通です。ここで「Kyvernoが厳しすぎる」と判断しないでください。違反は“見えていなかった負債”です。

4. 実務で効くルールセット（具体例）

4.1 リソース未設定防止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-resources
spec:
  validationFailureAction: Audit
  rules:
    - name: check-resources
      match:
        any:
          - resources:
              kinds: ["Pod"]
      validate:
        message: "全コンテナにrequests/limitsを設定してください。"
        pattern:
          spec:
            containers:
              - resources:
                  requests:
                    cpu: "?*"
                    memory: "?*"
                  limits:
                    cpu: "?*"
                    memory: "?*"

4.2 特権設定防止

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-privileged
spec:
  validationFailureAction: Enforce
  rules:
    - name: no-privileged
      match:
        any:
          - resources:
              kinds: ["Pod"]
      validate:
        message: "privilegedコンテナは禁止です。"
        pattern:
          spec:
            containers:
              - securityContext:
                  =(privileged): "false"

4.3 Digest固定の推奨（Supply Chain）

本来は digest 固定が理想です。移行期は Audit で始め、違反率が下がってから Enforce に切り替えます。

5. AuditからEnforceへ移行する基準

「何となく」で切り替えると炎上します。次の客観指標を使うと安全です。

• 直近14日で対象ポリシー違反率が5%未満
• 主要Namespace（prod/stg/shared）で違反ゼロ
• 例外申請フロー（Issue/PRテンプレート）が整備済み
• 当番がトラブル時に切り戻し手順を理解している

validationFailureAction を一括で上げるのではなく、ルール単位・Namespace単位で段階化するのがポイントです。

6. 例外運用のテンプレート

ポリシー導入で最も壊れるのは「例外管理」です。おすすめは以下。

• 例外は PolicyException で明示
• 期限（例: 14日）を必須にする
• チケット番号をannotationで必須化
• 期限切れを毎日バッチで通知

例外YAMLに expires と owner を必須化すると、放置率が一気に下がります。

7. CIに組み込んで“本番前に落とす”

クラスタ投入時に拒否されるより、PR段階で検知される方が開発体験は良いです。kyverno-cli をCIで実行します。

1

kyverno apply policies/ -r manifests/ --audit-warn

GitHub Actions例:

1
2
3
4

- name: Validate manifests with Kyverno
  run: |
    kyverno version
    kyverno apply ./policies -r ./k8s --audit-warn

これで「マージ後に初めて失敗する」パターンを減らせます。

8. よくある障害と対処

症状1: 正常なPodまで拒否される

• match条件が広すぎる可能性
• exclude で kube-system や監視系を一時除外
• まずAuditで影響範囲を確認してからEnforceへ

症状2: Admission timeoutでデプロイ遅延

• Kyvernoコンポーネントのリソース不足を確認
• policy数が多い場合、ルール統合とmatch最適化
• API Serverとのネットワーク遅延確認

症状3: レポートは出るが改善が進まない

• 違反上位3ルールに絞ってKPI化
• チーム別に違反件数を見える化
• 例外を期限付きに強制

9. 運用を続けるためのダッシュボード指標

最低限、以下を可視化してください。

• ルール別違反件数（7日移動平均）
• Namespace別違反件数
• Audit と Enforce の比率
• 期限切れ例外の件数
• deploy失敗要因のうちpolicy起因の割合

これを見ないと、ポリシーは「導入しただけ」で止まります。

10. 実践ロードマップ（最初の4週間）

• Week 1: Kyverno導入、3ルールをAuditで開始
• Week 2: 違反上位を改善、例外テンプレート導入
• Week 3: 一部NamespaceでEnforce化
• Week 4: CI連携完了、SLOに違反率を組み込み

4週間で「人頼みのレビュー文化」から「仕組みで防ぐ文化」へ移行できます。

まとめ

Kyverno導入の本質は、Kubernetesを縛ることではなく、再発するミスを設計で減らすことです。

• 最初はAuditで可視化
• 指標を持って段階的にEnforce
• 例外は期限付きで管理
• CIに前倒し検知を組み込む

この4点を守れば、ポリシーは“開発を止める壁”ではなく“事故を減らすガードレール”になります。まずは latest 禁止とリソース必須の2ルールから始めて、違反データを見ながら育てていきましょう。

Kubernetes は「自動でスケールするから安心」と思われがちですが、実運用では逆です。HPA、VPA、Cluster Autoscaler（CA）の設定が噛み合わないと、スケールアウトと再スケジューリングが衝突し、レイテンシ悪化やコスト増大を引き起こします。

本記事では、3つのオートスケーリング機構を同時運用する際の設計ポイントを、障害対応目線で整理します。

1. 役割分担を明確にする

まず前提として、各コンポーネントの責務を固定します。

• HPA: Pod 数を短期的に増減
• VPA: Pod あたりの requests/limits を中長期で最適化
• CA: ノード数を増減

この役割分担が曖昧だと、同じ問題を複数レイヤーで同時に解こうとして不安定化します。特に Web/API ワークロードでは、HPA を主軸、VPA は recommendation 中心で始めるのが安全です。

2. requests/limits が崩れていると全て失敗する

HPA の CPU 指標は requests 基準で計算されます。requests が不正確だと、HPA の判断もズレます。最初にやるべきは次です。

1. 過去 2 週間の実使用量を可視化
2. p95 使用量を requests の初期値に設定
3. limits は requests の 1.5〜2 倍で開始

極端に低い requests は「見かけの高負荷」を作り、不要スケールを誘発します。逆に高すぎる requests は CA の過剰増設を招きます。

3. HPA 指標選定の実践

CPU だけで運用すると、I/O 待ちや外部 API 待ちのボトルネックを見逃します。推奨は複合指標です。

• CPU Utilization（基本）
• メモリ使用率（リーク監視）
• RPS あたりレイテンシ（SLO 接続）
• Queue 長（非同期処理）

autoscaling/v2 では複数メトリクスを扱えるため、最初から設計しておくと後で楽です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api
  minReplicas: 3
  maxReplicas: 30
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
    - type: Pods
      pods:
        metric:
          name: http_requests_per_second
        target:
          type: AverageValue
          averageValue: "80"

4. スケール挙動を安定化する

HPA は設定次第で「増えすぎ・減りすぎ」を起こします。behavior を入れて振動を抑えます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

behavior:
  scaleUp:
    stabilizationWindowSeconds: 0
    policies:
      - type: Percent
        value: 100
        periodSeconds: 60
  scaleDown:
    stabilizationWindowSeconds: 300
    policies:
      - type: Percent
        value: 20
        periodSeconds: 60

スケールアップは素早く、スケールダウンは慎重に、が基本です。障害時の復旧速度と平常時コストのバランスを取りやすくなります。

5. VPA の安全な導入順序

VPA をいきなり Auto で入れると、Pod 再作成が頻発し、ピーク時間帯に影響することがあります。次の順序を推奨します。

1. Off で recommendation だけ収集
2. 2〜4週間データ蓄積
3. 非クリティカルなバッチ系から Auto 開始
4. API 系は Initial または手動反映を継続

この段階導入にすると、VPA が既存 SLO を壊すリスクを抑えられます。

6. HPA と VPA の衝突回避

同一 Deployment で CPU/Memory の両方を HPA と VPA が同時に強く制御すると、調整ループが競合します。現場では次の運用が現実的です。

• HPA: レプリカ数を制御（主）
• VPA: requests 最適化（従）
• クリティカルサービスは VPA recommendation を人間レビューして反映

また、メモリで OOM が起こるサービスは、HPA より先にアプリ側リーク調査を優先します。スケールで隠すと後で必ず再発します。

7. Cluster Autoscaler の盲点

CA は Pending Pod を見てノードを増やしますが、以下の条件で期待通り動きません。

• PDB が厳しすぎて eviction できない
• NodeSelector/taint 制約で配置先がない
• requests が過大で BinPacking 不可能

スケールしない時の確認手順を runbook 化しておくと、夜間障害で迷いません。

1. Pending Pod の events を確認
2. CA logs で scale-up decision を確認
3. node group の上限値と quota を確認
4. Pod 制約（affinity/taint/tolerations）を確認

8. 典型障害シナリオと対処

シナリオA: 突発トラフィックで 5xx 増加

• 兆候: CPU 90%超、pod 起動待ち
• 対処: HPA minReplicas を一時引き上げ、イメージ pull 最適化、readiness 調整
• 恒久策: 予測ピーク前の scheduled scaling を導入

シナリオB: コスト急増

• 兆候: ノード数だけ増えて利用率低い
• 対処: requests 見直し、scaleDown stabilization 調整、CA consolidate 有効化
• 恒久策: ワークロード別の node pool 分離

シナリオC: 断続的なタイムアウト

• 兆候: CPU 余裕あり、レイテンシ悪化
• 対処: 外部依存（DB/Redis/API）をトレースで確認
• 恒久策: HPA 指標に queue 長・レイテンシを追加

9. 実運用のメトリクスセット

運用ダッシュボードには、最低限次を置きます。

• HPA current/desired replicas
• Pod 起動時間（image pull + readiness）
• Pod Pending 数と理由
• Node 利用率（CPU/Memory）
• CA scale up/down イベント数
• 5xx 率と p95 latency

このセットがあると「スケーラが原因か、アプリが原因か」を 5 分以内で切り分けられます。

10. 段階的チューニング手順（4週間）

Week 1: ベースライン計測

• 現行 requests/limits と実使用量を比較
• HPA 閾値を仮設定（CPU 60%）

Week 2: 振動抑制

• behavior 追加
• scaleDown window を 300s 前後で調整

Week 3: 指標追加

• RPS/queue 指標を導入
• アラートを SLO 連動へ変更

Week 4: コスト最適化

• idle 時の minReplicas 見直し
• node pool の統廃合

この 4 週間を回すだけでも、無駄スケールと障害時復旧の両方が改善します。

11. 導入チェックリスト

• requests/limits が実使用量に基づいている
• HPA に behavior を設定済み
• VPA は recommendation 期間を経て適用している
• CA の上限値・quota・制約を定期点検している
• SLO 指標とスケーリング指標を接続している
• 典型障害シナリオの runbook がある

Kubernetes のスケーリングは、機能を有効にするだけでは安定しません。役割分担、指標設計、調整ループの制御、そして runbook をセットで整えることで、初めて「自動化が味方になる」状態を作れます。

複数リポジトリを運用していると、ほぼ同じ CI 設定を各リポジトリにコピーし続ける状態になりがちです。最初は早く見えますが、半年後には「どこに正解があるのかわからない」状態になります。セキュリティパッチを当てたいだけなのに 20 リポジトリを横断修正し、1つだけ取りこぼして監査で指摘される、というのは珍しくありません。

この問題に効くのが GitHub Actions の workflow_call を使った再利用ワークフローです。ただし、単に共通化するだけでは逆に運用事故が増えることがあります。重要なのは、共通化の粒度、権限境界、変更リリース方法を最初に設計することです。

本記事では、実運用で詰まりやすいポイントを中心に、導入から定着までを具体的に解説します。

1. 再利用ワークフローの基本方針

まず押さえるべき方針は次の 3 つです。

1. 再利用ワークフローは「プラットフォーム製品」として扱う
2. 呼び出し側（各アプリ repo）は薄く保つ
3. 破壊的変更はバージョンを切って段階移行する

「共通化＝1ファイルに全部詰め込む」ではありません。lint, test, build, deploy を1個にまとめると、対象外プロジェクトまで影響します。まずは小さく分割し、必要なものだけ組み合わせられる構造にします。

2. 推奨ディレクトリ構成

共通ワークフローを専用 repo に分離しておくと、監査や変更履歴の管理が容易になります。

1
2
3
4
5
6
7
8
9

org-ci-workflows/
  .github/workflows/
    ci-node.yml
    ci-python.yml
    security-scan.yml
    release-tag.yml
  docs/
    onboarding.md
    migration-checklist.md

呼び出し側は以下のように最小化します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

name: ci
on:
  pull_request:
  push:
    branches: [main]

jobs:
  node-ci:
    uses: your-org/org-ci-workflows/.github/workflows/ci-node.yml@v1
    with:
      node-version: "22"
      run-e2e: false
    secrets: inherit

この形の利点は、アプリチームが理解すべき YAML が減ることです。CI の標準知識が全員に伝播し、レビューも速くなります。

3. 実務で効く入力設計（inputs）

inputs は API 設計だと考えるべきです。曖昧な真偽値が増えると、挙動が読めなくなります。

悪い例

• enable_special_mode: true
• quick: true

良い例

• test-scope: unit|integration|full
• build-target: web|api|worker
• upload-artifact: true|false

再利用ワークフロー側では型とデフォルト値を明示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

on:
  workflow_call:
    inputs:
      test-scope:
        required: false
        type: string
        default: "unit"
      upload-artifact:
        required: false
        type: boolean
        default: true

入力名を自然言語に寄せすぎないのがコツです。将来の運用者が見て意味がぶれない命名に寄せます。

4. セキュリティ設計：permissions を最小化する

再利用ワークフローの導入後に増える事故が「権限過剰」です。permissions: write-all を残したまま運用すると、意図しないトークン利用で供給網リスクが高まります。

推奨はジョブ単位での最小権限化です。

1
2
3
4

permissions:
  contents: read
  pull-requests: write
  actions: read

デプロイやタグ作成など書き込みが必要な処理だけ、専用ジョブに分離して contents: write を付与します。CI と CD の境界を分けるだけで、攻撃面積をかなり削減できます。

5. キャッシュ設計でハマらないための実践

Actions の高速化でよく使う actions/cache は、キー設計を誤ると逆効果になります。

• キーが粗い: 依存不整合で不安定化
• キーが細かすぎる: キャッシュヒット率低下

Node の例:

1
2
3
4
5
6
7

- uses: actions/setup-node@v4
  with:
    node-version: ${{ inputs.node-version }}
    cache: npm

- run: npm ci
- run: npm test

まずは setup-* の組み込みキャッシュを優先し、複雑な手動キャッシュは必要になってから追加する方が安全です。

6. 導入手順（3週間での現実的移行）

Week 1: 現状分析

1. 全 repo の workflow を収集
2. 共通ジョブを抽出（lint/test/build/security）
3. 失敗率の高い処理を特定

Week 2: 共通 repo 構築

1. org-ci-workflows を作成
2. 2〜3 種類の再利用ワークフローを作る
3. テンプレート repo で先行検証

Week 3: 段階移行

1. 低リスク repo から順次移行
2. 失敗ログを収集し API（inputs）を微調整
3. v1 タグを固定し、全体展開

重要なのは、一気に全 repo を置き換えないことです。先行導入で「どの入力が不足しているか」を把握し、後続 repo の移行コストを下げます。

7. 変更管理：main 直参照を禁止する

呼び出し側で @main を使うと、共通 repo の更新が即時反映されます。これは便利ですが、本番では危険です。事故時に「いつ壊れたか」が追跡しづらくなります。

実運用では次を推奨します。

• 呼び出しは @v1 などのタグ固定
• 破壊的変更は v2 を新規発行
• 重大修正のみ v1.x に backport

さらに、変更通知テンプレートを用意しておくと移行が速くなります。

1
2
3
4
5
6

[CI Workflow Update]
- Target: ci-node.yml
- Change: npm audit step added
- Impact: build time +20-40 sec
- Action Required: none (v1.3.0 auto pickup)
- Rollback: use v1.2.4

8. 監視指標（導入効果を数字で見る）

再利用ワークフローを入れたら、以下を最低でも計測します。

• CI 平均実行時間
• PR あたり失敗回数
• ワークフロー設定変更に伴う障害件数
• セキュリティ警告検出率

導入後 1 か月で、設定差分の削減 と 障害切り分け時間の短縮 が見えてくるはずです。数字が出ない場合は、共通化の粒度が粗すぎる可能性があります。

9. よくある失敗と対策

失敗1: 共通化しすぎて柔軟性が消える

対策: 80%共通 + 20%ローカル上書きの構造にする。例外を許容する。

失敗2: 例外入力が増えて API が壊れる

対策: 四半期ごとに inputs を棚卸し。未使用入力を削除し、破壊的変更はメジャーバージョンへ。

失敗3: Platform Team しか触れない

対策: docs/onboarding.md を整備し、アプリチームが PR で改善できる運用にする。

10. そのまま使える導入チェックリスト

• 共通 repo を作成し、責任者を明確化した
• workflow_call の入力仕様を文書化した
• permissions を最小権限に設定した
• 呼び出し側でタグ固定（@v1）を徹底した
• 先行 repo で 1 週間運用検証した
• ロールバック手順を README に記載した

まとめ

GitHub Actions の再利用ワークフローは、単なる YAML 共通化ではなく、組織の開発基盤を製品として運用する取り組みです。導入の成否は、技術よりも運用設計に左右されます。

• 入力仕様を API として設計する
• 権限を最小化し事故半径を縮小する
• バージョン固定で変更を可観測にする

この3点を守るだけで、CI/CD は「壊れやすい魔法」から「改善可能な仕組み」に変わります。まずは 1 つの再利用ワークフローから始め、3 週間で小さく成功を作るのが最短ルートです。