使用机密注入从联机部署访问机密（预览版）

项目
09/13/2024

适用范围：Azure CLI ml 扩展 v2（最新版）Python SDK azure-ai-ml v2（最新版）

本文介绍如何将机密注入用于联机终结点和部署，以便从机密存储访问机密。

你将了解以下内容：

设置用户标识及其权限
创建工作区连接和/或密钥保管库以用作机密存储
使用机密注入功能创建终结点和部署

重要

此功能目前处于公开预览状态。此预览版在提供时没有附带服务级别协议，我们不建议将其用于生产工作负荷。某些功能可能不受支持或者受限。

有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

先决条件

若要使用 Azure 机器学习，必须有一个 Azure 订阅。如果没有 Azure 订阅，可在开始前创建一个试用帐户。立即试用免费版或付费版的 Azure 机器学习。
安装和配置 Azure 机器学习 CLI (v2) 扩展或 Azure 机器学习 Python SDK (v2)。
一个 Azure 资源组，你（或者你使用的服务主体）在此资源组中需要拥有 User Access Administrator 和 Contributor 访问权限。如果按前面所述配置了 Azure 机器学习扩展，你将拥有这样的资源组。
Azure 机器学习工作区。如果按前面所述配置了 Azure 机器学习扩展，你将拥有一个工作区。
任何已训练的机器学习模型，可用于评分和部署。

选择机密存储

可以使用以下任一方法选择存储机密（如 API 密钥）：

工作区下的工作区连接：如果使用此类机密存储，则以后可以授予终结点标识（在创建终结点时）相应权限，以自动从工作区连接读取机密，前提是满足某些条件。有关详细信息，请参阅创建终结点中的系统分配标识选项卡。
密钥保管库不一定在工作区下：如果使用此类机密存储，则不会向终结点标识授予从密钥保管库中自动读取机密的权限。因此，如果要将托管密钥保管库服务（如 Azure Key Vault）用作机密存储，必须稍后分配适当的角色。

使用工作区连接作为机密存储

可以创建工作区连接，以在部署中使用。例如，可以使用工作区连接 - 创建 REST API 创建到 Azure OpenAI 服务的连接。

或者，可以使用 Azure 机器学习工作室创建自定义连接（请参阅如何为提示流创建自定义连接）。

创建 Azure OpenAI 连接：

PUT https://management.chinacloudapi.cn/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.chinacloudapi.cn/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",
        }
    }
}

使用工作区连接 - 列出机密 REST API（预览版），验证用户标识是否可以从工作区连接读取机密。

POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview
Authorization: Bearer {{token}}

注意

在进行 REST API 调用时，前面的代码片段会使用 Authorization 标头中的令牌。可以通过运行 az account get-access-token 来获取令牌。有关获取令牌的详细信息，请参阅获取访问令牌。

（可选）使用 Azure Key Vault 作为机密存储

创建密钥保管库并设置用于部署的机密。有关创建密钥保管库的详细信息，请参阅使用 Azure CLI 在 Azure Key Vault 中设置和检索机密。此外，

az keyvault CLI 和设置机密 REST API 会显示如何设置机密。
az keyvault secret show CLI 和 Get Secret Versions REST API 会显示如何检索机密版本。

创建 Azure 密钥保管库：

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.cn/secrets/<secret_name>/<secret_version>。

验证用户标识是否可以从密钥保管库读取机密：

az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>

重要

如果将密钥保管库用作机密存储进行机密注入，则必须将密钥保管库的权限模型配置为 Azure 基于角色的访问控制 (RBAC)。有关详细信息，请参阅 Azure RBAC 与密钥保管库的访问策略。

选择用户标识

选择用于创建联机终结点和联机部署的用户标识。此用户标识可以是用户帐户、服务主体帐户或 Microsoft Entra ID 中的托管标识。若要设置用户标识，请按照为 Azure 机器学习资源和工作流设置身份验证中的步骤操作。

（可选）将角色分配给用户标识

