Использование динамических сеансов в приложениях контейнеров Azure

Динамические сеансы приложений контейнеров Azure предлагают изолированные, безопасные контексты, если требуется выполнить код или приложения отдельно от других рабочих нагрузок . Сеансы выполняются в пуле сеансов , который обеспечивает немедленный доступ к новым и существующим сеансам. Эти сеансы идеально подходят для сценариев, когда созданные пользователем входные данные должны обрабатываться контролируемым образом или при интеграции сторонних служб, требующих выполнения кода в изолированной среде. Вам не нужно развертывать ресурс приложения-контейнера для использования динамических сеансов, создавать пул сеансов и вызывать ЕГО API управления.

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

Конечная точка управления и маршрутизация

Приложение взаимодействует с сеансом с помощью API управления пулом сеансов. Общие сведения о маршрутизации запросов см. в разделе "Основные понятия".

Чтобы получить конечную точку управления пулами сеансов, см. конечную точку управления пулами сеансов.

https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io

Дополнительные сведения об управлении пулами сеансов см. в конечной точке управления пулами сеансов.

Проверка подлинности и авторизация API управления

Все запросы к API управления пулом сеансов требуют проверки подлинности (AuthN) с использованием маркера Microsoft Entra и авторизации (AuthZ) через роль выполнения сеансов Azure ContainerApps в пуле сеансов. Дополнительные сведения и примеры см. в разделе "Проверка подлинности и авторизация".

Отправка запросов в сеанс

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

Например, при вызове <POOL_MANAGEMENT_ENDPOINT>/api/uploadfileзапрос направляется в контейнер сеанса на целевом порту <TARGET_PORT>/api/uploadfile.

Пример запроса

В следующем примере показано, как отправить запрос в сеанс с помощью идентификатора пользователя в качестве уникального идентификатора сеанса.

Перед отправкой запроса замените заполнители между <> квадратными скобками значениями, определенными для запроса.

POST <POOL_MANAGEMENT_ENDPOINT>/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

Этот запрос направляется в контейнер сеанса с идентификатором, соответствующим ID пользователя.

Если сеанс не существует для заданного идентификатора, приложения контейнеров Azure автоматически выделяет один из пула перед пересылкой запроса.

В этом примере контейнер сеанса получает запрос на целевой порт по адресу <TARGET_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Идентификаторы

Чтобы отправить HTTP-запрос в сеанс, необходимо указать идентификатор сеанса в запросе. Идентификатор сеанса передается в качестве параметра строки запроса с именем identifier в URL-адресе при отправке запроса к сеансу.

• Если сеанс с идентификатором уже существует, запрос отправляется в существующий сеанс.

• Если сеанс с идентификатором не существует, новый сеанс автоматически создается перед отправкой запроса на него.

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

Формат идентификатора

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

Идентификатор сеанса — это строка, которую вы определяете и которая должна быть уникальной в пределах пула сеансов. При создании веб-приложения можно использовать идентификатор пользователя в качестве идентификатора сеанса. При создании чат-бота можно использовать идентификатор беседы.

Идентификатор должен быть строкой длиной от 4 до 128 символов и может содержать только буквенно-цифровые символы и специальные символы из этого списка: |, -&^%$#(){}[];<>

Жизненный цикл сеанса на практике

При совершении повторных вызовов к тому же сеансу сеанс остается выделенным в пуле. Если после завершения периода охлаждения к сеансу не выполняется никаких запросов, то сеанс автоматически уничтожается.

Безопасность

Модель безопасности

Динамические сеансы создаются для запуска ненадежного кода и приложений в безопасной и изолированной среде. Хотя сеансы изолированы друг от друга, все, что находится в одном сеансе, включая файлы и переменные среды, доступно пользователям сеанса.

Настройте сеанс или загрузите в него конфиденциальные данные только в том случае, если вы доверяете его пользователям.

Доступ к сети

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

Лучшие практики

• Безопасные идентификаторы: всегда используйте идентификаторы безопасных сеансов . Создайте идентификаторы сеанса с помощью криптографических методов, чтобы обеспечить уникальные и непредсказуемые значения. Избегайте использования последовательных идентификаторов, которые можно угадать злоумышленником.
• Используйте ПРОТОКОЛ HTTPS: всегда используйте ПРОТОКОЛ HTTPS для шифрования данных при передаче. Это защищает идентификаторы сеансов и любые конфиденциальные данные, обмениваемые между клиентом и сервером, от перехвата.
• Ограничение времени существования сеанса: реализация времени ожидания для сеансов. Например, разрешите неактивность не более 15 минут до автоматического завершения сеанса. Это помогает снизить риски из-за потери или оставленного без присмотра устройства.
• Ограничение видимости сеанса. Задайте строгие элементы управления доступом, чтобы идентификаторы сеансов были видимы только пулу сеансов. Избегайте предоставления идентификаторов сеансов в URL-адресах или журналах.
• Регулярно заменяйте учетные данные сеанса: повторно проверяйте и обновляйте учетные данные, связанные с вашими сеансами. Ротация снижает риск несанкционированного доступа.

