メインコンテンツまでスキップ

UID2 Private Operator for GCP integration guide

UID2 Operator は、UID2 エコシステムの API サーバーです。詳細は、UID2 Operator を参照してください。

このガイドでは、Google Cloud Platform (GCP) の機密コンピューティングオプションである Confidential Space で Private Operator として UID2 Operator Service を設定する情報を提供します。Confidential Space は、Trusted Execution Environment (TEE) として知られるセキュアなクラウドベースのエンクレーブ環境を提供します。

注記

UID2 Private Operator for GCP は、次の地域ではサポートされていません: ヨーロッパ、中国。

Operator Service は Confidential Space の "workload" で実行されます。これは、Confidential Space イメージ上のセキュアなクラウドベースのエンクレーブで実行されるコンテナ化された Docker イメージです。

UID2 Operator Confidential Space 用の Docker コンテナが起動すると、UID2 Core Service が Operator Service と Operator Service が実行されているエンクレーブ環境の正当性を検証するための認証プロセスが完了します。

認証が成功すると、UID2 Core Service は、UID2 Operator をセキュアな Confidential Space コンテナ内でブートストラップするためのソルトやキーなどのシード情報を提供します。

Operator version​

最新の ZIP ファイルは、次の表の GCP ダウンロード列にリンクされています。

Version NameVersion #/Release NotesGCP DownloadDateDeprecation Date
Q4 2025v5.62.24gcp-oidc-deployment-files-5.62.24-r2.zipJanuary 15, 2026January 15, 2027
注記

サポートされているバージョンと非推奨日については、Private Operator versions を参照してください。

Private Operator upgrade policy​

セキュリティと運用の整合性を維持するため、古いオペレーターのバージョンは12ヶ月後に無効化され、影響を受けるデプロイメントがシャットダウンまたは起動に失敗する可能性があります。最新のセキュリティと機能強化を使用するために、アップグレードを推奨します。中断を避けるために、積極的なアップグレードを推奨します。

注記

重要なセキュリティまたは運用上の問題、または契約条件が適用される場合、プライベートオペレーターに対してより厳しいアップグレードタイムラインを適用する権利を留保します。

Setup overview​

セットアップは、次の手順で行います:

  1. Confidential Space and UID2 Operator のアカウントを作成し、設定し、構成とデプロイに必要なさまざまな値を取得または作成します: Prerequisites を参照してください。

  2. Deployment environments に関する情報を確認します。

    ベストプラクティスは、まずインテグレーション環境にデプロイし、次に本番環境にデプロイすることです。

  3. 利用可能なdeployment options に関する情報を確認し、それぞれの利点を比較して、使用するオプションを決定します。

    Terraform テンプレートオプションを推奨します。

  4. 選択したデプロイメントオプションに従って、適用可能な手順に従います:

  5. 必要であれば、エグレスルールを有効にします。

すべての手順が完了すると、実装が稼働するようになります。

Prerequisites​

Google Cloud Platform で Confidential Space を使用して UID2 Operator Service を設定する前に、次の前提条件を満たす必要があります:

Confidential Space account setup​

UID2 Operator Service は、任意の GCP アカウントとプロジェクトで実行できます。ただし、認証をサポートするためには、Confidential Space 仮想マシン（VM）を実行するために使用できるサービスアカウントを作成する必要があります。

