1．はじめに「NIC x Ops（にこぷす）」とは？

皆さま、こんにちは！
このテックブログでは、IT運用に関する内容を連載、「にこぷす通信」をお届けしています。

『NIC x Ops（にこぷす）』とは、
私たちの会社であるNTTインテグレーション（NI+C）の運用ノウハウと、
IBMさんの強力なソリューションを
Collaboration（コラボレーション）させた、IT運用高度化シリーズ（Ops）のニックネームなんです。

現代のIT運用の現場は、システムの複雑化や人手不足など、課題が山積みです。そんな現場を少しでも楽に、そしてエンジニアの皆さんが笑顔で「攻めの運用」ができるように支えたい。そんな想いがこの「にこぷす」には込められています。

「にこぷす」には、Instana（可観測性）のほかにも、Turbonomic（リソース最適化）やTerraform（インフラ自動化）など、IT運用を劇的に変える製品がたくさんあります。

これからもこの通信を通して、「IT用語は難しいけれど、中身を知ればこんなに便利で面白いんだ！」というテクニカルな内容をご紹介していきますので、どうぞよろしくお願いします。

2．概要

外部SaaSやCI/CD（今回はHCP Terraform）からGoogle Cloudを操作する際、サービスアカウントのJSONキー（秘密鍵）を発行して登録する方法は、管理や漏洩のリスクの観点から現在ではアンチパターンとされています。

現在の標準的なアプローチは、鍵を直接発行・保持しない OIDC（OpenID Connect） プロトコルを利用し、一時的なアクセス資格情報（アクセストークン）を生成してキーレスで接続する方法です。Google Cloudではこの仕様を Workload Identity Federation（WIF） として実装しています。

今回は、本番環境を想定した VPC Service Controls（VPC-SC） のサービス境界内で保護されているプロジェクトに対し、HCP TerraformからOIDCを使ってセキュアに接続するための具体的な設定フローを検証しました。

GUI（コンソール）を使った手順に加えて、環境変数（シェル変数）を活用したgcloudコマンドによる確実な構築手順について記録しておきます。

3．アーキテクチャ設計（Hub-Spoke構成）

検証にあたり、認証を処理するプロジェクトと、実リソースを配置するプロジェクトを物理的に分ける「Hub-Spoke（分離）型」の構成を採用しました。

一般的なマルチプロジェクト運用におけるWIFは、「外部アイデンティティ（IdP）の接続設定を一元化して統制しやすくする」という管理面（ガバナンス）の目的で集約されることが多いです。しかし、VPC-SC（サービス境界）が絡む環境においては、単なる管理の集約化というメリットを超えて、アーキテクチャ上のデッドロックを回避するためにこのHub-Spoke構成が強く推奨されます。

認証プロセスの循環依存（デッドロック）を回避する

OIDCの認証窓口（WIF）をSpokeプロジェクト（本番環境）の内部に直接作ってしまうと、VPC-SCによって認証前のSTS（セキュリティ・トークン・サービス）へのアクセス自体が遮断されてしまいます。認証を完了させるためのアクセスが、未認証を理由にブロックされる「認証プロセスの循環依存（デッドロック）」が発生するためです。これを回避するため、セキュリティ境界の外側にHubプロジェクトを配置し、認証処理自体を境界の外側に逃がす設計が必要になります。

Hub-Spoke構成にしてWIF機能を境界外（Hub）に集約しておけば、アノニマスな認証処理はすべて安全に境界外で完結します。境界をまたぐ通信は、① WIFプリンシパル（principalSet://...）を境界内の iamcredentials.googleapis.com（SA借用API）に通すルールと、② 借用されたサービスアカウント（serviceAccount:...）を実操作API（storage.googleapis.com等）に通すルールの、役割を明確に分けた2つのシンプルな上り（Ingress）ルールだけで安全かつ明確に制御可能になります。

• Hubプロジェクト（共通Identity管理用・VPC-SC外）： WIF専用のプロジェクトです。境界の外側で安全にSTSによる認証を完結させます。
• Spokeプロジェクト（保護対象の環境・VPC-SC内）： 借用対象のサービスアカウント（SA）と、実リソース（GCSバケット等）を配置します。VPC-SCの境界内部で保護します。

4. 実際にやってみる

事前の環境変数定義（gcloudコマンドで構成する場合のみ使用）

以降の手順で使用する各種コマンドや設定ファイルの書き換えミスを防ぐため、あらかじめ今回の構成に必要なパラメータをターミナルで環境変数として定義しておきます。

