你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 容器应用自定义容器会话

项目
11/07/2024

除 Azure 容器应用动态会话提供的内置代码解释器外，还可以使用自定义容器来定义自己的会话沙盒。

用于自定义容器会话

使用自定义容器，可以生成满足你需求的解决方案。你可以通过自定义容器在快捷的临时环境中执行代码或运行应用程序，并使用 Hyper-V 提供安全的沙盒空间。此外，还可以使用可选的网络隔离来配置自定义容器。示例包括：

代码解释器：需要使用内置解释器不支持的语言在安全沙盒中执行不受信任的代码时，或者需要完全控制代码解释器环境时。
独立执行：需要在敌对的多租户场景中运行应用程序时，在这种场景下，每个租户或用户都有自己的沙盒环境。这些环境彼此隔离，并且与主机应用程序也隔离。一些例子包括运行用户提供的代码的应用程序、允许终端用户访问基于云的 shell 的代码、AI 代理和开发环境。

使用自定义容器会话

要使用自定义容器会话，首先应使用自定义容器映像创建会话池。 Azure 容器应用会使用提供的映像自动在其自己的 Hyper-V 沙盒中启动容器。容器启动后，该容器可供会话池使用。

当应用程序请求会话时，系统会立即从池中分配实例。会话保持活动状态，直到进入空闲状态，然后自动停止并销毁。

创建自定义容器会话池

若要创建自定义容器会话池，需要提供容器映像和池配置设置。

使用 HTTP 请求调用或与每个会话通信。自定义容器必须在指定的端口上公开 HTTP 服务器才能响应这些请求。

Azure CLI
Azure Resource Manager

若要使用 Azure CLI 创建自定义容器会话池，请使用以下命令确保安装最新版本的 Azure CLI 和 Azure 容器应用扩展：

az upgrade
az extension add --name containerapp --upgrade --allow-preview true -y

自定义容器会话池需要启用了工作负载配置文件的 Azure 容器应用环境。如果没有环境，请使用 az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles 命令创建一个。

使用 az containerapp sessionpool create 命令创建自定义容器会话池。

以下示例使用自定义容器映像 myregistry.azurecr.io/my-container-image:1.0 创建名为 my-session-pool 的会话池。

在发送请求之前，请将 <> 括号之间的占位符替换为适合你的会话池和会话标识符的值。

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --environment <ENVIRONMENT> \
    --registry-server myregistry.azurecr.io \
    --registry-username <USER_NAME> \
    --registry-password <PASSWORD> \
    --container-type CustomContainer \
    --image myregistry.azurecr.io/my-container-image:1.0 \
    --cpu 0.25 --memory 0.5Gi \
    --target-port 80 \
    --cooldown-period 300 \
    --network-status EgressDisabled \
    --max-sessions 10 \
    --ready-sessions 5 \
    --env-vars "key1=value1" "key2=value2" \
    --location <LOCATION>

此命令使用以下设置创建会话池：

参数	价值	说明
`--name`	`my-session-pool`	会话池的名称。
`--resource-group`	`my-resource-group`	包含会话池的资源组。
`--environment`	`my-environment`	容器应用环境的名称或资源 ID。
`--container-type`	`CustomContainer`	会话池的容器类型。必须为自定义容器会话的 `CustomContainer`。
`--image`	`myregistry.azurecr.io/my-container-image:1.0`	用于会话池的容器映像。
`--registry-server`	`myregistry.azurecr.io`	容器注册表服务器主机名。
`--registry-username`	`my-username`	用于登录容器注册表的用户名。
`--registry-password`	`my-password`	用于登录容器注册表的密码。
`--cpu`	`0.25`	所需的 CPU 核心数。
`--memory`	`0.5Gi`	所需的内存。
`--target-port`	`80`	用于入口流量的会话端口。
`--cooldown-period`	`300`	会话终止之前会话可以空闲的秒数。每次调用会话的 API 都会重置空闲时间。值必须介于 `300` 和 `3600` 之间。
`--network-status`	指定是否允许从会话发送出站网络流量。有效值为 `EgressDisabled`（默认值）和 `EgressEnabled`。
`--max-sessions`	`10`	可以同时分配的最大会话数。
`--ready-sessions`	`5`	会话池中始终处于就绪状态的目标会话数。如果会话的分配速度快于池的补充速度，请增加此数字。
`--env-vars`	`"key1=value1" "key2=value2"`	要在容器中设置的环境变量。
`--location`	`"Supported Location"`	会话池的位置。