デプロイメントオプションを選択する前に、次の Google Cloud のセットアップ手順を完了してください:

  1. UID2 Operator を実行する GCP プロジェクトを作成します。UID2 Operator Service が実行される GCP プロジェクトを作成することを推奨しますが、既存のプロジェクトを使用することもできます。次のガイドラインに従ってください:

    • プロジェクト名を選択します。たとえば、UID2-Operator-Production とします。この値は、後の手順で {PROJECT_ID} 値として使用します。
    • 請求が有効になっている GCP プロジェクトを定義してください。

  2. Confidential Space VM を実行する GCP サービスアカウントの名前を選択します。たとえば、uid2-operator とします。後の手順で {SERVICE_ACCOUNT_NAME} 値として使用します。

  3. gcloud CLI をインストールします。デプロイメントオプションの両方で必要です。Google が提供する手順に従ってください: Install the gcloud CLI。

  4. エグレスルールを有効にします。VPC インフラストラクチャが既知のエンドポイントへのイグレスのみを許可する場合、オペレーターが認証に必要な証明書を取得できるようにエグレスルールを有効にする必要があります。これを有効にするには、Google のこのドキュメントに従ってください: VPC Service Controls。

UID2 Operator account setup​

UID2 の連絡先に、あなたの組織を UID2 Operator として登録するよう依頼してください。誰に依頼すればよいかわからない場合は、Contact info を参照してください。

ヒント

新しいバージョンやその他の技術的な通知や要求について知らせておくべき人の社内メール配信リストを設定し、そのメールアドレスを提供しておくとよいでしょう。

登録手続きが完了すると、次の情報が送られてきます:

ItemDescription
{OPERATOR_KEY}UID2 Service であなたを Private Operator として識別する、あなた専用の Operator Key。設定時に OPERATOR_KEY の値として使用します。この値は、あなた固有の識別子であると同時にパスワードでもあります。Operator Key は、オペレーターのバージョンに固有のものではありません。
注意: 配備環境ごとに個別の Operator Key を受け取ります。
InstructionsVM のセットアップ手順や当該情報へのリンクなど、追加情報の詳細。

UID2 アカウント登録が完了し、gcloud CLI をインストールしたら、次のステップに進みます:

  • deployment environments に関する情報を確認します。
  • 利用可能なdeployment options に関する情報を確認し、それぞれの利点を比較して、使用するオプションを決定します。

Preparing DII for processing​

UID2 に変換する入力データが許容可能な形式であることは非常に重要です。そうでない場合、期待される結果は得られません。たとえば、Phone number normalization で説明されているように、電話番号には国コードを含めるように正規化する必要があります。

詳細は、Preparing emails and phone numbers for processing を参照してください。

フルトークン生成パイプラインをエンドツーエンドで検証し、正規化・ハッシュ化・エンコードされた値から生成されたトークンが正確であることを確認するためには、［UID2 Token Validator］（../ref-info/ref-token-validator.md）を使用してください。

Deployment environments​

以下の環境が利用可能で、deployment options の両方が両方の環境をサポートしています。

ベストプラクティスは、本番環境にデプロイする前に、インテグレーション環境で実装をテストして検証することです。

注記

各環境ごとに個別の {OPERATOR_KEY} 値を受け取ります。正しいものを使用してください。{OPERATOR_IMAGE} 値は、両方の環境で同じです。

EnvironmentDetails
Integration (integ)テスト専用。デバッグモードはインテグレーション環境で使用できます。
Production (prod)本番トラフィックの管理用。この環境では、Terraform テンプレート経由で、ロードバランシングを行い、HTTPS を有効にしてデプロイすることを推奨します。Deployment options を参照してください。

Deployment options​

デプロイメントオプションは次の2つがあります:

OptionDetails
Terraform templateこのオプションは:
  • 手動でサービスアカウントを設定する必要はありません。設定はとても簡単です。
  • ロードバランサーとスケーリンググループでスタック全体を立ち上げます。
  • gcloud オプションよりも保守・運用が簡単です。
  • アップグレードはとても簡単です。
  • 推奨するデプロイオプションです。
gcloud CLIこのオプションは:
  • パブリック IP アドレスを持つ VM インスタンスを1つ起動します。
  • 素早く実験・評価を行うことができます。
  • 複数のインスタンスを使用する場合は、コマンドを複数回実行して各インスタンスを手動で立ち上げる必要があります。
  • ロードバランサーを手動で設定する必要があります。
  • 手作業が増えるため、アップグレードはより複雑になります。

