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

Private Operator for AKS integration guide

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

注記

AKS の Private Operator をセットアップしたい場合は、UID2 の連絡先にお問い合わせください。詳細は、Contact info を参照してください。

このガイドでは、Azure Kubernetes Service（AKS） クラスター上で Azure Container Instances（ACI） の仮想ノード上で実行される UID2 Operator Service を Private Operator として設定する方法について説明します。Azure Container Instances 上の仮想ノードを使用することで、ハードウェアでバックアップされた Trusted Execution Environment （TEE） で実行される機密コンテナの機能を活用できます。この TEE は、データ整合性、データ機密性、コード整合性などの内在的な機能を提供します。

UID2 Operator の機密 Azure Container インスタンス用の Docker コンテナーが起動すると、UID2 Core Service が Operator Service の真正性と、Operator Service が実行されているエンクレーブ環境の真正性を検証できるようにする認証プロセスが完了します。

認証が成功すると、UID2 Core Service は、UID2 Operator をセキュアな UID2 Operator 機密 Azure Container Instance で起動するためのソルトやキーなどのシード情報を提供します。

注意

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

Private Operator upgrade policy​

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

注記

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

Prerequisites​

AKS の UID2 Private Operator をデプロイする前に、次の前提条件を完了してください:

Set up the UID2 Operator account​

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

登録プロセスが完了すると、UID2 Service に対して Private Operator として識別する、あなた専用の operator key が届きます。構成中は、これを OPERATOR_KEY の値として使用します。この値は、あなたのためのユニークな識別子であり、パスワードでもあります。安全に保管し、共有しないでください。

注記

各環境に対して別の operator key が届きます。

Install the Azure CLI​

Azure コマンドラインインターフェイスをインストールします。詳細は、Azure ドキュメントの How to install the Azure CLI を参照してください。

Get the required Azure permissions​

リソースグループを作成するには、サブスクリプションの所有者権限が必要です。

作業が完了したら、そのリソースに対してリソースグループレベルの貢献者権限のみが必要です。

詳細は、Azure ドキュメントの Azure roles を参照してください。

すべての前提条件が完了したら、UID2 Private Operator をデプロイする準備が整いました。次は Deployment を参照してください。

Install the kubectl CLI​

Kubernetes の kubectl コマンドラインインターフェイスをインストールします。詳細は、Kubernetes ドキュメントの Install Tools を参照してください。

Install the Helm CLI​

helm コマンドラインインターフェイスをインストールします。詳細は、Installing Helm を参照してください。

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​

以下の環境が利用可能です。ベストプラクティスとして、テスト環境で実装をテストして検証してから、本番環境にデプロイすることをお勧めします。

注記

各環境ごとに別々の {OPERATOR_KEY} 値が届きます。使用している環境に正しいキーを使用してください。デプロイメントアーティファクトとプロセスフローは、両方の環境で同じです。

EnvironmentDetails
Integration (integ)テスト専用です。デバッグモードはテスト環境で利用可能です。
Production (prod)本番トラフィックを管理するためのものです。

Deployment​

AKS の新しい UID2 Private Operator をデプロイするには、次の主要な手順を完了する必要があります:

Download ZIP file and extract files​

インストールファイルをセットアップするには、次の手順に従ってください:

  1. UID2 の連絡先に、デプロイメントファイルを含む ZIP ファイルを依頼してください。

  2. ダウンロードし、解凍します。

Prepare environment variables​

以下のコマンドを実行して、後で使用する環境変数を準備します。変数名は必要に応じて選択してください。

export RESOURCE_GROUP="my-vn-aks"
export LOCATION="eastus"
export VNET_NAME="my-vnet"
export PUBLIC_IP_ADDRESS_NAME="my-public-ip"
export NAT_GATEWAY_NAME="my-nat-gateway"
export AKS_CLUSTER_NAME="myvncluster"
export KEYVAULT_NAME="my-vn-aks-vault"
export KEYVAULT_SECRET_NAME="my-vn-aks-opr-key-name"
export MANAGED_IDENTITY="my-vn-aks-opr-id"
export AKS_NODE_RESOURCE_GROUP="MC_${RESOURCE_GROUP}_${AKS_CLUSTER_NAME}_${LOCATION}"
export SUBSCRIPTION_ID="$(az account show --query id --output tsv)"
export DEPLOYMENT_ENV="integ"