如果用户标识希望终结点的系统分配标识 (SAI) 自动获得从工作区连接读取机密的权限，则用户标识必须在工作区范围内具有Azure Machine Learning Workspace Connection Secrets Reader角色（或更高）。
- 具有Microsoft.Authorization/roleAssignments/write权限的管理员可以运行 CLI 命令，以便将角色分配给用户标识：
```
az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
```
注意

终结点的系统分配标识 (SAI)不会自动获得从密钥保管库读取机密的权限。因此，无需为用户标识分配密钥保管库的角色。

如果要为终结点使用用户分配的标识 (UAI)，则无需将角色分配给用户标识。如果打算使用机密注入功能，正确的做法是，必须手动将角色分配给终结点的 UAI。

具有Microsoft.Authorization/roleAssignments/write权限的管理员可以运行以下命令，以便将角色分配给终结点标识：

对于工作区连接：

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 门户中的资源，验证标识（用户标识或终结点标识）是否分配了角色。例如，在 Azure 机器学习工作区或密钥保管库中：
1. 选择“访问控制 (IAM)”选项卡。
2. 选择“检查访问”按钮并查找标识。
3. 验证正确的角色是否显示在“当前角色分配”选项卡下。

如果使用系统分配的标识 (SAI) 作为终结点标识，请指定是否要对终结点标识强制授予对默认机密存储（即工作区下的工作区连接）的访问。

创建 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。

如果满足以下条件，终结点标识将自动授予工作区范围内的 Azure Machine Learning Workspace Connection Secrets Reader 角色（或更高版本）：

创建终结点的用户标识有权从工作区连接 (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action) 读取机密。
终结点使用 SAI。
终结点使用标志定义为在创建终结点时强制访问默认机密存储（当前工作区下的工作区连接）。

系统不会自动向终结点标识授予从 Key Vault 读取机密的角色。如果要将 Key Vault 用作机密存储，则需要在密钥保管库的范围内手动分配适当的角色（例如 Key Vault Secrets User）到终结点标识。有关角色的详细信息，请参阅 Key Vault 数据平面操作的 Azure 内置角色。

如果使用用户分配的标识 (UAI) 作为终结点标识，则不允许指定 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 时，必须手动将任何必需的角色分配给终结点标识，如可选部分将角色分配给用户标识中所述。

创建部署

创作评分脚本或 Dockerfile 和相关脚本，以便部署可以通过环境变量使用机密。
- 无需为工作区连接或密钥保管库调用机密检索 API。当部署中的用户容器启动时，环境变量将填充机密。
- 注入环境变量的值可以是以下三种类型之一：
  - 整个列表机密 API（预览版）响应。你需要了解 API 响应结构，对其进行分析，并将其用于用户容器。
  - 工作区连接中的单个机密或元数据。无需了解工作区连接 API 响应结构即可使用它。
  - 密钥保管库中的单个机密版本。无需了解密钥保管库 API 响应结构即可使用它。

使用评分脚本（如果使用自定义模型）或 Dockerfile（如果采用 BYOC 部署方法）启动部署的创建。指定用户在用户容器中期望的环境变量。

如果映射到环境变量的值遵循某些模式，则终结点标识将用于执行机密检索和注入。

模式	行为
`${{azureml://connections/<connection_name>}}`	整个列表机密 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.cn/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.cn/secrets/secret1/secretversion1}}

创建部署：

az ml online-deployment create -f deployment.yaml

如果为终结点设置了 enforce_access_to_default_secret_stores 标志，则会在终结点创建和部署创建时检查用户标识从工作区连接读取机密的权限。如果用户标识没有权限，则创建将失败。

在部署创建时，如果任何环境变量映射到遵循上表中模式的值，则会使用终结点标识（SAI 或 UAI）执行机密检索和注入。如果终结点标识无权从指定的机密存储（工作区连接或密钥保管库）读取机密，则部署创建将失败。此外，如果机密存储中不存在指定的机密引用，则部署创建将失败。

有关在部署 Azure 机器学习联机终结点期间可能发生的错误的详细信息，请参阅机密注入错误。

使用机密

可以通过从部署中运行的用户容器中的环境变量中检索机密来使用这些机密。

通过