オンライン エンドポイントでのシークレットの挿入 (プレビュー)
適用対象:Azure CLI ml extension v2 (現行)
Python SDK azure-ai-ml v2 (現行)
オンライン エンドポイントのコンテキストでのシークレットの挿入は、シークレット ストアからシークレット (API キーなど) を取得し、オンライン デプロイ内で実行されているユーザー コンテナーにそれを挿入するプロセスです。 シークレットは、最終的に、環境変数を介して安全にアクセスされ、スコアリング スクリプトを実行する推論サーバーまたは BYOC (Bring Your Own Container) デプロイ アプローチでユーザーが持ち込む推論スタックによって使われます。
重要
現在、この機能はパブリック プレビュー段階にあります。 このプレビュー バージョンはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。
詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。
問題の説明
オンライン デプロイを作成するとき、デプロイ内からシークレットを使って外部サービスにアクセスするのが望ましい場合があります。 このような外部サービスとしては、Microsoft Azure OpenAI サービス、Azure AI サービス、Azure AI Content Safety などがあります。
シークレットを使うには、デプロイ内で実行されているユーザー コンテナーにシークレットを安全に渡す方法を見つける必要があります。 デプロイ定義の一部としてシークレットを含めるのは、デプロイ定義でシークレットが公開されるため、お勧めしません。
それよりよい方法は、シークレット ストアにシークレットを格納して、デプロイ内から安全にそれを取得することです。 ただし、この方法には、シークレットを取得するためにシークレット ストアに対してデプロイ自体の認証を行う方法という固有の課題があります。 オンライン デプロイでは、マネージド ID である "エンドポイント ID" を使ってユーザー コンテナーが実行されるため、Azure RBAC を使ってエンドポイント ID のアクセス許可を制御し、シークレット ストアからのシークレットの取得をエンドポイントに許可できます。 この方法を使うには、次のタスクを行う必要があります。
- シークレット ストアからシークレットを読み取ることができるように、適切なロールをエンドポイント ID に割り当てます。
- エンドポイントのマネージド ID を使ってシークレット ストアからシークレットを取得するように、デプロイにスコアリング ロジックを実装します。
マネージド ID を使うこの方法は、シークレットを取得して挿入するための安全な方法ですが、シークレット挿入機能を使用してシークレットを挿入すると、ワークスペース接続とキー コンテナーのためのシークレットを取得するプロセスがさらに簡単になります。
エンドポイントに関連付けられたマネージド ID
オンライン デプロイでは、エンドポイントに関連付けられたマネージド ID を使ってユーザー コンテナーが実行されます。 "エンドポイント ID" と呼ばれるこのマネージド ID は、Azure RBAC をサポートする Microsoft Entra ID です。 そのため、ID に Azure ロールを割り当てて、操作の実行に必要なアクセス許可を制御できます。 エンドポイント ID には、システム割り当て ID (SAI) またはユーザー割り当て ID (UAI) のいずれかを使用できます。 どちらの種類の ID を使うかは、エンドポイントの作成時に決定できます。
- "システム割り当て ID" の場合、エンドポイントを作成すると ID が自動的に作成され、基本的なアクセス許可 (Azure Container Registry のプル アクセス許可やストレージ BLOB データ 閲覧者など) を持つロールが自動的に割り当てられます。
- "ユーザー割り当て ID" の場合は、まず ID を作成してから、エンドポイントの作成時にエンドポイントに関連付ける必要があります。 必要に応じて、適切なロールを UAI に割り当てる必要もあります。
エンドポイントのマネージド ID の使用について詳しくは、マネージド ID を使ってエンドポイントからリソースにアクセスする方法に関する記事と、外部サービスと対話するためのマネージド ID の使用に関する例をご覧ください。
エンドポイント ID へのロールの割り当て
シークレット ストアには、次のロールが必要です。
- ワークスペースのワークスペース接続に格納されているシークレットの場合:
Workspace Connections
によって提供される List Secrets API (プレビュー) では、API を呼び出す ID に、Azure Machine Learning Workspace Connection Secrets Reader
ロール (または同等のもの) が割り当てられている必要があります - 外部の Microsoft Azure Key Vault に格納されているシークレットの場合: Key Vault によって提供される Get Secret Versions API では、API を呼び出す ID に、
Key Vault Secrets User
ロール (または同等のもの) が割り当てられている必要があります。
シークレットの挿入の実装
シークレット ストアからシークレット (API キーなど) を取得した後、オンライン デプロイ内で実行されているユーザー コンテナーにそれを挿入するには 2 つの方法があります。
- ユーザー自身がマネージド ID を使ってシークレットを挿入します。
- シークレット挿入機能を使ってシークレットを挿入します。
どちらの方法にも 2 つのステップが含まれます。
- 最初に、エンドポイント ID を使ってシークレット ストアからシークレットを取得します。
- 次に、シークレットをユーザー コンテナーに挿入します。
マネージド ID を使用したシークレットの挿入
デプロイの定義で、エンドポイント ID を使ってシークレット ストアから API を呼び出す必要があります。 このロジックは、スコアリング スクリプトまたは BYOC コンテナーで実行するシェル スクリプトで実装できます。 マネージド ID を使ったシークレットの挿入の実装については、外部サービスと対話するためのマネージド ID の使用の例をご覧ください。
シークレット挿入機能を使用したシークレットの挿入
シークレット挿入機能を使うには、デプロイの定義で、ワークスペース接続または Key Vault の (参照したい) シークレットを環境変数にマップします。 この方法を使うと、スコアリング スクリプトや BYOC コンテナーで実行するシェル スクリプトで、コードを記述する必要がありません。 ワークスペース接続または Key Vault のシークレットを環境変数にマップするには、次の条件が満たされている必要があります。
- エンドポイントの作成時に、既定のシークレット ストア (現在のワークスペースの下のワークスペース接続) へのアクセスを強制するようにオンライン エンドポイントが定義されていた場合、エンドポイントにデプロイを作成するユーザー ID は、ワークスペース接続からシークレットを読み取るアクセス許可を持っている必要があります。
- デプロイで使わるエンドポイント ID には、デプロイの定義で参照されているように、ワークスペース接続または Key Vault からシークレットを読み取るためのアクセス許可が必要です。
Note
- SAI と、既定のシークレット ストアへのアクセスを強制するように設定されたフラグを使って、エンドポイントが正常に作成された場合、エンドポイントにはワークスペース接続に対するアクセス許可が自動的に付与されます。
- エンドポイントで UAI が使われていた場合、または既定のシークレット ストアへのアクセスを強制するフラグが設定されていなかった場合は、エンドポイント ID にワークスペース接続に対するアクセス許可がない可能性があります。 そのような状況では、ワークスペース接続に対するロールをエンドポイント ID に手動で割り当てる必要があります。
- エンドポイント ID が外部 Key Vault に対するアクセス許可を自動的に受け取ることはありません。 Key Vault をシークレット ストアとして使っている場合は、Key Vault のロールをエンドポイント ID に手動で割り当てる必要があります。
シークレットの挿入の使用について詳しくは、シークレットの挿入を使用したオンライン エンドポイントへの機械学習モデルのデプロイ (プレビュー) に関する記事をご覧ください。