Set up AKS and node pool​

AKS とノードプールをセットアップするには、次の手順を完了します:

Create resource group​

Azure で、UID2 Private Operator を実行するリソースグループを作成するには、次のコマンドを実行します:

az group create --name "${RESOURCE_GROUP}" --location "${LOCATION}"
備考

すべてのリソースは、${RESOURCE_GROUP} の値として指定した名前の下に後でプロビジョニングされます。

ロケーションに関していくつかの制限があります:

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

  • Azure 仮想ネットワークのデプロイメントの可用性は、Resource availability & quota limits for ACI を確認してください。

  • ロケーションのエイリアスを取得するには、次のコマンドを実行します:

    az account list-locations -o table

Create virtual network​

仮想ネットワークを作成するには、次のコマンドを実行します:

az network vnet create \
    --resource-group ${RESOURCE_GROUP} \
    --name ${VNET_NAME} \
    --location ${LOCATION} \
    --address-prefixes 10.0.0.0/8

Create subnets​

サブネットを作成するには、次のコマンドを実行します:

# Default Subnet (10.0.0.0/24)
az network vnet subnet create \
    --resource-group ${RESOURCE_GROUP} \
    --vnet-name ${VNET_NAME} \
    --name default \
    --address-prefixes 10.0.0.0/24

# AKS Subnet (CIDR /16)
az network vnet subnet create \
    --resource-group ${RESOURCE_GROUP} \
    --vnet-name ${VNET_NAME} \
    --name aks \
    --address-prefixes 10.1.0.0/16

# Container Groups Subnet (CIDR /16) with Delegation
az network vnet subnet create \
    --resource-group ${RESOURCE_GROUP} \
    --vnet-name ${VNET_NAME} \
    --name cg \
    --address-prefixes 10.2.0.0/16 \
    --delegations Microsoft.ContainerInstance/containerGroups

Create public IP address​

パブリック IP アドレスを作成するには、次のコマンドを実行します:

az network public-ip create --name ${PUBLIC_IP_ADDRESS_NAME} --resource-group ${RESOURCE_GROUP} --sku standard --allocation static

Create NAT gateway​

Azure NAT Gateway を作成するには、次のコマンドを実行します:

az network nat gateway create \
    --resource-group ${RESOURCE_GROUP} \
    --name ${NAT_GATEWAY_NAME} \
    --public-ip-addresses ${PUBLIC_IP_ADDRESS_NAME} \
    --idle-timeout 4

Configure NAT service for source subnet​

NAT サービスを構成するには、次のコマンドを実行します:

az network vnet subnet update \
    --resource-group ${RESOURCE_GROUP} \
    --vnet-name ${VNET_NAME} \
    --name cg \
    --nat-gateway ${NAT_GATEWAY_NAME}
注記

アウトバンドのネットワークが制限されている場合は、Private Operator network egress に記載されている宛先へのアウトバウンドアクセスを許可する必要があります。

Get the AKS Subnet ID​

AKS サブネット ID を取得するには、次のコマンドを実行します:

export AKS_SUBNET_ID=$(az network vnet subnet show \
    --resource-group ${RESOURCE_GROUP} \
    --vnet-name ${VNET_NAME} \
    --name aks \
    --query id \
    --output tsv)

Create an AKS service​

AKS サービスを作成するには、次のコマンドを実行します:

