シークレット挿入を使ってオンライン デプロイからシークレットにアクセスする (プレビュー)
適用対象:
Azure CLI ml extension v2 (現行)Python SDK azure-ai-ml v2 (現行)
この記事では、オンライン エンドポイントとデプロイでシークレット挿入を使って、シークレット ストアからシークレットにアクセスする方法について説明します。
次のことを学習します。
- ユーザー ID とそのアクセス許可を設定する
- シークレット ストアとして使うワークスペース接続やキー コンテナーを作成する
- シークレット挿入機能を使ってエンドポイントとデプロイを作成する
重要
現在、この機能はパブリック プレビュー段階にあります。 このプレビュー バージョンはサービス レベル アグリーメントなしで提供されており、運用環境のワークロードに使用することは推奨されません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。
詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。
前提条件
Azure Machine Learning を使用するには、Azure サブスクリプションが必要です。 Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。 無料版または有料版の Azure Machine Learning を今すぐお試しください。
Azure Machine Learning CLI (v2) 拡張機能または Azure Machine Learning Python SDK (v2) をインストールして構成します。
Azure Resource グループが必要です。そのグループで (または使用するサービス プリンシパルで)
User Access AdministratorとContributorのアクセス権を持っている必要があります。 上記のように Azure Machine Learning 拡張機能を構成すると、このようなリソース グループが作成されます。Azure Machine Learning ワークスペース。 上記のように Azure Machine Learning 拡張機能を構成すると、ワークスペースが作成されます。
スコアリングとデプロイの準備が整ったトレーニング済みの機械学習モデル。
シークレット ストアの選択
シークレット (API キーなど) の格納に次のいずれかを使うことを選択できます。
- ワークスペース下のワークスペース接続: この種類のシークレット ストアを使う場合、指定された特定の条件が満たされていれば、後で (エンドポイントの作成時に) エンドポイント ID に、ワークスペース接続からシークレットを自動的に読み取るアクセス許可を付与できます。 詳細については、「エンドポイントの作成」セクションの [システム割り当て ID] タブを参照してください。
- キー コンテナー (必ずしもワークスペース下にあるとは限らない): この種類のシークレット ストアを使用する場合、エンドポイント ID には、キー コンテナーからシークレットを自動的に読み取るアクセス許可は付与されません。 そのため、Microsoft Azure Key Vault などのマネージド キー コンテナー サービスをシークレット ストアとして使う場合は、後で適切なロールを割り当てる必要があります。
ワークスペース接続をシークレット ストアとして使う
デプロイで使うワークスペース接続を作成できます。 たとえば、ワークスペース接続 - Create REST API を使って、Microsoft Azure OpenAI Service への接続を作成できます。
または、Azure Machine Learning スタジオ (プロンプト フロー用のカスタム接続を作成する方法に関する記事を参照) または Azure AI Studio (AI Studio でカスタム接続を作成する方法に関する記事を参照) を使ってカスタム接続を作成することもできます。
Azure OpenAI 接続を作成します。
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview Authorization: Bearer {{token}} Content-Type: application/json { "properties": { "authType": "ApiKey", "category": "AzureOpenAI", "credentials": { "key": "<key>", "endpoint": "https://<name>.openai.azure.com/", }, "expiryTime": null, "target": "https://<name>.openai.azure.com/", "isSharedToAll": false, "sharedUserList": [], "metadata": { "ApiType": "Azure" } } }または、カスタム接続を作成することもできます。
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview Authorization: Bearer {{token}} Content-Type: application/json { "properties": { "authType": "CustomKeys", "category": "CustomKeys", "credentials": { "keys": { "OPENAI_API_KEY": "<key>", "SPEECH_API_KEY": "<key>" } }, "expiryTime": null, "target": "_", "isSharedToAll": false, "sharedUserList": [], "metadata": { "OPENAI_API_BASE": "<oai endpoint>", "OPENAI_API_VERSION": "<oai version>", "OPENAI_API_TYPE": "azure", "SPEECH_REGION": "eastus", } } }ワークスペース接続 - List Secrets REST API (プレビュー) を使って、ユーザー ID がワークスペース接続からシークレットを読み取れることを確認します。
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview Authorization: Bearer {{token}}
Note
前のコード スニペットでは、REST API 呼び出しを行うときに Authorization ヘッダーのトークンを使います。 az account get-access-token を実行するとトークンを取得できます。 トークンの取得の詳細については、アクセス トークンの取得に関する記事を参照してください。
(省略可能) Azure Key Vault をシークレット ストアとして使う
キー コンテナーを作成し、デプロイで使うシークレットを設定します。 キー コンテナーの作成の詳細については、「Azure CLI を使って Azure Key Vault からシークレットを設定および取得する」を参照してください。 さらに、
- az keyvault CLI と Set Secret REST API では、シークレットを設定する方法を示しています。
- az keyvault secret show CLI と Get Secret Versions REST API では、シークレット バージョンを取得する方法を示しています。
Azure Key Vault を作成します。
az keyvault create --name mykeyvault --resource-group myrg --location eastusシークレットを作成します。
az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>このコマンドは、作成したシークレットのバージョンを返します。 応答の
idプロパティを確認して、シークレットのバージョンを取得できます。 返される応答はhttps://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>のようになります。ユーザー ID がキー コンテナーからシークレットを読み取れることを確認します。
az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>
重要
キー コンテナーをシークレット挿入用のシークレット ストアとして使う場合は、キー コンテナーのアクセス許可モデルを Azure ロールベースのアクセス制御 (RBAC) として構成する必要があります。 詳細については、Key Vault の Azure RBAC とアクセス ポリシーに関する記事を参照してください。
ユーザー ID を選ぶ
オンライン エンドポイントとオンライン デプロイの作成に使うユーザー ID を選びます。 このユーザー ID には、ユーザー アカウント、サービス プリンシパル アカウント、または Microsoft Entra ID のマネージド ID を使用できます。 ユーザー ID を設定するには、「Azure Machine Learning リソースとワークフローの認証を設定する」の手順に従います。
(省略可能) ユーザー ID にロールを割り当てる
ユーザー ID がエンドポイントのシステム割り当て ID (SAI) に、ワークスペース接続からシークレットを読み取るアクセス許可を自動的に付与する必要がある場合、ユーザー ID はワークスペースのスコープ上で
Azure Machine Learning Workspace Connection Secrets Readerロール (またはそれ以上) を持っている必要があります。Microsoft.Authorization/roleAssignments/writeアクセス許可を持つ管理者は、CLI コマンドを実行して、"ユーザー ID" にロールを割り当てることができます。az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
Note
エンドポイントのシステム割り当て ID (SAI) には、キー コンテナーからシークレットを読み取るためのアクセス許可が自動的に付与されません。 そのため、ユーザー ID に Key Vault のロールを割り当てる必要はありません。
エンドポイントにユーザー割り当て ID (UAI) を使う場合は、ユーザー ID にロールを割り当てる必要はありません。 代わりに、シークレット挿入機能を使う場合は、エンドポイントの UAI にロールを手動で割り当てる必要があります。
Microsoft.Authorization/roleAssignments/writeアクセス許可を持つ管理者は、次のコマンドを実行して、"エンドポイント ID" にロールを割り当てることができます。ワークスペース接続の場合:
az role assignment create --assignee <EndpointIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>キー コンテナーの場合:
az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>
Azure portal のリソースに移動して、ID (ユーザー ID またはエンドポイント ID) にロールが割り当てられていることを確認します。 たとえば、Azure Machine Learning ワークスペースまたは Key Vault では次を行います。
- [アクセス制御 (IAM)] タブを選びます。
- [アクセスの確認] ボタンを選び、ID を見つけます。
- [現在のロールの割り当て] タブに適切なロールが表示されていることを確認します。
エンドポイントの作成
システム割り当て ID (SAI) をエンドポイント ID として使っている場合は、既定のシークレット ストア (つまり、ワークスペース下のワークスペース接続) へのアクセスをエンドポイント ID に適用するかどうかを指定します。
endpoint.yamlファイルを作成します。$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json name: my-endpoint auth_mode: key properties: enforce_access_to_default_secret_stores: enabled # default: disabledendpoint.yamlファイルを使ってエンドポイントを作成します。az ml online-endpoint create -f endpoint.yaml
エンドポイント定義で identity プロパティを指定しない場合、エンドポイントでは既定で SAI が使われます。
次の条件が満たされる場合、エンドポイント ID には、ワークスペースのスコープに対する Azure Machine Learning Workspace Connection Secrets Reader ロール (またはそれ以上) が自動的に付与されます。
- エンドポイントを作成するユーザー ID には、ワークスペース接続 (
Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action) からシークレットを読み取るアクセス許可があります。 - エンドポイントで SAI を使用している。
- エンドポイントは、エンドポイントの作成時に既定のシークレット ストア (現在のワークスペースの下のワークスペース接続) へのアクセスを強制するフラグを使用して定義されている。
エンドポイント ID には、Key Vault からシークレットを読み取るロールが自動的に付与されません。 Key Vault をシークレット ストアとして使う場合は、Key Vault のスコープ上の "エンドポイント ID" に、Key Vault Secrets User などの適切なロールを手動で割り当てる必要があります。 ロールの詳細については、「Key Vault データ プレーン操作のための Azure 組み込みロール」を参照してください。
デプロイの作成
デプロイが環境変数を介してシークレットを使用できるように、スコアリング スクリプトまたは Dockerfile と関連スクリプトを作成します。
ワークスペース接続またはキー コンテナーのシークレット取得 API を呼び出す必要はありません。 デプロイ内のユーザー コンテナーが開始されるときに、環境変数にシークレットが設定されます。
環境変数に挿入される値は、次の 3 つの種類のいずれかになります。
- List Secrets API (プレビュー) 応答全体。 API の応答の構造体を理解し、解析して、ユーザー コンテナーで使う必要があります。
- ワークスペース接続からの個々のシークレットまたはメタデータ。 ワークスペース接続 API の応答の構造体を理解していなくても使用できます。
- Key Vault の個別のシークレットのバージョン。 Key Vault API の応答の構造体を理解していなくても使用できます。
スコアリング スクリプト (カスタム モデルを使う場合) または Dockerfile (デプロイに BYOC アプローチを採用する場合) を使って、デプロイの作成を開始します。 ユーザーがユーザー コンテナー内で想定する環境変数を指定します。
環境変数にマップされた値が特定のパターンに従っている場合、エンドポイント ID はシークレットの取得と挿入の実行に使われます。
パターン Behavior ${{azureml://connections/<connection_name>}}List Secrets API (プレビュー) 応答全体が環境変数に挿入されます。 ${{azureml://connections/<connection_name>/credentials/<credential_name>}}資格情報の値が環境変数に挿入されます。 ${{azureml://connections/<connection_name>/metadata/<metadata_name>}}メタデータの値が環境変数に挿入されます。 ${{azureml://connections/<connection_name>/target}}ターゲットの値 (該当する場合) が環境変数に挿入されます。 ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}}シークレットのバージョンの値が環境変数に挿入されます。 次に例を示します。
deployment.yamlを作成します。$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json name: blue endpoint_name: my-endpoint #… environment_variables: AOAI_CONNECTION: ${{azureml://connections/aoai_connection}} LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}} OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}} OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}} USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}デプロイを作成します。
az ml online-deployment create -f deployment.yaml
エンドポイントに enforce_access_to_default_secret_stores フラグが設定されている場合、ワークスペース接続からシークレットを読み取るためのユーザー ID のアクセス許可が、エンドポイントの作成時とデプロイの作成時の両方で検査されます。 ユーザー ID にアクセス許可がない場合、作成は失敗します。
デプロイの作成時に、環境変数が上記の表のパターンに従う値にマップされている場合、シークレットの取得と挿入はエンドポイント ID (SAI または UAI) を使って実行されます。 エンドポイント ID に、指定されたシークレット ストア (ワークスペース接続またはキー コンテナー) からシークレットを読み取るアクセス許可がない場合、デプロイの作成は失敗します。 また、指定されたシークレットの参照がシークレット ストアに存在しない場合、デプロイの作成は失敗します。
Azure Machine Learning オンライン エンドポイントのデプロイ中に発生する可能性のあるエラーの詳細については、シークレット挿入のエラーに関する記事を参照してください。
シークレットを使用する
デプロイで実行されているユーザー コンテナー内の環境変数からシークレットを取得することで、シークレットを使用できます。