これらを一度シェル上でエクスポートしておけば、以後の構築用コマンドは書き換えることなく、すべてそのままコピー＆ペーストで実行可能になります。

# 1. 境界外：Hubプロジェクトのパラメータ
export HUB_PROJECT_ID="HubプロジェクトのプロジェクトID"
export HUB_PROJECT_NUM="Hubプロジェクトのプロジェクト番号"

# 2. 境界内：Spokeプロジェクトのパラメータ
export SPOKE_PROJECT_ID="SpokeプロジェクトのプロジェクトID"
export SPOKE_PROJECT_NUM="Spokeプロジェクトのプロジェクト番号"
export SA_NAME="サービスアカウント名"
export SA_EMAIL="${SA_NAME}@${SPOKE_PROJECT_ID}.iam.gserviceaccount.com"

# 3. HCP Terraform（組織・アクセス制限用）のパラメータ
export ORG_ID="HCP Terraformの組織ID"

# 4. VPC-SC管理用パラメータ（上りルールを適用する際に使用）
export PERIMETER_NAME="サービスの境界名"
export POLICY_ID="アクセスポリシーID"

【手順1】HubプロジェクトにおけるWIFプロバイダの設定

境界外のHubプロジェクトで、HCP TerraformからのOIDCアサーションを信頼するためのプールとプロバイダを構成します。

なお、HCP TerraformのOIDCトークン（JWTクレーム）からは、組織（Organization）情報のほかにワークスペースID（terraform_workspace_id）やプロジェクトIDなども送信されてくるため、特定のワークスペースのみに絞り込んだ厳密な制御をかけることも技術的には可能です。ただし、今回は運用管理をシンプルにすることを優先し、組織（Organization）レベルで一元的に制御し、ワークスペースレベルでの個別制限は行わない方針とします。

（方法１）コンソールでの設定

1. Hubプロジェクトを選択し、「IAM と管理」 > 「Workload Identity 連携」 からプールを新規作成します。
   
2. 「名前」を入力し、次に進みます。
   
3. プロバイダの種類は「OIDC」を選択し、プロバイダ名、発行 URL（https://app.terraform.io）を入力します。オーディエンスは、「デフォルトのオーディエンス」のままで問題ありません。
   
4. 属性マッピング を定義します。 必須となるサブジェクト（スロット 1）と、表記の揺れを防ぐための組織ID（スロット 2）を、コンソール上のテーブルに以下のようにマッピングします。

   番号 (GCP側)	Google Cloud 側の属性 (左)	OIDC クレーム (右)	用途
   Google 1 (必須)	google.subject	assertion.sub	アクセス主体 (Sub) の一意な識別
   Google 2	attribute.terraform_organization_id	assertion.terraform_organization_id	組織IDベースのアクセス境界制限

5. 属性条件（CEL式） を定義し、特定の組織のみがこのプールを利用できるように制限します。
   
   • 単一の組織のみを許可する場合（基本構成）
     • attribute.terraform_organization_id == 'org-16桁の組織ID'
   • 複数の組織を許可したい場合 条件に in 演算子とリストを組み合わせることで、複数組織を許可できます。
     • attribute.terraform_organization_id in ['org-1つ目の組織ID', 'org-2つ目の組織ID']

（方法２）gcloud コマンドによる構成

事前定義した環境変数を利用して、コンソールを介さずスムーズに構成を完了させます。

# Workload Identity プールの作成
gcloud iam workload-identity-pools create "hcp-tf-pool" \
  --project="${HUB_PROJECT_ID}" \
  --location="global" \
  --display-name="HCP Terraform Pool"

# OIDC プロバイダの作成 (デフォルトAudienceは自動適用されるため省略)
gcloud iam workload-identity-pools providers create-oidc "hcp-tf-provider" \
  --project="${HUB_PROJECT_ID}" \
  --location="global" \
  --workload-identity-pool="hcp-tf-pool" \
  --display-name="HCP Terraform Provider" \
  --issuer-uri="https://app.terraform.io" \
  --attribute-mapping="google.subject=assertion.sub,attribute.terraform_organization_id=assertion.terraform_organization_id" \
  --attribute-condition="attribute.terraform_organization_id == '${ORG_ID}'"

【手順2】Spokeプロジェクトでのサービスアカウントの設定

境界内（Spoke）プロジェクトに移動し、HCP Terraformがなりすますサービスアカウント（SA）に対し、① WIFプールからの借用許可（信頼関係） と、② SA自身が実際にSpoke内のGCSバケットを構築するための操作権限 をそれぞれ付与します。