どちらのデプロイメントオプションも、両方のデプロイメント環境をサポートしています。

次のステップを決定するには、使用するデプロイオプションを選択してください。次に、該当する手順に従ってください:

Deploy—Terraform template​

デプロイとアップグレードを容易にするために、Terraform テンプレートを使用して、ロードバランシングと自動スケーリング機能を備えた UID2 Private Operator 実装をデプロイできます。このシナリオでは、すべての VM インスタンスが Confidential Space VM で実行され、複数の可用性ゾーン（AZ）にデプロイされます。

Terraform テンプレートは次の操作を行います:

  • 必要な Google Cloud Platform API を有効にします。
  • Confidential Space VM を実行するためのサービスアカウントを設定します。
  • operator_key 値を保持するためのシークレットを作成します。
  • 次のコンポーネントを作成します:
    • ネットワーク: VPC とサブネットワーク。
    • インスタンス: インスタンステンプレート、インスタンスグループ（自動スケーリングを有効にする）。
    • イングレス: ロードバランサー（ヘルスチェック付き）、フォワーディングルール、ファイアウォールルール。
    • エグレス: Cloud Network Address Translation (NAT)。
  • HTTPS が有効になっている場合、Terraform に HTTPS 証明書を提供します。
注記

Terraform テンプレートは、Confidential Space account setup Step 3 でインストールした gcloud CLI を使用します。

新しい UID2 Operator を GCP Confidential Space Enclave にデプロイするための Terraform テンプレートを使用する手順は次のとおりです:

  1. Install Terraform
  2. Set up the Terraform environment
  3. Download the template files
  4. Provide input values
  5. Run Terraform
  6. Test Terraform using the health check endpoint

詳細は次のとおりです:

Install Terraform​

Terraform がインストールされていない場合は、terraform.io を参照してインストールしてください。

Set up the Terraform environment​

  1. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。プロジェクト ID の {PROJECT_ID} プレースホルダを自分のプロジェクト ID に置き換えてください（Confidential Space account setup を参照）:

    gcloud config set project {PROJECT_ID}

  2. Terraform の環境を設定します:

    gcloud auth application-default login

Download the template files​

Operator version の GCP ダウンロード列にある ZIP ファイルをダウンロードします。最新バージョンを選択してください。ファイルを便利な場所に解凍します。次の表に示すファイルが生成されます。

FileDetails
main.tfTerraform のテンプレートファイルです。
variables.tf名前、タイプ、デフォルト値を含む、テンプレート入力変数の定義です。
outputs.tf出力定義です。
terraform.tfvarsテンプレート入力変数の値です。

Provide input values​