Дополнительные рекомендации для пользовательских сеансов контейнеров

• Используйте протоколы безопасной передачи: всегда используйте ПРОТОКОЛ HTTPS для шифрования данных во время передачи, включая идентификаторы сеансов. Этот подход защищает от атак человека в середине.

• Мониторинг действий сеанса: реализация ведения журнала и мониторинга для отслеживания действий сеанса. Используйте эти журналы для выявления необычных шаблонов или потенциальных нарушений безопасности.

• Проверка ввода пользователей. При этом все входные данные пользователя считаются опасными. Используйте методы проверки входных данных и санитарии для защиты от атак на внедрение и обеспечения обработки только доверенных данных.

Проверка подлинности и авторизация

При отправке запросов в сессию через API управления пулом аутентификация выполняется с помощью токенов Microsoft Entra. Только маркеры Microsoft Entra из удостоверения, принадлежащего роли исполнителя сеансов Azure ContainerApps в пуле сеансов, разрешены вызывать API управления пулом.

Чтобы назначить роль удостоверению, используйте следующую команду Azure CLI:

az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

Если вы используете интеграцию с фреймворком большой языковой модели (LLM), фреймворк обрабатывает создание токенов и управление ими. Убедитесь, что приложение настроено с управляемой идентичностью и необходимыми назначениями ролей в пуле сеансов.

Если вы используете конечные точки API управления пула напрямую, необходимо создать маркер и включить его в Authorization заголовок HTTP-запросов. Помимо упомянутых ранее назначений ролей, токен должен содержать утверждение аудитории (aud) со значением https://dynamicsessions.io.

Azure CLI

Чтобы создать токен с помощью Azure CLI, выполните следующую команду:

az account get-access-token --resource https://dynamicsessions.io

C#

В C# можно использовать библиотеку Azure.Identity для генерации токена. Сначала установите библиотеку:

dotnet add package Azure.Identity

Затем используйте следующий код для создания токена:

using Azure.Identity;

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://dynamicsessions.io/.default" }));
var accessToken = token.Token;

JavaScript

В JavaScript можно использовать библиотеку @azure/identity для создания токена. Сначала установите библиотеку:

npm install @azure/identity

Затем используйте следующий код для создания токена:

const { DefaultAzureCredential } = require("@azure/identity");
const { TokenCredential } = require("@azure/core-auth");

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://dynamicsessions.io/.default");
const accessToken = token.token;

Питон

В Python можно использовать библиотеку azure-identity для генерации токена. Сначала установите библиотеку:

pip install azure-identity

Затем используйте следующий код для создания токена:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://dynamicsessions.io/.default")
access_token = token.token

Это важно

Действительный токен используется для создания и доступа к любому сеансу в пуле. Обеспечьте безопасность ваших токенов и не делитесь ими с ненадежными сторонами. Конечные пользователи никогда не должны иметь непосредственный доступ к токенам. Только предоставляйте маркеры приложению и никогда конечным пользователям.

Защита идентификаторов сеанса

Идентификатор сеанса — это конфиденциальная информация, которую необходимо безопасно управлять. Приложение должно гарантировать, что у каждого пользователя или клиента есть доступ только к собственным сеансам.

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

Примеры стратегий включают:

• Один сеанс на пользователя: если приложение использует один сеанс для каждого пользователя, каждый пользователь должен быть безопасно проверен, и приложение должно использовать уникальный идентификатор сеанса для каждого вошедшего в систему пользователя.

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

Это важно

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

Использование управляемого удостоверения

Управляемое удостоверение в Microsoft Entra ID позволяет сеансовым пулам контейнеров и их сеансам получать доступ к другим защищенным ресурсам Microsoft Entra. В пуле сеансов поддерживаются как управляемые системой, так и назначаемые пользователем удостоверения.

Дополнительные сведения об управляемых удостоверениях в Microsoft Entra ID см. в разделе «Управляемые удостоверения для ресурсов Azure».

Существует два способа использования управляемых удостоверений с настраиваемыми пулами сеансов контейнеров:

