管理境界を構成する

このドキュメントでは、Resource Manager を使用して管理境界と機能構成を設定および管理する方法について説明します。管理境界により、Agent Registry でプロジェクト間のリソース検出とガバナンスが可能になります。

始める前に

境界と機能構成を構成する前に、必要なロールを取得して、必要な API を有効にします。

必要なロール

境界と機能を構成するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • 境界と機能構成を作成、更新、削除する: ターゲット フォルダまたは組織（ユーザー管理の管理プロジェクトを指定する場合は管理プロジェクト）に対するリソース マネージャー編集者 （roles/resourcemanager.editor）
  • 境界と機能の構成を表示する: ターゲット フォルダまたは組織に対する Resource Manager 閲覧者 （roles/resourcemanager.viewer）
  • メンバー プロジェクトにタグを付加する:
    • ターゲット フォルダ、組織、またはメンバー プロジェクトに対するタグユーザー （roles/resourcemanager.tagUser）
    • ターゲット フォルダまたは組織に対するタグ管理者 （roles/resourcemanager.tagAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

API を有効にする

  • Resource Manager API を有効にするには、gcloud services enable コマンドを使用します。

    gcloud services enable cloudresourcemanager.googleapis.com \
  --project=PROJECT_ID

    PROJECT_ID は、プロジェクトの ID に置き換えます。

管理境界を設定する

フォルダまたは組織に管理境界を設定するには、次の 2 つの方法があります。

  • フォルダ全体または組織全体の境界（タグフィルタなし）: フォルダまたは組織内のすべての子孫プロジェクトが含まれます。ステップ 1 とステップ 4 をスキップし、ステップ 2: 境界を作成する（--tag-key と --tag-value を除く）とステップ 3: 機能構成を作成するのみを完了します。
  • タグベースの境界: フォルダまたは組織内のプロジェクトをタグ値で分割します。以下の 4 つの手順をすべて完了してください。

ステップ 1: パーティショニング タグキーを構成する

タグフィルタを使用せずにフォルダ全体または組織全体の境界を作成する場合は、この手順をスキップします。デフォルトでは、BoundaryConfig リソースにタグキーは構成されていません。

タグベースの境界の場合、BoundaryConfig リソースは、フォルダまたは組織内のプロジェクトをパーティショニングするために使用されるタグキーを確立します。タグベースの境界を作成する前に、このリソースを構成します。

パーティショニング タグキーを設定するには、gcloud resource-manager boundary-configs update コマンドを使用します。

gcloud resource-manager boundary-configs update \
  --folder=FOLDER_ID \
  --tag-key=TAG_KEY_NAME

組織でタグキーを構成するには、--folder ではなく --organization=ORGANIZATION_ID を指定します。以前にタグキーを構成し、タグなしの境界に切り替える場合（親の下に境界が存在しない場合）、--tag-key ではなく --clear-tag-key を指定してこのコマンドを実行します。

次のように置き換えます。

  • FOLDER_ID: 親フォルダの ID
  • TAG_KEY_NAME: タグキーの名前。ORGANIZATION_ID/TAG_KEY_SHORT_NAME の形式（例: 123456789012/env）

ステップ 2: 境界を作成する

フォルダまたは組織に Boundary リソースを作成します。

タグフィルタなしでフォルダ全体の境界を作成するには（フォルダ内のすべての子孫プロジェクトが自動的に含まれます）、--tag-key と --tag-value を指定せずに gcloud resource-manager boundaries create コマンドを使用します。

gcloud resource-manager boundaries create BOUNDARY_ID \
  --folder=FOLDER_ID \
  --display-name="Production Boundary"

ステップ 1 でパーティショニング タグキーを構成した後にタグベースの境界を作成するには、--tag-key フラグと --tag-value フラグを指定します。

gcloud resource-manager boundaries create BOUNDARY_ID \
  --folder=FOLDER_ID \
  --display-name="Production Boundary" \
  --tag-key=TAG_KEY_NAME \
  --tag-value=TAG_VALUE_SHORT_NAME

組織に境界を作成するには、--folder ではなく --organization=ORGANIZATION_ID を指定します。

次のように置き換えます。

  • BOUNDARY_ID: 境界の一意の ID（prod-boundary など）
  • FOLDER_ID: 親フォルダの ID
  • TAG_KEY_NAME: 構成したタグキー（123456789012/env など）
  • TAG_VALUE_SHORT_NAME: プロジェクトが境界に参加するために必要なタグ値（prod など）。

ステップ 3: 機能構成を作成する

CapabilityConfig リソースを作成して、境界を管理プロジェクトにリンクし、境界を越えて管理されるサービスを宣言します。

