gcloud iam

Table of Contents

  1. 基本概念
  2. サービスアカウント
    1. 作成・管理
    2. サービスアカウントキー
  3. ロール
    1. 事前定義ロール
    2. よく使う事前定義ロール
    3. カスタムロール
  4. ポリシーバインディング
    1. プロジェクトレベル
    2. リソースレベル
    3. 条件付きバインディング
  5. サービスアカウントの権限借用
  6. Workload Identity Federation
  7. 注意点
  8. 参考リンク

gcloud iam は Google Cloud の Identity and Access Management（IAM）を管理するコマンドです。サービスアカウントの作成、ロールの管理、ポリシーバインディングの設定を行えます。

基本概念

概念 説明
プリンシパル アクセスするユーザーやサービスアカウント
ロール 権限のセット（例: roles/viewer、roles/editor）
ポリシー プリンシパルとロールの紐付け
サービスアカウント アプリケーションが使う専用アカウント

サービスアカウント

作成・管理

1
2
3
4
5
6
7
8
9
10
11
12
13
# サービスアカウントを作成
gcloud iam service-accounts create my-sa \
  --display-name="My Service Account" \
  --description="Cloud Run で使用するサービスアカウント"

# 一覧を表示
gcloud iam service-accounts list

# 詳細を表示
gcloud iam service-accounts describe my-sa@PROJECT_ID.iam.gserviceaccount.com

# 削除
gcloud iam service-accounts delete my-sa@PROJECT_ID.iam.gserviceaccount.com

サービスアカウントキー

1
2
3
4
5
6
7
8
9
10
11
# キーを作成（JSON 形式）
gcloud iam service-accounts keys create key.json \
  --iam-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

# キーの一覧を表示
gcloud iam service-accounts keys list \
  --iam-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

# キーを削除
gcloud iam service-accounts keys delete KEY_ID \
  --iam-account=my-sa@PROJECT_ID.iam.gserviceaccount.com

注意: サービスアカウントキーはセキュリティリスクが高いため、可能な限り Workload Identity やサービスアカウントの権限借用（--impersonate-service-account）を使うことが推奨されています。

サービスアカウントキーの代替手段（公式）

ロール

事前定義ロール

1
2
3
4
5
# 利用可能なロールを検索
gcloud iam roles list --filter="name:run"

# ロールの詳細（含まれる権限）を表示
gcloud iam roles describe roles/run.invoker

よく使う事前定義ロール

ロール 説明
roles/viewer プロジェクト全体の読み取り専用
roles/editor プロジェクト全体の読み書き（IAM 管理を除く）
roles/owner プロジェクト全体の完全な制御
roles/run.invoker Cloud Run サービスを呼び出す権限
roles/run.admin Cloud Run の管理権限
roles/storage.objectViewer Cloud Storage オブジェクトの読み取り
roles/storage.admin Cloud Storage の管理権限
roles/cloudsql.client Cloud SQL への接続権限
roles/secretmanager.secretAccessor Secret Manager のシークレット読み取り
roles/container.admin GKE クラスタの管理権限
roles/iam.serviceAccountUser サービスアカウントとしての実行権限

事前定義ロールの一覧（公式）

カスタムロール

最小権限の原則に従い、必要な権限だけを含むカスタムロールを作成できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# カスタムロールを作成
gcloud iam roles create myCustomRole \
  --project=PROJECT_ID \
  --title="My Custom Role" \
  --description="Cloud Run のデプロイと Secret Manager の読み取り" \
  --permissions="run.services.create,run.services.update,secretmanager.versions.access"

# カスタムロールを更新
gcloud iam roles update myCustomRole \
  --project=PROJECT_ID \
  --add-permissions="run.services.delete"

# カスタムロールを削除
gcloud iam roles delete myCustomRole --project=PROJECT_ID

カスタムロールの作成（公式）

ポリシーバインディング

プリンシパルにロールを付与・削除します。

プロジェクトレベル

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# ユーザーにロールを付与
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:alice@example.com" \
  --role="roles/viewer"

# サービスアカウントにロールを付与
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.invoker"

# ロールを削除
gcloud projects remove-iam-policy-binding PROJECT_ID \
  --member="user:alice@example.com" \
  --role="roles/viewer"

# 現在のポリシーを表示
gcloud projects get-iam-policy PROJECT_ID

リソースレベル

特定のリソースにだけ権限を付与できます。プロジェクト全体よりもセキュアです。

1
2
3
4
5
6
7
8
9
10
# Cloud Run サービスに invoker 権限を付与
gcloud run services add-iam-policy-binding my-service \
  --region=asia-northeast1 \
  --member="serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.invoker"

# Cloud Storage バケットに権限を付与
gcloud storage buckets add-iam-policy-binding gs://my-bucket \
  --member="serviceAccount:my-sa@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

条件付きバインディング

期限付きや条件付きの権限付与ができます。

1
2
3
4
5
# 2025年末まで有効な権限を付与
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:alice@example.com" \
  --role="roles/editor" \
  --condition="title=temp-access,expression=request.time < timestamp('2025-12-31T00:00:00Z')"

サービスアカウントの権限借用

キーファイルを使わずに、一時的に別のサービスアカウントの権限で操作できます。

1
2
3
4
5
6
7
8
9
10
11
# 任意のコマンドをサービスアカウントとして実行
gcloud run deploy my-service \
  --source=. \
  --region=asia-northeast1 \
  --impersonate-service-account=deploy-sa@PROJECT_ID.iam.gserviceaccount.com

# 権限借用に必要なロール（借用元のアカウントに付与）
gcloud iam service-accounts add-iam-policy-binding \
  deploy-sa@PROJECT_ID.iam.gserviceaccount.com \
  --member="user:alice@example.com" \
  --role="roles/iam.serviceAccountTokenCreator"

サービスアカウントの権限借用（公式）

Workload Identity Federation

GitHub Actions や AWS など外部のアイデンティティプロバイダーから、キーなしで認証できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Workload Identity プールを作成
gcloud iam workload-identity-pools create github-pool \
  --location="global" \
  --display-name="GitHub Actions Pool"

# プロバイダーを追加（GitHub Actions 用）
gcloud iam workload-identity-pools providers create-oidc github-provider \
  --location="global" \
  --workload-identity-pool="github-pool" \
  --display-name="GitHub Provider" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
  --issuer-uri="https://token.actions.githubusercontent.com"

# サービスアカウントへのバインディング
gcloud iam service-accounts add-iam-policy-binding \
  deploy-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github-pool/attribute.repository/OWNER/REPO"

Workload Identity Federation（公式）

注意点

  • roles/editor や roles/owner はプロジェクト全体に広い権限を与えるため、本番環境では避ける。必要な事前定義ロールやカスタムロールを使う
  • サービスアカウントキー（JSON）はローテーションと保管に注意が必要。Workload Identity Federation や権限借用を優先する
  • ポリシーバインディングの変更はすぐに反映されない場合がある（最大で数分の遅延）
  • get-iam-policy → 編集 → set-iam-policy の手順は競合しやすい。add-iam-policy-binding / remove-iam-policy-binding を使うのが安全

参考リンク