若要检查会话池的状态，请使用 az containerapp sessionpool show 命令：

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

若要更新会话池，请使用 az containerapp sessionpool update 命令。

若要使用 Azure 资源管理器创建自定义容器会话池，请使用 Microsoft.ContainerApps/sessionPools 资源类型创建会话池资源。以下示例演示了一个用于创建自定义容器会话池的 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
    },
    "secrets": [
      {
        "name": "registrypassword",
        "value": "<REGISTRY_PASSWORD>"
      }
    ],
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "username": "myregistry",
          "passwordSecretRef": "registrypassword"
      },
      "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"
    }
  }
}

此模板使用以下设置创建会话池：

参数	价值	说明
`name`	`my-session-pool`	会话池的名称。
`location`	`westus2`	会话池的位置。
`environmentId`	`/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>`	容器应用环境的资源 ID。
`poolManagementType`	`Dynamic`	必须为自定义容器会话的 `Dynamic`。
`containerType`	`CustomContainer`	会话池的容器类型。必须为自定义容器会话的 `CustomContainer`。
`scaleConfiguration.maxConcurrentSessions`	`10`	可以同时分配的最大会话数。
`scaleConfiguration.readySessionInstances`	`5`	会话池中始终处于就绪状态的目标会话数。如果会话的分配速度快于池的补充速度，请增加此数字。
`dynamicPoolConfiguration.executionType`	`Timed`	会话池的执行类型。必须为自定义容器会话的 `Timed`。
`dynamicPoolConfiguration.cooldownPeriodInSeconds`	`600`	会话终止之前会话可以空闲的秒数。每次调用会话的 API 都会重置空闲时间。值必须介于 `300` 和 `3600` 之间。
`secrets`	`[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]`	机密列表。
`customContainerTemplate.registryCredentials.server`	`myregistry.azurecr.io`	容器注册表服务器主机名。
`customContainerTemplate.registryCredentials.username`	`myregistry`	用于登录容器注册表的用户名。
`customContainerTemplate.registryCredentials.passwordSecretRef`	`registrypassword`	包含用于登录到容器注册表的密码的机密的名称。
`customContainerTemplate.containers[0].image`	`myregistry.azurecr.io/my-container-image:1.0`	用于会话池的容器映像。
`customContainerTemplate.containers[0].name`	`mycontainer`	容器的名称。
`customContainerTemplate.containers[0].resources.cpu`	`0.25`	所需的 CPU 核心数。
`customContainerTemplate.containers[0].resources.memory`	`0.5Gi`	所需的内存。
`customContainerTemplate.containers[0].env`	名称值对数组	要在容器中设置的环境变量。
`customContainerTemplate.containers[0].command`	`["/bin/sh"]`	要在容器中运行的命令。
`customContainerTemplate.containers[0].args`	`["-c", "while true; do echo hello; sleep 10;done"]`	要传递给命令的参数。
`customContainerTemplate.containers[0].ingress.targetPort`	`80`	用于入口流量的会话端口。
`sessionNetworkConfiguration.status`	`EgressDisabled`	指定是否允许从会话发送出站网络流量。有效值为 `EgressDisabled`（默认值）和 `EgressEnabled`。

重要

如果会话用于运行不受信任的代码，请勿包含你不希望不受信任的代码访问的信息或数据。假设代码是恶意的，并且对容器具有完全访问权限，包括其环境变量、机密和文件。

图像缓存

创建或更新会话池时，Azure 容器应用会缓存池中的容器映像。此缓存有助于加快创建新会话的过程。