（方法１）コンソールでの設定

A. WIFプールからサービスアカウントへの「借用権限（信頼関係）」の付与

1. Spokeプロジェクト にコンソール表示を切り替えます。
2. 「IAM と管理」 > 「サービスアカウント」 から対象のSAの詳細画面を開きます。（SAは事前に作成しています。）
3. 「アクセス権を持つプリンシパル」 タブを開き、「アクセスを許可」 をクリックします。
   
4. 「新しいプリンシパル」 入力欄に、以下の WIF プリンシパルセット識別子をフルパスで直接入力します。 ※ 【Hubプロジェクト番号】 と 【組織ID】 の部分は、それぞれご自身の環境の値（12桁と16桁の数値）に置き換えてください。
   • principalSet://iam.googleapis.com/projects/【Hubプロジェクト番号】/locations/global/workloadIdentityPools/hcp-tf-pool/attribute.terraform_organization_id/org-【組織ID】
5. 「ロールの選択」 で、「Workload Identity ユーザー」（roles/iam.workloadIdentityUser）を選択し、保存します。
   

B. サービスアカウント自身への「リソース操作権限」の付与

続いて、なりすまされたサービスアカウント自身が、Spokeプロジェクト内でGCSバケットを作成・管理できるよう、リソース自体の操作権限を付与します。(基本的な操作なので、画面イメージは省略)

1. Spokeプロジェクト の 「IAM と管理」 > 「IAM」 画面を開きます。
2. 画面上部の 「アクセスを許可」 をクリックします。
3. 「新しいプリンシパル」 入力欄に、Spokeプロジェクトで作成したサービスアカウントのメールアドレスを入力します。
4. 「ロールの選択」 で、「Storage 管理者」（roles/storage.admin）を選択し、保存します。

（方法２）gcloud コマンドによる構成

IAMバインドの不整合やコンソールの挙動に気をもみたくない場合は、環境変数を用いてターミナルから直接適用します。

# 0. サービスアカウント（SA）の新規作成
gcloud iam service-accounts create "${SA_NAME}" \
  --project="${SPOKE_PROJECT_ID}" \
  --display-name="HCP Terraform impersonation target SA"

# 1. サービスアカウントに対する借用権限（WIF信頼関係）のバインド
gcloud iam service-accounts add-iam-policy-binding "${SA_EMAIL}" \
  --project="${SPOKE_PROJECT_ID}" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/${HUB_PROJECT_NUM}/locations/global/workloadIdentityPools/hcp-tf-pool/attribute.terraform_organization_id/${ORG_ID}"

# 2. サービスアカウント自体へのリソース操作権限（Storage管理者ロール）の付与
gcloud projects add-iam-policy-binding "${SPOKE_PROJECT_ID}" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/storage.admin"

【手順3】VPC-SCの上り（Ingress）ポリシーの設定

Spokeプロジェクトが属するVPC-SCのセキュリティ境界を越えて、サービスアカウントの資格情報生成API（iamcredentials.googleapis.com）を呼び出すため、上りポリシーを定義します。

「最小権限の原則」を満たすため、ポリシーは「① WIF経由のなりすまし用」と「② なりすまし完了後の実操作用」の2つの独立した上りルールに分けて定義します。これにより認証と認可のプロセスを分離・制御できます。

安全・確実なコード管理を行うための 「コンソール（GUI）による設定」 と、本番環境など一貫性を重視する場面で推奨される 「構成ファイル（YAML）を用いたgcloudによる設定」 の2種類の方法があります。

（方法１）コンソール（GUI）による設定

1. Google Cloud コンソール上部のプロジェクトセレクターで 「組織」 または共通管理されているリソースフォルダを選択し、「セキュリティ」 > 「VPC Service Controls」 に移動します。
2. 設定対象 の サービス境界（Perimeter）を選択し、「編集」 ボタンをクリックします。
3. 境界の設定画面の左メニューから 「上り（Ingress）ポリシー」 を選択し、「ルールを追加」 をクリックします。
4. なりすまし要求（WIF認証）用の「FROM (送信元属性)」 を以下のように設定します。
   
   • API クライアントの送信元: 「すべての送信元アクセスレベル（デフォルト）」
   • API クライアント（ID）: 「選択した ID」にチェックを入れ、追加欄に以下の WIF プールプリンシパルセット（プール全体を表すワイルドカード * を末尾に付与）を手動入力して追加します。
     • principalSet://iam.googleapis.com/projects/【Hubプロジェクト番号】/locations/global/workloadIdentityPools/hcp-tf-pool/*
       
