Azure Container Apps 自定義容器會話

發行項
11/07/2024

除了 Azure 容器應用程式動態工作階段提供的內建程式碼解釋器之外，您也可以使用自訂容器來定義您自己的工作階段沙箱。

用於自訂容器工作階段

自訂容器可讓您建置專為您需求量身打造的解決方案。它們可讓您在快速且暫時的環境中執行程式碼或執行應用程式，並提供具有 Hyper-V 的安全沙箱空間。此外，可以使用選擇性的網路隔離來設定它們。這些範例包含：

程式碼解釋器：當您需要以內建解釋器不支援的語言在安全沙箱中執行未受信任的程式碼，或需要完全控制程式碼解釋器環境時。
隔離執行：當您需要在惡意的多租用戶案例中執行應用程式，每個租用戶或使用者都有自己的沙箱環境時。這些環境會彼此隔離，且與主應用程式隔離。一些範例包括執行使用者提供程式碼的應用程式、授與使用者存取雲端式殼層、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>

此命令會建立具有下列設定的工作階段集區：

參數	數值	Description
`--name`	`my-session-pool`	工作階段集區的名稱。
`--resource-group`	`my-resource-group`	包含工作階段集區的資源群組。
`--environment`	`my-environment`	容器應用程式環境的名稱或資源識別碼。
`--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 Resource Manager 建立自訂容器工作階段集區，請使用 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"
    }
  }
}

此樣本會建立具有下列設定的工作階段集區：

參數	數值	Description
`name`	`my-session-pool`	工作階段集區的名稱。
`location`	`westus2`	工作階段集區的位置。
`environmentId`	`/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>`	容器應用程式環境的資源識別碼。
`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 Container Apps 會快取集區中的容器映射。此快取有助於加速建立新工作階段的程式。

映像的任何變更都不會自動反映在會話中。若要更新映像，請使用新的映像標記來更新會話集區。針對每個映像更新使用唯一的標籤，以確保已提取新的映像。

使用工作階段

您的應用程式會使用工作階段集區的管理 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 要求也必須包含具有工作階段識別項的查詢字串參數 identifier。這個唯一的工作階段識別項可讓應用程式與特定工作階段進行互動。若要深入了解工作階段識別項，請參閱工作階段識別項。

重要

工作階段識別碼是敏感性資訊，當您建立和管理其值時，需要安全流程。若要保護此值，您的應用程式必須確保每個使用者或租用戶只能存取自己的工作階段。無法保護工作階段的存取，可能會導致濫用或未獲授權存取使用者工作階段中儲存的資料。如需詳細資訊，請參閱工作階段識別項

將要求轉送至工作階段的容器：

基底集區管理端點之後路徑中的任何內容都會轉送至工作階段的容器。

例如，如果您對 <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile 發出呼叫，要求會路由傳送至位於 0.0.0.0:<TARGET_PORT>/api/uploadfile 的工作階段容器。

持續工作階段互動：

您可以繼續對相同的工作階段發出要求。如果沒有工作階段的要求超過冷卻期間，系統會自動刪除工作階段。

範例要求

下列範例顯示依使用者識別碼對自訂容器工作階段的要求。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為您要求特有的值。

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!'"
}

此要求會轉送至具有使用者識別碼的自訂容器工作階段。如果工作階段尚未執行，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 Resource Manager。

若要啟用自定義容器會話集區的受控識別，請將屬性新增 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>": {}
    }
  }
}

此樣本包含下列受控識別的其他設定：

參數	數值	Description
`customContainerTemplate.registryCredentials.identity`	`<IDENTITY_RESOURCE_ID>`	要用於映像提取驗證之受控識別的資源標識碼。
`managedIdentitySettings.identity`	`<IDENTITY_RESOURCE_ID>`	在工作階段中使用的受控識別資源標識碼。
`managedIdentitySettings.lifecycle`	`None`	受控識別可供使用所在的會話生命週期。 - `None` （預設值）：會話無法存取身分識別。它僅用於影像提取。 - `Main`：除了映像提取之外，主要會話也可以存取身分識別。請小心使用。

記錄

自定義容器會話中的控制台記錄可在名為 AppEnvSessionConsoleLogs_CL的數據表中，與 Azure Container Apps 環境相關聯的 Azure Log Analytics 工作區中取得。

計費

自定義容器會話會根據會話集區耗用的資源來計費。如需詳細資訊，請參閱 Azure Container Apps 計費。

下一步

Azure 容器應用程式動態工作階段概觀

共用方式為