# Create the AKS cluster
az aks create \
    --resource-group ${RESOURCE_GROUP} \
    --name ${AKS_CLUSTER_NAME} \
    --location ${LOCATION} \
    --kubernetes-version 1.36 \
    --network-plugin azure \
    --network-policy calico \
    --vnet-subnet-id ${AKS_SUBNET_ID} \
    --service-cidr 10.4.0.0/16 \
    --dns-service-ip 10.4.0.10 \
    --node-vm-size Standard_D4d_v5 \
    --node-count 2 \
    --enable-cluster-autoscaler \
    --min-count 2 \
    --max-count 5 \
    --auto-upgrade-channel patch \
    --enable-managed-identity \
    --nodepool-name oprnodepool \
    --os-sku Ubuntu
注記

必ず最新のサポートされている Kubernetes バージョンを使用してください。--kubernetes-version フラグを使用します。上記のバージョンはあくまで一例です。Azure は、Kubernetes の各マイナーバージョンをリリースから約 12 ヶ月後に標準サポートの対象外とし、それ以降はクラスターの作成が K8sVersionNotSupported で失敗します。お使いのリージョンで現在利用可能なバージョンを一覧表示するには、az aks get-versions --location ${LOCATION} を実行してください。標準サポートの対象外となったバージョンを使用する場合は、長期サポート（LTS）を有効にする必要があります。詳細は、Microsoft ドキュメントの Long-term support for Azure Kubernetes Service (AKS) versions を参照してください。

Get the principal ID of the managed identity​

principal ID を取得するには、次のコマンドを実行します:

export MANAGED_IDENTITY_PRINCIPAL_ID="$(az aks show --resource-group ${RESOURCE_GROUP} --name ${AKS_CLUSTER_NAME} --query "identityProfile.kubeletidentity.clientId" --output tsv)"

詳細は、Microsoft Azure ドキュメントの Get the principal ID of the system-assigned managed identity を参照してください。

Create contributor role for the two resource groups​

各グループに対してコントリビューターロールを作成するには、次のコマンドを実行します:

az role assignment create \
  --assignee ${MANAGED_IDENTITY_PRINCIPAL_ID} \
  --scope /subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${AKS_NODE_RESOURCE_GROUP} \
  --role Contributor

az role assignment create \
  --assignee ${MANAGED_IDENTITY_PRINCIPAL_ID} \
  --scope /subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP} \
  --role Contributor

外部ドキュメントの追加参照情報:

Set up AKS cluster​

AKS クラスターをセットアップするには、次のコマンドを実行します:

az aks get-credentials --name ${AKS_CLUSTER_NAME} --resource-group ${RESOURCE_GROUP}

az provider register -n Microsoft.ContainerInstance

git clone git@github.com:microsoft/virtualnodesOnAzureContainerInstances.git

helm install virtualnode virtualnodesOnAzureContainerInstances/Helm/virtualnode
 
# Wait for ~1 minute for virtualnode-0 to appear.
kubectl get nodes

Complete key vault and managed identity setup​

次のステップは、Key Vault をセットアップし、Operator Key を保存することです。Key Vault を作成したら、Managed Identity を作成し、Key Vault へのアクセス権を付与できます。

後で、AKS クラスターが起動すると、この ID を使用します。詳細は、Microsoft Azure ドキュメントの Running pods with an Azure Managed Identity を参照してください。

以下の手順に従ってください:

az identity create --name "${MANAGED_IDENTITY}" --resource-group "${RESOURCE_GROUP}" --location "${LOCATION}"

az keyvault create --name "${KEYVAULT_NAME}" --resource-group "${RESOURCE_GROUP}" --location "${LOCATION}" --enable-purge-protection --enable-rbac-authorization

export KEYVAULT_RESOURCE_ID="$(az keyvault show --resource-group "${RESOURCE_GROUP}" --name "${KEYVAULT_NAME}" --query id --output tsv)"

az keyvault secret set --vault-name "${KEYVAULT_NAME}" --name "${KEYVAULT_SECRET_NAME}" --value "<some value>"

export IDENTITY_PRINCIPAL_ID="$(az identity show --name "${MANAGED_IDENTITY}" --resource-group "${RESOURCE_GROUP}" --query principalId --output tsv)"