对映像所做的任何更改都不会自动反映在会话中。若要更新映像，请使用新的映像标记更新会话池。对每个映像更新使用唯一标记，以确保拉取新映像。

处理会话

应用程序使用会话池的管理 API 与会话交互。

自定义容器会话的池管理终结点遵循以下格式：https://<SESSION_POOL>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io。

若要检索会话池的管理终结点，请使用 az containerapp sessionpool show 命令：

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

对池管理终结点的所有请求都必须包含具有持有者令牌的 Authorization 标头。若要了解如何使用池管理 API 进行身份验证，请参阅身份验证。

每个 API 请求还必须包含具有会话 ID 的查询字符串参数 identifier。此唯一会话 ID 使应用程序能够与特定会话进行交互。若要了解有关会话标识符的详细信息，请参阅会话标识符。

重要

会话标识符是敏感信息，需要通过一个安全的过程来创建和管理它的值。要保护此值，应用程序必须确保每个用户或租户仅有权访问其自己的会话。如果未能保护对会话的访问，可能会导致滥用或未经授权地访问存储在用户会话中的数据。有关详细信息，请参阅“会话标识符”

将请求转发到会话的容器：

基础池管理终结点后面的路径中的任何内容都将转发到会话的容器。

例如，如果调用 <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile，请求将路由到会话的容器 0.0.0.0:<TARGET_PORT>/api/uploadfile。

连续会话交互：

可以继续向同一会话发出请求。如果会话的请求时间超过冷却期，则会自动删除会话。

示例请求

以下示例展示了用户 ID 对自定义容器会话的请求。

在发送请求之前，请将 <> 括号之间的占位符替换为特定于你的请求的值。

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

此请求将转发到具有用户 ID 标识符的自定义容器会话。如果会话尚未运行，则 Azure 容器应用会在转发请求之前从池分配会话。

在此示例中，会话的容器在 http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER> 接收请求。

使用托管标识

来自 Microsoft Entra ID 的托管标识允许你的自定义容器会话池及其会话访问其他 Microsoft Entra 保护的资源。有关 Microsoft Entra ID 中的托管标识的详细信息，请参阅 Azure 资源的托管标识。

可以为自定义容器会话池启用托管标识。系统分配的托管标识和用户分配的托管标识均受支持。

可通过两种方法将托管标识用于自定义容器会话池：

映像拉取身份验证：使用托管标识向容器注册表进行身份验证以拉取容器映像。
资源访问：在会话中使用会话池的托管标识访问其他 Microsoft Entra 保护的资源。由于其安全影响，此功能默认禁用。

重要

如果启用对会话中的托管标识的访问，则会话中运行的任何代码或程序都可以为池的托管标识创建 Entra 令牌。由于会话通常运行不受信任的代码，因此请谨慎使用此功能。

Azure CLI
Azure Resource Manager

若要为自定义容器会话池启用托管标识，请使用 Azure 资源管理器。

若要为自定义容器会话池启用托管标识，请将 identity 属性添加到会话池资源。 identity 属性必须具有带有 SystemAssigned 或 UserAssigned 值的 type 属性。有关如何配置此属性的详细信息，请参阅配置托管标识。

以下示例演示了一个 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>`	用于映像拉取身份验证的托管标识的资源 ID。
`managedIdentitySettings.identity`	`<IDENTITY_RESOURCE_ID>`	在会话中使用的托管标识的资源 ID。
`managedIdentitySettings.lifecycle`	`None`	托管标识可用的会话生命周期。 - `None`（默认）：会话无法访问标识。它仅用于映像拉取。 - `Main`：除了映像拉取外，主会话还可以访问标识。请谨慎使用。

Logging

与名为 AppEnvSessionConsoleLogs_CL 的表中的 Azure 容器应用环境关联的 Azure Log Analytics 工作区中提供了来自自定义容器会话的控制台日志。

计费

自定义容器会话根据会话池消耗的资源计费。有关详细信息，请参阅“Azure 容器应用计费”。

后续步骤

Azure 容器应用动态会话概述

通过