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" で実行されます。—コンテナ化された Dockert イメージは、Confidential Space イメージ上のセキュアなクラウドベースのエンクレーブで実行されます。
UID2 Operator Confidential Space 用の Docker コンテナが起動すると、UID2 Core Service が Operator Service と Operator Service が実行されているエンクレーブ環境の正当性を検証するための認証プロセスが完了します。
認証が成功すると、UID2 Core Service は、UID2 Operator をセキュアな Confidential Space コンテナ内でブートストラップするためのソルトやキーなどのシード情報を提供します。
Setup Overview
セットアップは、次の手順で行います:
-
Confidential Space and UID2 Operator のアカウントを作成し、設定し、構成とデプロイに必要なさまざまな値を取得または作成します: Prerequisites を参照してください。
-
Deployment environments に関する情報を確認します。
ペストプラクティス は、まずインテグレーション環境にデプロイし、次に本番環境にデプロイすることです。
-
利用可能なdeployment options に関する情報を確認し、それぞれの利点を比較して、使用するオプションを決定します。
Terraform テンプレートオプションを勧めます。
-
選択したデプロイメントオプションに従って、適用可能な手順に従います:
-
必要であれば、エグレスルールを有効にします。
- 詳細は Confidential Space Account Setup、Step 4 を参照してください。
すべての手順が完了すると、実装が稼働するようになります。
Prerequisites
Google Cloud Platform で Confidential Space を使用して UID2 Operator Service を設定する前に、次の前提条件を満たす必要があります:
Confidential Space Account Setup
UID2 Operator Service は、任意の GCP アカウントとプロジェクトで実行できます。ただし、認証をサポートするためには 、Confidential Space 仮想マシン(VM)を実行するために使用できるサービスアカウントを作成する必要があります。
デプロイメントオプションを選択する前に、次の Google Cloud のセットアップ手順を完了してください:
-
UID2 Operator を実行する GCP プロジェクトを作成します。UID2 Operator Service が実行される GCP プロジェクトを作成することを勧めますが、既存のプロジェクトを使用することもできます。次のガイドラインに従ってください:
- プロジェクト名を選択します。たとえば、
UID2-Operator-Production
とします。この値は、後の手順で{PROJECT_ID}
値として使用します。 - 請求が有効になっている GCP プロジェクトを定義してください。
- プロジェクト名を選択します。たとえば、
-
Confidential Space VM を実行する GCP サービスアカウントの名前を選択します。たとえば、
uid2-operator
とします。後の手順で{SERVICE_ACCOUNT_NAME}
値として使用します。 -
gcloud CLI をインストールします。デプロイメントオプションの両方で必要です。Google が提供する手順に従ってください: Install the gcloud CLI。
-
エグレスルールを有効にします。VPC インフラストラクチャが既知のエンドポイントへのイグレスのみを許可する場合、オペレーターが認証に必要な証明書を取得できるようにエグレスルールを有効にする必要があります。これを有効にするには、Google のこのドキュメントに従ってください: VPC Service Controls。
UID2 Operator Account Setup
UID2 の連絡先に、あなたの組織を UID2 Operator として登録するよう依頼してください。誰に依頼すればよいかわからない場合は、Contact Info を参照してください。
新しいバージョンやその他の技術的な通知や要求について知らせておくべき人の社内メール配信リストを設定し、そのメールアドレスを提供しておくとよいでしょう。
登録手続きが完了すると、次の情報が送られてきます:
Item | Description |
---|---|
{OPERATOR_KEY} | UID2 Service であなたを Private Operator として識別する、あなた専用の Operator Key。設定時に OPERATOR_KEY の値とし て使用します。この値は、あなた固有の識別子であると同時にパスワードでもあります。Operator Keyは、オペレーターのバージョンに固有のものではありません。NOTE: 配備環境ごとに個別の Operator Keyを受け取ります。 |
Instructions | VM のセットアップ手順や当該情報へのリンクなど、追加情報の詳細。 |
UID2 アカウント登録が完了し、gcloud CLI をインストールしたら、次のステップに進みます:
- deployment environments に関する情報を確認します。
- 利用可能なdeployment options に関する情報を確認し、それぞれの利点を比較して、使用するオプションを決定します。
Operator Versions
最新の ZIP ファイルは、次の表の GCP ダウンロード列にリンクされています。
Release | Version | Date | Release Notes | AWS Version | GCP Download | Azure Download |
---|---|---|---|---|---|---|
Q1 2024 | 5.26.19 | February 13, 2024 | v5.26.19-56899dc0d7 | 5.26.19-56899dc0d7 | 5.26.19-56899dc0d7 GCP ZIP | 5.26.19-56899dc0d7 Azure ZIP |
Q2 2024 | 5.37.12 | June 12, 2024 | v5.37.12 | 5.37.12 | gcp-oidc-deployment-files-5.37.12.zip | azure-cc-deployment-files-5.37.12.zip |
Q3 2024 | 5.38.104 | September 12, 2024 | v5.38.104 | 5.38.104 | gcp-oidc-deployment-files-5.38.104.zip | azure-cc-deployment-files-5.38.104.zip |
Q3 2024 Out-of-band | 5.41.0 | October 29, 2024 | v5.41.0 | 5.41.0 | gcp-oidc-deployment-files-5.41.0.zip | azure-cc-deployment-files-5.41.0.zip |
Deployment Environments
以下の環境が利用可能で、deployment options の両方が両方の環境をサポートしています。
ベストプラクティスは、本番環境にデプロイする前に、統合環境で実装をテストして検証することをです。
各環境ごとに個別の {OPERATOR_KEY}
値を受け取ります。正しいものを使用してください。{OPERATOR_IMAGE}
値は、両方の環境で同じです。
Environment | Details |
---|---|
Integration (integ ) | テスト専用。デバッグモードはインテグレーション環境で使用できます。 |
Production (prod ) | 本番トラフィックの管理用。この環境では、Terraform テンプレート経由で、ロードバランシングを行い、HTTPS を有効にしてデプロイすることを勧めます。Deployment Options を参照してください。 |
Deployment Options
デプロイメントオプションは次の2つがあります:
Option | Details |
---|---|
Terraform template | このオプションは:
|
gcloud CLI | このオプションは:
|
どちらのデプロイメントオプションも、両方のデプロイメント環境をサポートしています。
次のステップを決定するには、使用するデプロイオプションを選択してください。次に、該当する手順に従ってください:
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 テンプレートを使用する手順は次のとおりです:
- Install Terraform
- Set Up the Terraform Environment
- Download the Template Files
- Provide Input Values
- Run Terraform
- Test Terraform Using the Health Check Endpoint
詳細は次のとおりです:
Install Terraform
Terraform がインストールされていない場合は、terraform.io を参照してインストールしてください。
Set Up the Terraform Environment
-
新しいプロジェクトを作成するか、既存のプロジェクトを選択します。プロジェクト ID の
{PROJECT_ID}
プレースホルダを自分のプロジェクト ID に置き換えてください(Confidential Space Account Setup を参照):gcloud config set project {PROJECT_ID}
-
Terraform の環境を設定します:
gcloud auth application-default login
Download the Template Files
Operator Versions の GCP ダウンロード列にある ZIP ファイルをダウンロードします。最新バージョンを選択してください。ファイルを便利な場所に解凍します。次の表に示すファイルが生成されます。
File | Details |
---|---|
main.tf | Terraform のテンプレートファイルです。 |
variables.tf | 名前、タイプ、デフォルト値を含む、テンプレート入力変数の定義です。 |
outputs.tf | 出力定義です。 |
terraform.tfvars | テンプレート入力変数の値です。 |
Provide Input Values
入力パラメータの値を提供するために、ダウンロードした terraform.tfvars
ファイルに入力します。必要なものとオプションの両方があります。
-
次の表に示す必要な入力パラメータの値を提供します:
Name Type Default Required Description project_id
string
uid2-test
yes UID2 Operator を実行する GCP プロジェクトの ID。例えば、 UID2-Operator-Production
。service_account_name
string
tf-test
yes GCP Confidential Space の UID2 Operator インスタンスに 使用するサービスアカウントの名前。 uid_operator_image
string
us-docker.pkg.dev/uid2-prod-project/iabtechlab/uid2-operator:{version_number}
yes コンフィギュレーションで使用する UID2 Private Operator for GCP の Docker イメージ URL。バージョン番号は、デプロイされるバージョンによって変わります。 uid_operator_key
string
n/a yes UID2 Operator Keyは、UID2 Operator Account Setup で受け取ったものです。 uid_operator_key_secret_name
string
secret-operator-key
yes Secret Manager で作成するキーの名前。 uid_deployment_env
string
integ
yes 有効な値: integ
はインテグレーション環境、prod
は本番環境。
マシンタイプはデプロイ環境によって決まります。integ
はn2d-standard-2
を使用し、prod
はn2d-standard-16
を使用します。debug_mode
bool
true
yes より 多くの診断情報を有効にするには true
に設定します。本番環境ではfalse
に設定しなければなりません。 -
(オプション、強く勧めます) ロードバランサーを HTTPS に設定します。次の表に示すパラメータお値を設定します:
Name Type Default Required Description ssl
bool
false
no ロードバランサが HTTPS を使うように設定するには、このフラグを true
に設定します。
HTTPSを使う場合はcertificate
とprivate_key
パラメータにも値を指定する必要があります。certificate
string
n/a no HTTPS 証明書の内容。証明書は PEM 形式でなければなりません。
例えば:file('path/to/certificate.pem')
.ssl
がtrue
に設定されている場合は必須です。
詳細は Terraform ドキュメントの google_compute_ssl_certificate を参照してください。private_key
string
n/a no HTTPS 証明書の秘密鍵の内容。秘密鍵は PEM 形式でなければならなりません
例えば:file('path/to/private_key.pem')
.ssl
がtrue
に設定されている場合は必須です。
詳細は Terraform ドキュメントの google_compute_ssl_certificate を参照してください。 -
(オプション) 次の表に示す追加の入力パラメータの名前と値を提供します。これらのパラメータは常にオプションですが、デフォルト値を変更して、より適切な要件に合わせることができます。
Name Type Default Required Description region
string
us-east1
no デプロイ先のリージョン。有効なリージョンの一覧については、Google Cloud ドキュメントの Available regions and zones を参照してください。
NOTE: GCP Confidential Space 用の UID2 Private Operator の実装は、次の地域ではサポートされていません: ヨーロッパ、中国。network_name
string
uid-operator
no VPC リソース名(ルール/インスタンスタグにも使用されます)。 min_replicas
number
1
no デプロイする最小レプリカ数を示します。 max_replicas
number
5
no デプロイする最大レプリカ数を示します。 uid_operator_key_secret_name
string
"secret-operator-key"
no オペレーターキーのシークレットの名前を指定します。Terraform テンプレートは、GCP Secret Manager に uid_operator_key
値を保持するためのシークレットを作成します。名前を定義できます。例:uid2-operator-operator-key-secret-integ
。debug_mode
bool
false
no UID2 チームと協力して問題をデバッグする場合を除き、 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 テンプレートからの出力値は次の表の通りです。
Name | Description |
---|---|
load_balancer_ip | ロードバランサーのパブリックIPアドレス。 この値は、perform the health check や DNS の設定に使用できます。 |
Deploy—gcloud CLI
gcloud CLI を使用して GCP Confidential Space Enclave に新しい UID2 Operator をデプロイするには、次の手順に従います。
本番環境へのデプロイメントにはこのオプションを使用しないことを勧めます。本番環境へのデプロイメントには、Terraform テンプレートを使用し、ロードバランシングを行い、HTTPS を有効にすることを勧めます。
- Set Up Service Account Rules and Permissions
- Create Secret for the Operator Key in Secret Manager
- Update the Script with Valid Values
- Run the Script
- Test gcloud Using the Health Check Endpoint