az role assignment create --assignee-object-id "${IDENTITY_PRINCIPAL_ID}" --role "Key Vault Secrets User" --scope "${KEYVAULT_RESOURCE_ID}" --assignee-principal-type ServicePrincipal

Complete the UID2 Private Operator setup​

Private Operator のセットアップを完了するには、次の手順に従ってください:

Update placeholder values​

前のステップを完了した後、プレースホルダ値を更新するには、次の手順に従ってください:

  1. 以下のコマンドを実行して、Managed Identity ID を取得します:

    MANAGED_IDENTITY_ID=$(az identity show --name "${MANAGED_IDENTITY}" --resource-group "${RESOURCE_GROUP}" --query id --output tsv)

  2. operator.yaml ファイルの microsoft.containerinstance.virtualnode.identity を、取得した Managed Identity ID で更新します:

    • For Linux, run:
    sed -i "s#IDENTITY_PLACEHOLDER#$MANAGED_IDENTITY_ID#g" "operator.yaml"
    • For MacOS, run:
    sed -i '' "s#IDENTITY_PLACEHOLDER#$MANAGED_IDENTITY_ID#g" "operator.yaml"

  3. Vault Key と Secret 名を環境変数で更新します:

    • For Linux, run:
    sed -i "s#VAULT_NAME_PLACEHOLDER#$KEYVAULT_NAME#g" "operator.yaml"
    sed -i "s#OPERATOR_KEY_SECRET_NAME_PLACEHOLDER#$KEYVAULT_SECRET_NAME#g" "operator.yaml"
    sed -i "s#DEPLOYMENT_ENVIRONMENT_PLACEHOLDER#$DEPLOYMENT_ENV#g" "operator.yaml"
    • For MacOS, run:
    sed -i '' "s#VAULT_NAME_PLACEHOLDER#$KEYVAULT_NAME#g" "operator.yaml"
    sed -i '' "s#OPERATOR_KEY_SECRET_NAME_PLACEHOLDER#$KEYVAULT_SECRET_NAME#g" "operator.yaml"
    sed -i '' "s#DEPLOYMENT_ENVIRONMENT_PLACEHOLDER#$DEPLOYMENT_ENV#g" "operator.yaml"

Deploy operator​

以下の手順に従って、Private Operator をデプロイします:

  1. Kubernetes configuration credentials を取得するには、次のコマンドを実行します:

    az aks get-credentials --name ${AKS_CLUSTER_NAME} --resource-group ${RESOURCE_GROUP}

  2. Kubernetes configuration credentials を取得したら、次のコマンドを実行して Private Operator をデプロイします:

    kubectl apply -f operator.yaml

Running the health check​

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

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

以下の手順に従ってください:

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

    IP=$(az network public-ip list --resource-group ${AKS_NODE_RESOURCE_GROUP} --query "[?starts_with(name, 'kubernetes')].ipAddress" --output tsv)

  2. Operator のステータスをテストするには、ブラウザでヘルスチェックエンドポイントにアクセスします: http://${IP}/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​

AKS 用の UID2 Private Operator の新しいバージョンがリリースされると、独自の Private Operator をホストしている参加者は、更新のメール通知を受け取り、新しいリリースリンクまたはインストールファイルを取得するための手順が記載されます。アップグレードのための期間があり、その後、古いバージョンは非アクティブになり、サポートされなくなります。

アップグレードするには、次の手順を完了します:

  1. Download ZIP file and extract files を参照して、新しいバージョンのデプロイメントファイルをダウンロードし、解凍します。

  2. Complete the UID2 Private Operator setup の手順に従い、新しいファイルを使用して AKS 実装を新しいバージョンでデプロイします。

  3. 新しい AKS デプロイメントのヘルスを確認し、ステータスが正常であることを確認します。

  4. 古い AKS ポッドが適切にシャットダウンされていることを再確認します:

    kubectl get pods

Keeping the operator key secure​

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

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