Доступ к секретам из онлайн-развертывания с помощью внедрения секретов (предварительная версия)

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ:Расширение машинного обучения Azure CLI версии 2 (current)Python SDK azure-ai-ml версии 2 (current)

В этой статье вы узнаете, как использовать внедрение секретов с веб-конечной точкой и развертыванием для доступа к секретам из хранилища секретов.

Содержание:

  • Настройка удостоверения пользователя и его разрешений
  • Создание подключений к рабочей области и /или хранилищ ключей для использования в качестве хранилищ секретов
  • Создание конечной точки и развертывания с помощью функции внедрения секретов

Важно!

Эта функция сейчас доступна в виде общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания. Ее не следует использовать для производственных рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены.

Дополнительные сведения см. в статье Дополнительные условия использования Предварительных версий Microsoft Azure.

Необходимые компоненты

  • Для использования машинного обучения Azure необходима подписка Azure. Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе. Опробуйте бесплатную или платную версию Машинного обучения Azure уже сегодня.

  • Установите и настройте расширение Машинное обучение Azure CLI (версии 2) или пакет SDK для Python Машинное обучение Azure версии 2.

  • Группа ресурсов Azure, в которой у вас (или вашего субъекта-службы) должен быть доступ User Access Administrator и Contributor. У вас будет такая группа ресурсов, если вы настроили расширение Машинное обучение Azure, как указано ранее.

  • Рабочая область Машинного обучения Azure. У вас будет рабочая область, если вы настроили расширение Машинное обучение Azure, как указано ранее.

  • Любая обученная модель машинного обучения готова к оценке и развертыванию.

Выбор хранилища секретов

Вы можете сохранить секреты (например, ключи API) с помощью следующих способов:

  • Подключения к рабочей области. Если вы используете это хранилище секретов, вы можете позже предоставить удостоверение конечной точки (во время создания конечной точки) для автоматического чтения секретов из подключений к рабочей области, если выполняются определенные условия. Дополнительные сведения см. на вкладке удостоверения, назначаемого системой, в разделе "Создание конечной точки ".
  • Хранилища ключей, которые не обязательно используются в рабочей области. Если вы используете такое хранилище секретов, удостоверение конечной точки не будет предоставлено разрешение на чтение секретов из хранилищ ключей автоматически. Таким образом, если вы хотите использовать службу управляемого хранилища ключей, например Microsoft Azure Key Vault в качестве секретного хранилища, необходимо назначить соответствующую роль позже.

Использование подключения к рабочей области в качестве хранилища секретов

Вы можете создать подключения к рабочей области для использования в развертывании. Например, можно создать подключение к службе Microsoft Azure OpenAI с помощью Подключение рабочих областей — создание REST API.

Кроме того, можно создать настраиваемое подключение с помощью Студия машинного обучения Azure (см. инструкции по созданию настраиваемого подключения для потока запроса) или Azure AI Studio (см. инструкции по созданию настраиваемого подключения в AI Studio).

  1. Создайте подключение 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"
        }
    }
}

  2. Кроме того, можно создать настраиваемое подключение:

    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",
        }
    }
}

  3. Убедитесь, что удостоверение пользователя может считывать секреты из подключения к рабочей области, используя Подключение ions рабочей области — REST API списка секретов (предварительная версия).

    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}}

Примечание.

Предыдущие фрагменты кода используют маркер в заголовке Authorization при выполнении вызовов REST API. Маркер можно получить, выполнив команду az account get-access-token. Дополнительные сведения о получении маркера см. в статье "Получение маркера доступа".

(Необязательно) Использование Azure Key Vault в качестве хранилища секретов

Создайте хранилище ключей и задайте секрет для использования в развертывании. Дополнительные сведения о создании хранилища ключей см. в статье "Настройка и извлечение секрета из Azure Key Vault" с помощью Azure CLI. Также

  1. Создайте Azure Key Vault:

    az keyvault create --name mykeyvault --resource-group myrg --location eastus

  2. Создайте секрет:

    az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>

    Эта команда возвращает созданную секретную версию. Вы можете проверка id свойство ответа, чтобы получить секретную версию. Возвращенный ответ выглядит следующим образом https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Убедитесь, что удостоверение пользователя может прочитать секрет из хранилища ключей:

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