5. 「TO (送信先属性)」 を以下のように設定し、「完了」をクリックします。
   
   • プロジェクト / 境界スコープ: 「選択したプロジェクト」にチェックを入れ、境界内に位置する Spokeプロジェクト を選択します。
   • サービス: 「選択したサービス」にチェックを入れ、サービス名の一覧から 「IAM Service Account Credentials API」 を選択して追加します。 ※ もしくは、直接 iamcredentials.googleapis.com を追加します。
   • メソッド: 「すべてのメソッド」を選択します。
6. 同様に、リソース作成用のルールを追加します。(同様の操作なので、画面イメージは省略)
   • FROM (送信元属性)
     • API クライアントの送信元: 「すべての送信元アクセスレベル」
     • API クライアント（ID）: リソースをデプロイするために作成したサービスアカウント
   • TO (送信先属性)
     • プロジェクト / 境界スコープ: Spokeプロジェクト
     • サービス: storage.googleapis.com
     • メソッド: 「すべてのメソッド」
7. 画面下部の 「保存」 をクリックして上りルールを確定させます。

（方法２）構成ファイル（YAML）を用いたgcloudによる設定

VPC-SCはコンソールでの編集ミスが即座に通信遮断を招くため、CLI（gcloud）によるコード管理（GitOps）が推奨されます。

⚠️ 【重要】既存ポリシー上書き消失のリスクへの対策 gcloudコマンドの --set-ingress-policies オプションは、引数で渡したファイルを基準にポリシーを「完全上書き」するため、単に新規ルールのみを書いたファイルを適用すると、境界に設定されていた既存の他ルールがすべて消去（消失）されてしまいます。

これを防ぐため、実務では必ず 「一度既存のポリシーをYAMLに退避 ➔ そのファイルに今回のルールをマージ ➔ 一括して反映」 という手順を踏んでください。

① 既存の上りポリシーを安全にバックアップ・退避する

まず、現在境界に適用されている既存の上りポリシーのみを抽出し、ingress_merged.yaml という名前のローカルファイルにYAML形式で書き出します。

gcloud access-context-manager perimeters describe "${PERIMETER_NAME}" \
  --billing-project="${SPOKE_PROJECT_ID}" \
  --policy="${POLICY_ID}" \
  --format="yaml(status.ingressPolicies)" | sed '1,2d; s/^  //' > ingress_merged.yaml

⚠️ Spoke プロジェクトで Access Context Manager API が有効化されている必要があります。

② 出力されたYAMLファイルの末尾に環境変数を展開しながら一括マージ（追記）する

ヒアドキュメント（cat <<EOF >> ...）を利用して、事前定義済みの環境変数を展開しながら、エクスポートした ingress_merged.yaml の末尾に直接上りルールを自動追記します。

cat <<EOF >> ingress_merged.yaml

- ingressFrom:
    identities:
    # 1. Hubのプロジェクト番号が刻印されたWIF通行証を許可
    - principalSet://iam.googleapis.com/projects/${HUB_PROJECT_NUM}/locations/global/workloadIdentityPools/hcp-tf-pool/*
    sources:
    - accessLevel: '*'
  ingressTo:
    operations:
    - methodSelectors:
      - method: '*'
      serviceName: iamcredentials.googleapis.com
    resources:
    - projects/${SPOKE_PROJECT_NUM}
  title: HCP Terraform なりすまし専用ルール

- ingressFrom:
    identities:
    # 2. 変身完了後のサービスアカウント自身のIDを許可
    - serviceAccount:${SA_EMAIL}
    sources:
    - accessLevel: '*'
  ingressTo:
    operations:
    - methodSelectors:
      - method: '*'
      serviceName: storage.googleapis.com
    resources:
    - projects/${SPOKE_PROJECT_NUM}
  title: デプロイ実操作用ルール
EOF

③ マージ完了後のYAMLファイルを一括適用（安全なロールフォワード）

既存設定と今回の追加設定が完全に融合した ingress_merged.yaml を用いて、サービス境界へポリシーを一括適用します。既存のポリシーを一切巻き込むことなく、安全にポリシーの更新が完了します。

gcloud access-context-manager perimeters update "${PERIMETER_NAME}" \
  --billing-project="${SPOKE_PROJECT_ID}" \
  --set-ingress-policies="ingress_merged.yaml" \
  --policy="${POLICY_ID}"