入力パラメータの値を提供するために、ダウンロードした terraform.tfvars ファイルに入力します。必要なものとオプションの両方があります。

  1. 次の表に示す必要な入力パラメータの値を提供します:

    NameTypeDefaultRequiredDescription
    project_idstringuid2-testyesUID2 Operator を実行する GCP プロジェクトの ID。たとえば、UID2-Operator-Production。
    service_account_namestringtf-testyesGCP Confidential Space の UID2 Operator インスタンスに使用するサービスアカウントの名前。
    uid_operator_imagestringus-docker.pkg.dev/uid2-prod-project/iabtechlab/uid2-operator:{version_number}yesコンフィギュレーションで使用する UID2 Private Operator for GCP の Docker イメージ URL。バージョン番号は、デプロイされるバージョンによって変わります。
    uid_operator_keystringn/ayesUID2 Operator Key は、UID2 Operator account setup で受け取ったものです。
    uid_operator_key_secret_namestringsecret-operator-keyyesSecret Manager で作成するキーの名前。
    uid_deployment_envstringintegyes有効な値: integ はインテグレーション環境、prod は本番環境。
    マシンタイプはデプロイ環境によって決まります。integ は n2d-standard-2 を使用し、prod は n2d-standard-16 を使用します。
    debug_modebooltrueyesより多くの診断情報を有効にするには true に設定します。本番環境では false に設定しなければなりません。

  2. (オプション、強く推奨します) ロードバランサーを HTTPS に設定します。次の表に示すパラメータの値を設定します:

    NameTypeDefaultRequiredDescription
    sslboolfalsenoロードバランサーが HTTPS を使うように設定するには、このフラグを true に設定します。
    HTTPS を使う場合は certificate と private_key パラメータにも値を指定する必要があります。
    certificatestringn/anoHTTPS 証明書の内容。証明書は PEM 形式でなければなりません。
    たとえば: file('path/to/certificate.pem').
    ssl が true に設定されている場合は必須です。
    詳細は Terraform ドキュメントの google_compute_ssl_certificate を参照してください。
    private_keystringn/anoHTTPS 証明書の秘密鍵の内容。秘密鍵は PEM 形式でなければなりません。
    たとえば: file('path/to/private_key.pem').
    ssl が true に設定されている場合は必須です。
    詳細は Terraform ドキュメントの google_compute_ssl_certificate を参照してください。

  3. (オプション) 次の表に示す追加の入力パラメータの名前と値を提供します。これらのパラメータは常にオプションですが、デフォルト値を変更して、より適切な要件に合わせることができます。

    NameTypeDefaultRequiredDescription
    regionstringus-east1noデプロイ先のリージョン。有効なリージョンの一覧は、Google Cloud ドキュメントの Available regions and zones を参照してください。
    注意: GCP Confidential Space 用の UID2 Private Operator の実装は、次の地域ではサポートされていません: ヨーロッパ、中国。
    network_namestringuid-operatornoVPC リソース名（ルール/インスタンスタグにも使用されます）。
    min_replicasnumber1noデプロイする最小レプリカ数を示します。
    max_replicasnumber5noデプロイする最大レプリカ数を示します。
    uid_operator_key_secret_namestring"secret-operator-key"noOperator Key のシークレットの名前を指定します。Terraform テンプレートは、GCP Secret Manager に uid_operator_key 値を保持するためのシークレットを作成します。名前を定義できます。例: uid2-operator-operator-key-secret-integ。
    debug_modeboolfalsenoUID2 チームと協力して問題をデバッグする場合を除き、true に設定しないでください。それ以外の場合、このフラグを true に設定すると、認証が失敗します。

Run Terraform​

以下を実行します:

terraform init
terraform apply

terraform apply を実行すると、同じフォルダに次のファイルが生成されます: terraform.tfstate。このファイルは、マネージドインフラストラクチャと構成に関する状態情報を保存し、将来のメンテナンスに使用されます。

注記

Terraform の state ファイルに関する推奨に従ってください: デプロイされたインフラストラクチャを維持するために必要であり、機密情報を含む可能性があります。詳細は、Terraform ドキュメントの state を参照してください。

Test Terraform using the health check endpoint​

実装のヘルスをテストするために、ヘルスチェックエンドポイントを使用します。ヘルスチェックの期待される結果は、HTTP 200 で、レスポンスボディが OK です。

手順は、Health check—Terraform template を参照してください。

Delete all created resources​

クリーンアップを行いたい場合は、Terraform によって作成されたリソースを削除できます。たとえば、integ をテストしたい場合、後でスタック全体を削除することができます。

すべてのリソースを削除するには、次のコマンドを実行します:

terraform destroy

Outputs​

Terraform テンプレートからの出力値は次の表の通りです。

NameDescription
load_balancer_ipロードバランサーのパブリック IP アドレス。
この値は、ヘルスチェックの実行 や DNS の設定に使用できます。

Deploy—gcloud CLI​

gcloud CLI を使用して GCP Confidential Space Enclave に新しい UID2 Operator をデプロイするには、次の手順に従います。