機能構成を作成するには、gcloud resource-manager capability-configs create コマンドを使用し、Agent Registry に --types=agent-management を指定します。

gcloud resource-manager capability-configs create \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --types=agent-management \
  --boundaries=folders/FOLDER_ID/boundaries/BOUNDARY_ID \
  --display-name="DISPLAY_NAME"

組織に機能構成を作成するには、--folder ではなく --organization=ORGANIZATION_ID を指定します。

次のように置き換えます。

  • CAPABILITY_CONFIG_ID: 機能構成の一意の ID（prod-capabilities など）
  • FOLDER_ID: 親フォルダの ID
  • BOUNDARY_ID: 作成した境界の ID
  • DISPLAY_NAME: 人が読める形式の表示名

境界のない単一のスタンドアロン プロジェクトで機能を有効にするには、ステップ 1、2、4 をスキップし、--folder と --boundaries の代わりに --project=PROJECT_NUMBER と --management-project=projects/PROJECT_NUMBER を指定してこのコマンドを実行します。

既存のプロジェクトを管理プロジェクトとして使用するには、--management-project=projects/PROJECT_NUMBER フラグを渡します。指定するプロジェクトは次の要件を満たしている必要があります。満たしていない場合、コマンドはエラーで失敗します。

  • CapabilityConfig リソースと同じ親（folders/FOLDER_ID または organizations/ORGANIZATION_ID）の直下に存在する。
  • ACTIVE ライフサイクル状態である。
  • 管理プロジェクトとして指定されていない。

--management-project を省略すると、Resource Manager は親フォルダまたは組織の直下に専用の管理プロジェクトを自動的にプロビジョニングします。

CapabilityConfig リソースを作成すると、管理プロジェクトで対応するサービス API が自動的に有効になります（agent-management を指定した場合は agentregistry.googleapis.com など）。管理プロジェクトでこれらの API を手動で有効にする必要はありません。

ステップ 4: メンバー プロジェクトにタグを適用する

タグフィルタなしでフォルダ全体または組織全体の境界を作成した場合は、すべての子孫プロジェクトが自動的に含まれるため、この手順をスキップします。

タグベースの境界の場合、一致するタグ値をプロジェクトにバインドすると、プロジェクトは管理境界に動的に参加します。

境界に属する各プロジェクトにタグを適用するには、gcloud resource-manager tags bindings create コマンドを使用します。

gcloud resource-manager tags bindings create \
  --tag-value=TAG_VALUE_NAME \
  --parent=//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER

次のように置き換えます。

  • TAG_VALUE_NAME: タグ値の名前（123456789012/env/prod など）
  • PROJECT_NUMBER: 境界に含めるプロジェクトのプロジェクト番号（またはプロジェクト ID）

機能構成を管理する

機能構成の一覧表示、記述、更新、削除を行うことができます。このセクションの例では、--folder=FOLDER_ID を使用しています。組織またはプロジェクトの機能構成を管理するには、--folder の代わりに --organization=ORGANIZATION_ID または --project=PROJECT_NUMBER を指定します（境界は、フォルダレベルまたは組織レベルの機能構成にのみ適用できます）。

機能構成を一覧表示する

フォルダ内のすべての機能構成を一覧表示するには、gcloud resource-manager capability-configs list コマンドを使用します。

gcloud resource-manager capability-configs list \
  --folder=FOLDER_ID

機能の構成を記述する

構成の詳細と割り当てられた管理プロジェクトを表示するには、gcloud resource-manager capability-configs describe コマンドを使用します。

gcloud resource-manager capability-configs describe \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID

関連付けられた境界を更新する

機能構成にリンクされている境界を更新するには、gcloud resource-manager capability-configs update コマンドを使用します。

gcloud resource-manager capability-configs update \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --boundaries=folders/FOLDER_ID/boundaries/BOUNDARY_ID_1,folders/FOLDER_ID/boundaries/BOUNDARY_ID_2

update コマンドは、--types フラグと --display-name フラグも受け入れ、有効な機能タイプまたは表示名を更新します。

機能構成を削除する

境界がアタッチされている間は CapabilityConfig リソースを削除できません。また、CapabilityConfig リソースにアタッチされている間は Boundary リソースを削除できません。

プロジェクト間の管理が不要になったときに、機能構成を削除するには:

  1. 関連付けられた境界を接続解除するには、--clear-boundaries フラグを指定して gcloud resource-manager capability-configs update コマンドを使用します。

    gcloud resource-manager capability-configs update \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID \
  --clear-boundaries

  2. 機能構成を削除するには、gcloud resource-manager capability-configs delete コマンドを使用します。

    gcloud resource-manager capability-configs delete \
  CAPABILITY_CONFIG_ID \
  --folder=FOLDER_ID

次のステップ