【手順4】HCP Terraform側の環境変数（Variables）設定

Google Cloud側のインフラ・APIアクセスの受け入れ態勢が整ったら、次は呼び出し元である HCP Terraform（旧 Terraform Cloud） のWorkspaceを設定します。 HCP Terraform側でキーレスWIF接続を有効化するには、Workspace内の「Variables」にて、特定の環境変数を登録する必要があります。

設定する環境変数（Environment Variables）

HCP Terraformの該当するWorkspaceを開き、「Variables」 メニューをクリックして、以下の 「Environment variable」（※ Terraform variableではない点に注意）を3つ追加します。

変数名（Key）	値の記述形式（Value）	用途
TFC_GCP_PROVIDER_AUTH	true	HCP Terraformに対して、GCP WIFのキーレス認証プロトコルの稼働を命じるフラグ。
TFC_GCP_WORKLOAD_PROVIDER_NAME	projects/【Hubプロジェクト番号】/locations/global/workloadIdentityPools/hcp-tf-pool/providers/hcp-tf-provider	境界外（Hub）プロジェクトに構築したOIDCプロバイダのフルパス。
TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL	【SpokeプロジェクトのSAメールアドレス】	最終的に境界をまたいで借用し、リソースの構築権限として利用するサービスアカウント。

💡 ポイント TFC_GCP_WORKLOAD_PROVIDER_NAME の値には、WIFプールやプロバイダのID（hcp-tf-pool や hcp-tf-provider）が埋め込まれています。スペルミスがあると認証フローの途中でGCP STSに弾かれるため、1文字の誤字もないように注意深く指定してください。

【手順5】Terraformによる接続・デプロイ検証

準備が整ったら、HCP TerraformからSpokeプロジェクトに対して実際にデプロイをかけます。

providers.tf の定義

前段の手順でHCP Terraformの環境変数にてWIF連携が有効化されているため、バックグラウンドで一時的なOIDCトークンが自動的にロードされます。これにより、Terraformコード内の provider 定義には環境変数経由のキーレス認証が行われるため、サービスアカウントの秘密鍵ファイルのパスやシークレットの参照などの余計な記述は一切不要になります。

provider "google" {
  project = "production-resource-spoke"
}

リソース（GCS）の定義

動作検証用に、VPC-SC境界内にGCSバケットを作成します。

resource "google_storage_bucket" "assets" {
  name     = "bucket-production-resource-spoke-prd-gcs-assets"
  location = "asia-northeast1"
}

HCP TerraformからWorkspaceを実行（Run）し、VPC-SCのIngress制御を通過してGCSバケットが無事に生成されれば、OIDCによるキーレス連携の開通はすべて完了です。

• HCP Terraform（Apply 結果）
  
• Cloud Console
  

5. まとめ：VPC-SCを突破する設計の要点おさらい

外部SaaSからVPC-SC境界を越えてGoogle Cloudに接続する設計は、難解に見えますが、押さえるべき設計上のポイントは極めてシンプルです。最後に重要な要点をおさらいです。

1. 認証（WIF/STS）は境界外（Hub）に逃がす
   • 認証前のアクセスはVPC-SCのプリンシパル制限にかけられないため、境界の外（Hub）で安全にSTSによる認証を完結させ、循環依存（デッドロック）を防ぎます。
2. 上り（Ingress）ポリシーは役割ごとに「2枚」に分ける
   • 「WIFプリンシパル（なりすまし前） ➔ iamcredentials」と「サービスアカウント ➔ 実操作API」にポリシーを物理分割し、必ず正規の借用手順（なりすまし）を経るプロセスを強制します。

一連の設計を理解して整理しておけば、画面のウィザードに惑わされることなく、自信を持って堅牢なキーレスCI/CDパイプラインを構築できます。構成の理解が済んだら、これらの設定自体もIaC化して自動管理するのが次のステップとしておすすめです。

「にこぷす通信」について

「NIC × Ops（にこぷす）通信」は、隔週で皆さまに情報をお届けします。
このシリーズでは、Instana（可観測性）をはじめ、Turbonomic（リソース最適化）やTerraform（インフラ自動化）など、IT運用を劇的に変える製品をピックアップしていきます。
これからも最新の技術検証をチームで継続し、皆さまの現場ですぐに役立つ「有益な知見」を全力で共有していきます。 次回の連載もお楽しみに！