Важно!

Если вы используете хранилище ключей в качестве хранилища секретов для внедрения секретов, необходимо настроить модель разрешений хранилища ключей в качестве управления доступом на основе ролей Azure (RBAC). Дополнительные сведения см. в статье Azure RBAC и политика доступа для Key Vault.

Выбор удостоверения пользователя

Выберите удостоверение пользователя, которое будет использоваться для создания веб-конечной точки и сетевого развертывания. Это удостоверение пользователя может быть учетной записью пользователя, учетной записью субъекта-службы или управляемым удостоверением в идентификаторе Microsoft Entra. Чтобы настроить удостоверение пользователя, выполните действия, описанные в разделе "Настройка проверки подлинности для Машинное обучение 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) конечной точки, не будет автоматически предоставлено разрешение на чтение секретов из хранилищ ключей. Поэтому удостоверение пользователя не должно быть назначено роли для Key Vault.

  • Если вы хотите использовать назначаемое пользователем удостоверение (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 или Key Vault:

    1. Перейдите на вкладку управления доступом (IAM).
    2. Нажмите кнопку "Проверить доступ" и найдите удостоверение.
    3. Убедитесь, что правая роль отображается на вкладке "Текущие назначения ролей".

Создание конечной точки

Если вы используете назначаемое системой удостоверение (SAI) в качестве удостоверения конечной точки, укажите, следует ли применять доступ к хранилищам секретов по умолчанию (а именно подключения к рабочей области) к удостоверению конечной точки.

  1. Создайте файл 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

  2. Создайте конечную точку с помощью 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 для операций плоскости данных Key Vault.

Создание развертывания

  1. Создайте скрипт оценки или Dockerfile и связанные скрипты, чтобы развертывание потребляло секреты с помощью переменных среды.

    • Вам не нужно вызывать API-интерфейсы извлечения секретов для подключений к рабочей области или хранилищ ключей. Переменные среды заполняются секретами при запуске пользовательского контейнера в развертывании.

    • Значение, которое внедряется в переменную среды, может быть одним из трех типов:

      • Весь ответ API секретов списка (предварительная версия). Вам потребуется понять структуру ответа API, проанализировать ее и использовать ее в контейнере пользователя.
      • Отдельный секрет или метаданные из подключения к рабочей области. Его можно использовать без понимания структуры отклика API подключения к рабочей области.
      • Отдельная версия секрета из Key Vault. Его можно использовать без понимания структуры отклика API Key Vault.

  2. Инициируйте создание развертывания с помощью скрипта оценки (если используется пользовательская модель) или 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.net/secrets/<secret_name>/<secret_version>}} Значение секретной версии внедряется в переменную среды.

    Например:

    1. Создайте 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}}

    2. Создание развертывания:

      az ml online-deployment create -f deployment.yaml

enforce_access_to_default_secret_stores Если флаг был установлен для конечной точки, разрешение удостоверения пользователя на чтение секретов из подключений к рабочей области будет проверка как во время создания конечной точки, так и во время создания развертывания. Если удостоверение пользователя не имеет разрешения, создание завершится ошибкой.

Во время создания развертывания, если любая переменная среды сопоставляется со значением, которое соответствует шаблонам в предыдущей таблице, извлечение секретов и внедрение будет выполнено с удостоверением конечной точки (SAI или UAI). Если удостоверение конечной точки не имеет разрешения на чтение секретов из указанных хранилищ секретов (подключения к рабочей области или хранилища ключей), создание развертывания завершится ошибкой. Кроме того, если указанная ссылка на секрет не существует в хранилищах секретов, создание развертывания завершится ошибкой.

Дополнительные сведения об ошибках, которые могут возникнуть во время развертывания Машинное обучение Azure сетевых конечных точек, см. в разделе "Ошибки внедрения секретов".

Использование секретов

Секреты можно использовать, извлекая их из переменных среды в контейнере пользователя, работающем в развертываниях.

Связанный контент