注記

本番環境へのデプロイメントにはこのオプションを使用しないことを推奨します。本番環境へのデプロイメントには、Terraform テンプレートを使用し、ロードバランシングを行い、HTTPS を有効にすることを推奨します。

  1. Set up service account rules and permissions
  2. Create secret for the operator key in Secret Manager
  3. Update the script with valid values
  4. Run the script
  5. Test gcloud using the health check endpoint

Set up service account rules and permissions​

gcloud CLI を使用して、UID2 Operator Service を実行するためのサービスアカウントを設定するには、次の手順に従います。プレースフォルダー値を自分の有効な値に置き換えてください。

  1. 作成したプロジェクトに切り替えます（Confidential Space account setup で作成したプロジェクト）:

    $ gcloud config set project {PROJECT_ID}

  2. 次の API を有効にします:

    NameDescription
    compute.googleapis.comCompute Engine API
    confidentialcomputing.googleapis.comConfidential Computing API
    logging.googleapis.comCloud Logging API
    secretmanager.googleapis.comService Management API

    API を有効にするには、次のコマンドを実行します:

    $ gcloud services enable compute.googleapis.com \
      confidentialcomputing.googleapis.com \
      logging.googleapis.com \
      secretmanager.googleapis.com

  3. UID2 Operator Service を実行するサービスアカウントを作成します:

    $ gcloud iam service-accounts create {SERVICE_ACCOUNT_NAME}

  4. サービスアカウントに必要な権限を付与します。

    権限は次の表に示されています。

    PermissionDescription
    confidentialcomputing.workloadUser認証トークンを生成し、VM でワークロードを実行する権限を提供します。
    logging.logWritergcloud ロギングでログエントリを書き込む権限を提供します。
    secretmanager.secretAccessorGCP Secret Manager で管理されている Operator Key にアクセスする権限を提供します。

    confidentialcomputing.workloadUser 権限を付与します:

    $ gcloud projects add-iam-policy-binding {PROJECT_ID} \
      --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \
      --role=roles/confidentialcomputing.workloadUser

    logging.logWriter 権限を付与します:

    $ gcloud projects add-iam-policy-binding {PROJECT_ID} \
      --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \
      --role=roles/logging.logWriter

    secretmanager.secretAccessor 権限を付与します:

    $ gcloud projects add-iam-policy-binding {PROJECT_ID} \
      --member=serviceAccount:{SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com \
      --role=roles/secretmanager.secretAccessor

  5. VPC ルールを追加して、UID2 Operator のデフォルト公開ポートであるポート 8080 へのパブリックアクセスを許可します:

    $ gcloud compute firewall-rules create operator-tcp \
      --direction=INGRESS --priority=1000 --network=default --action=ALLOW \
      --rules=tcp:8080 \
      --source-ranges=10.0.0.0/8 \
      --target-service-accounts={SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com
警告

source-ranges は、クライアントが Private Operator を呼び出すために使用する IP アドレスの範囲を指定します。CIDR 表記であり、複数の範囲を提供するためにカンマ区切りの値を使用できます。例: --source-ranges="10.0.0.0/8,10.10.0.0/16"。範囲が正確であり、自分のものである IP アドレスのみが含まれていることを確認してください。

Create secret for the operator key in Secret Manager​

UID2 Operator には、Operator Key が必要です。UID2 アカウントの設定（UID2 Operator account setup を参照）の一環として、各環境の Operator Key を受け取ります。

次のステップは、{OPERATOR_KEY} 値を GCP Secret Manager に保存し、それに対する完全なシークレット名を取得し、それをデプロイメントスクリプト内の {OPERATOR_KEY_SECRET_FULL_NAME} プレースホルダで置き換えることです (Update the script with valid values を参照)。

次の手順に従います:

  1. 次のスクリプトを実行して、新しいシークレットを作成します。最初に、自分の値でカスタマイズしてください:

    OPERATOR_KEY="{OPERATOR_KEY}"
    echo -n $OPERATOR_KEY | gcloud secrets create {OPERATOR_KEY_SECRET_NAME} \
         --replication-policy="automatic" \
       --data-file=-

    1. 自分の値を使用してスクリプトを準備します:

      • {OPERATOR_KEY} には、環境の Operator Key 値を使用します。
      • {OPERATOR_KEY_SECRET_NAME} には、この環境の API シークレットの名前を指定します。例: uid2-operator-operator-key-secret-integ。

    2. スクリプトを実行します。

      スクリプトは GCP Secret Manager にシークレットを作成します。シークレット（表示名）は {OPERATOR_KEY_SECRET_NAME} で、シークレット値は {OPERATOR_KEY} です。

  2. 次のコマンドを実行して、完全なシークレット名を取得します。最初に、自分の値でカスタマイズしてください:

    $ gcloud secrets versions describe latest --secret {OPERATOR_KEY_SECRET_NAME} --format 'value(name)'

この例では、完全なシークレット名は次のようになります: projects/111111111111/secrets/uid2-operator-operator-key-secret-integ/versions/1。これは、次のセクションの {OPERATOR_KEY_SECRET_FULL_NAME} プレースホルダを置き換えるために使用する値です。

Update the script with valid values​

サンプルスクリプトを更新して、プレースホルダ値を自分の有効な値に置き換えます。

このセクションには次の内容が含まれます:

Placeholder values and definitions​

プレースホルダ値は、次の表に定義されています。

PlaceholderActual Value
{INSTANCE_NAME}有効な VM の名前。
{ZONE}VM インスタンスがデプロイされる Google Cloud ゾーン。
{IMAGE_FAMILY}confidential-space はインテグレーションと本番で使用し、confidential-space-debug はインテグレーションでのみデバッグ用に使用します。confidential-space-debug は本番では動作しないことに注意してください。
{SERVICE_ACCOUNT}アカウント作成時に作成したサービスアカウントのメールアドレス: {SERVICE_ACCOUNT_NAME}@{PROJECT_ID}.iam.gserviceaccount.com.
詳細は Set up service account rules and permissions (Step 4) を参照してください。
{OPERATOR_IMAGE}コンフィギュレーションで使用する UID2 Private Operator for GCP の Docker イメージ URL。
これは、GCP ダウンロードファイルの terraform.tfvars ファイルにあります。(Operator version を参照)
{OPERATOR_KEY_SECRET_FULL_NAME}Operator Key secret に指定したフルネーム (Create secret for the operator key in Secret Manager を参照)。パスを含め projects/<project_id>/secrets/<secret_id>/versions/<version> の形式でしています。たとえば: projects/111111111111/secrets/uid2-operator-operator-key-secret-integ/versions/1
Sample deployment script—integ​

インテグレーション環境のデプロイメントスクリプトの例は、次のプレースホルダ値を使用しています。

$ gcloud compute instances create {INSTANCE_NAME} \
  --zone {ZONE} \
  --machine-type n2d-standard-2 \
  --confidential-compute \
  --shielded-secure-boot \
  --maintenance-policy Terminate \
  --scopes cloud-platform \
  --image-project confidential-space-images \
  --image-family {IMAGE_FAMILY} \
  --service-account {SERVICE_ACCOUNT} \
  --metadata ^~^tee-image-reference={OPERATOR_IMAGE}~tee-container-log-redirect=true~tee-restart-policy=Never~tee-env-DEPLOYMENT_ENVIRONMENT=integ~tee-env-API_TOKEN_SECRET_NAME={OPERATOR_KEY_SECRET_FULL_NAME}~tee-env-CORE_BASE_URL=https://core-integ.uidapi.com~tee-env-OPTOUT_BASE_URL=https://optout-integ.uidapi.com
Sample deployment script—prod​

本番環境のデプロイメントスクリプトの例は、次のプレースホルダ値を使用しています。

注記

本番環境では n2d-standard-16 という machine-type 値が必要です。

$ gcloud compute instances create {INSTANCE_NAME} \
  --zone {ZONE} \
  --machine-type n2d-standard-16 \
  --confidential-compute \
  --shielded-secure-boot \
  --maintenance-policy Terminate \
  --scopes cloud-platform \
  --image-project confidential-space-images \
  --image-family confidential-space \
  --service-account {SERVICE_ACCOUNT} \
  --metadata ^~^tee-image-reference={OPERATOR_IMAGE}~tee-container-log-redirect=true~tee-restart-policy=Never~tee-env-DEPLOYMENT_ENVIRONMENT=prod~tee-env-API_TOKEN_SECRET_NAME={OPERATOR_KEY_SECRET_FULL_NAME}~tee-env-CORE_BASE_URL=https://core-prod.uidapi.com~tee-env-OPTOUT_BASE_URL=https://optout-prod.uidapi.com

Run the script​

スクリプトの準備ができたら、追加の有効な値を含むスクリプトを実行します。

Test gcloud using the health check endpoint​

ヘルスチェックエンドポイントを呼び出して、実装の健全性をテストします。期待される結果は、HTTP 200 で、レスポンスボディが OK です。

手順は、Health check—gcloud CLI を参照してください。

Running the health check​

ヘルスチェックエンドポイントを呼び出して、実装の健全性をテストします。

ヘルスチェックの実行は、エンドポイントを除いて、インテグレーションと本番環境で同じです。

選択したデプロイメントオプションに応じて、適用される手順に従ってください:

Health check—Terraform template​

次の例は、Terraform テンプレートオプションのヘルスチェックを示しています:

  1. ロードバランサーのパブリック IP アドレスを取得します:

    terraform output load_balancer_ip

  2. オペレーターステータスをテストするには、ブラウザでヘルスチェックエンドポイントに移動します: http://{IP}/ops/healthcheck。

    HTTP 200 とレスポンスボディが OK の場合、健全な状態です。

Health check—gcloud CLI​

次の例は、gcloud コマンドラインオプションのヘルスチェックを示しています:

  1. デプロイされたインスタンスのパブリック IP アドレスを取得します:

    $ gcloud compute instances describe {INSTANCE_NAME} \
      --zone={ZONE} \
      --format='get(networkInterfaces[0].accessConfigs[0].natIP)'

  2. オペレーターステータスをテストするには、ブラウザでヘルスチェックエンドポイントに移動します: http://{IP}:8080/ops/healthcheck。

    HTTP 200 とレスポンスボディが OK の場合、健全な状態です。

Private Operator attestation failure​

Private Operator が Core Service による検証に失敗した場合、次のいずれかのアクションが発生します:

  • HTTP 401 レスポンス。Private Operator はすぐに終了します。
    • 原因: Operator Key が取り消されたか、間違っています。
  • その他の 200 以外のレスポンスコード。Private Operator は 12 時間機能し続けます。この期間内に問題が解決されない場合、自動的に終了します。

Private Operator がエラーが発生した場合、アラートを処理し、オペレーターを再起動するためのインフラストラクチャを用意する必要があります。

Upgrading​

UID2 Google Cloud Platform Confidential Space の新しいバージョンがリリースされると、Private Operator は新しいイメージバージョンを含む通知メールを受け取ります。アップグレードのためのウィンドウがあり、古いバージョンは非アクティブ化され、サポートされなくなります。

新しいバージョンにアップグレードする場合、アップグレードプロセスは選択したデプロイメントオプションに依存します。該当する手順に従ってください:

Upgrading—Terraform template​

Terraform テンプレートを使用してデプロイした場合、アップグレードするには、新しい {OPERATOR_IMAGE} を使用してデプロイメントを更新するだけです。

Upgrading—gcloud CLI​

gcloud CLI を使用してデプロイした場合、アップグレードするには、新しい {OPERATOR_IMAGE} を使用して新しいインスタンスを立ち上げ、古いインスタンスをシャットダウンする必要があります。

手動でロードバランサーを設定した場合、ロードバランサーのマッピングも更新する必要があります。

Scraping metrics​

GCP の Private Operator は、ポート 9080 の /metrics エンドポイントで Prometheus 形式のメトリクス を公開します。Prometheus 互換のスクレイパーを使用して、これらのメトリクスを収集して集計できます。

Keeping the operator key secure​

Operator Key を安全に保つためのガイドラインを以下に示します:

  • Operator Key を受け取ったら、安全な場所に保管してください。
  • キーが使用されているすべての場所を把握しておき、キーをローテーションする必要がある場合に迅速に対応できるようにしてください。
  • キーが漏洩した場合に備えて、既存の値を新しい値に置き換えるプロセスを確立してください。
  • 定期的なサイクル（例えば、毎年）でキーをローテーションし、キーが漏洩するリスクを軽減してください。

UID2 Operator error codes​

以下の表は、Private Operator 起動シーケンス中に発生する可能性のあるエラーを一覧表示しています。

注記

Private Operator 起動時のエラーコードは、リリース v5.49.7 以降のバージョンに適用されます。

Startup errors​

オペレータの起動時に以下のエラーが発生する可能性があります：

Error CodeIssueSteps to Resolve
E02OperatorKeyNotFoundErrorオペレータと同じプロジェクトの GCP Secret Manager に指定されたシークレット名が存在し、サービスアカウントがシークレットにアクセスする権限を持っていることを確認してください。tee-env-API_TOKEN_SECRET_NAME に設定されていることを確認してください。必要に応じて、特定のシークレット名はログを確認できます。
E03ConfigurationMissingError構成に必要な属性が不足しています。詳細はログを参照し、GCP オペレーターを実行する前に不足している属性を更新してください。
E04ConfigurationValueError設定値が無効です。設定値が必要な形式と環境に一致していることを確認してください。注意: debug_mode = true は integ 環境でのみ許可されます。詳細はログを確認してください。
E05OperatorKeyValidationErrorOperator Key が環境に対して正しいことを確認し、提供されたものと一致していることを確認してください。
E06UID2ServicesUnreachableErrorUID2 Core Service および Opt-Out Service の IP アドレスをアウトバウンドファイアウォールで許可します。IP アドレスと DNS の詳細は、ログを参照してください。
E08OperatorKeyPermissionErrorCompute Engine インスタンステンプレートにサービスアカウントをアタッチします。UID2 Operator は、GCP Secret Manager から Operator Key にアクセスするためにこれらの権限が必要です。

Runtime errors​

オペレータの実行中に以下のエラーが発生する可能性があります:

Error CodeIssueHow to Identify in LogsSteps to Resolve
E12Data Download FailureE12: Data Download Failure を含むログメッセージ、または RotatingStoreVerticle からの Failed to load エラーを確認してください。これらのメッセージには、HTTP ステータスコード（例：HTTP response code 403）や例外の種類（例：exception: IOException）が含まれます。エラーメッセージ内の HTTP ステータスコードまたは例外を確認し、それに応じて対処してください:
404 エラー: Operator Key が環境に対して有効であることを確認してください。
403 エラー: Operator Key および認証情報が正しいことを確認してください。
タイムアウトエラー: ネットワーク接続を確認し、ファイアウォール／セキュリティグループの設定で HTTPS（ポート 443）へのアウトバウンド通信が許可されていることを確認し、UID2 Service のエンドポイントにアクセス可能であることを確認してください。
500/503 エラー: このコードは一時的な UID2 Service の問題を示します。再試行し、エラーが継続する場合は UID2 サポートへ連絡してください。