• Проверка подлинности для извлечения образа: Используйте управляемое удостоверение для проверки подлинности в реестре контейнеров для извлечения образа контейнера.

• Доступ к ресурсам. Используйте управляемое удостоверение пула сеансов в сеансе для доступа к другим защищенным ресурсам Microsoft Entra. Из-за его последствий для безопасности эта возможность отключена по умолчанию.

  Это важно

  Если вы включите доступ к управляемому удостоверению в сеансе, любой код или программы, работающие в сеансе, могут создавать токены Microsoft Entra для управляемого удостоверения пула. Так как сеансы обычно выполняют ненадежный код, используйте эту функцию с крайней осторожностью.

Azure CLI

Чтобы включить управляемое удостоверение для настраиваемого пула сеансов контейнеров, используйте Azure Resource Manager.

Диспетчер ресурсов Azure

Чтобы включить управляемое удостоверение для настраиваемого пула сеансов контейнеров, добавьте identity свойство в ресурс пула сеансов.

Свойство identity должно содержать type со значением SystemAssigned или UserAssigned. Дополнительные сведения о настройке этого свойства см. в разделе Настройка управляемых удостоверений.

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

Перед отправкой запроса замените заполнители между <> скобками соответствующими значениями для пула сеансов и идентификатора сеанса.

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-08-02-preview",
  "name": "my-session-pool",
  "location": "westus2",
  "properties": {
    "environmentId": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>",
    "poolManagementType": "Dynamic",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 600
    },
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "identity": "<IDENTITY_RESOURCE_ID>"
      },
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "name": "mycontainer",
          "resources": {
            "cpu": 0.25,
            "memory": "0.5Gi"
          },
          "command": [
            "/bin/sh"
          ],
          "args": [
            "-c",
            "while true; do echo hello; sleep 10;done"
          ],
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressEnabled"
    },
    "managedIdentitySettings": [
      {
        "identity": "<IDENTITY_RESOURCE_ID>",
        "lifecycle": "None"
      }
    ]
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<IDENTITY_RESOURCE_ID>": {}
    }
  }
}

Этот шаблон содержит следующие параметры управляемой удостоверенности личности:

Параметр	Ценность	Описание
customContainerTemplate.registryCredentials.identity	<IDENTITY_RESOURCE_ID>	Идентификатор ресурса управляемого удостоверения, который используется для аутентификации при извлечении образов.
managedIdentitySettings.identity	<IDENTITY_RESOURCE_ID>	Идентификатор ресурса управляемого удостоверения, используемого в сеансе.
managedIdentitySettings.lifecycle	None	Жизненный цикл сеанса, в течение которого доступно управляемое удостоверение. - None (по умолчанию): сеанс не может получить доступ к удостоверению. Этот параметр используется только для извлечения изображения. - Main: Помимо загрузки изображений, основной сеанс также может получить доступ к идентификационным данным. Используйте с осторожностью.

Лесозаготовка

Динамические сеансы приложений контейнеров Azure интегрируются с Azure Monitor и Log Analytics для сбора журналов, создаваемых во время выполнения сеанса. Действия по настройке одинаковы для интерпретатора кода и настраиваемых пулов сеансов контейнеров, но доступные категории журналов отличаются по типу сеанса. Метрики, возвращаемые с помощью заголовков ответа API, не записываются в Log Analytics.

Различия в журналировании по типу сеанса

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

• Сеансы интерпретатора кода: выходные данные возвращаются из выполнения (включая stdout и stderr), но таблицы Log Analytics AppEnvSession не выводятся. См. ведение журнала сеансов интерпретатора кода.
• Пользовательские сеансы контейнеров: таблицы Log Analytics AppEnvSession создаются, когда ваш контейнер записывает в stdout или stderr, а журналы платформы доступны для жизненного цикла пула и событий. См. ведение журнала пользовательских сеансов контейнеров.
• Common: Метрики, возвращаемые с помощью заголовков ответа API, не записываются в Log Analytics.

Полный список поддерживаемых категорий сеансов в ресурсе среды (Microsoft.App/managedEnvironments) см. в поддерживаемых журналах для Microsoft.App/managedEnvironments.

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

• Типы сеансов: узнайте о различных типах динамических сеансов:

  • Сеансы интерпретатора кода
  • Пользовательские сеансы контейнеров

• Учебники. Работа непосредственно с REST API или с помощью агента LLM:

  • Используйте агента LLM.
    • AutoGen
    • LangChain
    • LlamaIndex
    • Семантическое ядро
  • Использование REST API
    • Интерпретатор кода JavaScript