シークレット挿入を使ってオンラインデプロイからシークレットにアクセスする (プレビュー)

[アーティクル]
09/03/2024

適用対象: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 では次を行います。
1. [アクセス制御 (IAM)] タブを選びます。
2. [アクセスの確認] ボタンを選び、ID を見つけます。
3. [現在のロールの割り当て] タブに適切なロールが表示されていることを確認します。

システム割り当て 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: disabled

endpoint.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 組み込みロール」を参照してください。

ユーザー割り当て ID (UAI) をエンドポイント ID として使っている場合、enforce_access_to_default_secret_stores フラグを指定することはできません。

endpoint.yaml ファイルを作成します。

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
identity:
    type: user_assigned
    user_assigned_identities: /subscriptions/00000000-0000-0000-000-000000000000/resourcegroups/myrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity

endpoint.yaml ファイルを使ってエンドポイントを作成します。
```
az ml online-endpoint create -f endpoint.yaml
```

UAI を使う場合は、省略可能のセクション「ユーザー ID へのロールの割り当て」の説明に従って、必要なロールをエンドポイント ID に手動で割り当てる必要があります。

デプロイの作成

デプロイが環境変数を介してシークレットを使用できるように、スコアリングスクリプトまたは 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 オンラインエンドポイントのデプロイ中に発生する可能性のあるエラーの詳細については、シークレット挿入のエラーに関する記事を参照してください。

シークレットを使用する

デプロイで実行されているユーザーコンテナー内の環境変数からシークレットを取得することで、シークレットを使用できます。

次の方法で共有

シークレット挿入を使ってオンラインデプロイからシークレットにアクセスする (プレビュー)

前提条件

シークレットストアの選択

ワークスペース接続をシークレットストアとして使う

(省略可能) Azure Key Vault をシークレットストアとして使う

ユーザー ID を選ぶ

(省略可能) ユーザー ID にロールを割り当てる

エンドポイントの作成

デプロイの作成

シークレットを使用する

フィードバック

その他のリソース

次の方法で共有

シークレット挿入を使ってオンライン デプロイからシークレットにアクセスする (プレビュー)

前提条件

シークレット ストアの選択

ワークスペース接続をシークレット ストアとして使う

(省略可能) Azure Key Vault をシークレット ストアとして使う

ユーザー ID を選ぶ

(省略可能) ユーザー ID にロールを割り当てる

エンドポイントの作成

デプロイの作成

シークレットを使用する

関連するコンテンツ

フィードバック

その他のリソース

シークレット挿入を使ってオンラインデプロイからシークレットにアクセスする (プレビュー)

シークレットストアの選択

ワークスペース接続をシークレットストアとして使う

(省略可能) Azure Key Vault をシークレットストアとして使う