Azure 容器應用程式自訂容器工作階段 (預覽)

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

注意

Azure 容器應用程式目前處於預覽狀態。 如需詳細資訊，請參閱預覽限制。

用於自訂容器工作階段

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

• 程式碼解釋器：當您需要以內建解釋器不支援的語言在安全沙箱中執行未受信任的程式碼，或需要完全控制程式碼解釋器環境時。

• 隔離執行：當您需要在惡意的多租用戶案例中執行應用程式，每個租用戶或使用者都有自己的沙箱環境時。 這些環境會彼此隔離，且與主應用程式隔離。 一些範例包括執行使用者提供程式碼的應用程式、授與使用者存取雲端式殼層、AI 代理程式和開發環境的程式碼。

使用自訂容器工作階段

若要使用自訂容器工作階段，您必須先建立具有自訂容器映像的工作階段集區。 Azure 容器應用程式會自動使用提供的映像，在自己的 Hyper-V 沙箱中啟動容器。 容器啟動後，即可用於工作階段集區。

當您的應用程式要求工作階段時，執行個體會立即從集區配置。 工作階段會保持作用中狀態，直到其進入閒置狀態，然後會自動停止並終結。

建立自訂容器工作階段集區

若要建立自訂容器工作階段集區，您必須提供容器映像和集區組態設定。

您可以使用 HTTP 要求叫用或與每個工作階段通訊。 自訂容器必須在您指定的連接埠上公開 HTTP 伺服器，以回應這些要求。

Azure CLI

若要使用 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 update 命令。

Azure Resource Manager

若要使用 Azure Resource Manager 建立自訂容器工作階段集區，請使用 Microsoft.ContainerApps/sessionPools 資源類型建立工作階段集區資源。 下列範例顯示建立自訂容器工作階段集區的 ARM 範本程式碼片段。

在傳送要求之前，請將 <> 括弧之間的預留位置取代為工作階段集區和工作階段識別項的適當值。

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-02-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": {
      "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 之間。
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。

重要

如果工作階段用來執行未受信任的程式碼，請勿包含您不想要未受信任程式碼存取的資訊或資料。 假設程式碼是惡意的，且具有容器的完整存取權，包括其環境變數、祕密和檔案。

使用工作階段

您的應用程式會使用工作階段集區的管理 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> 接收要求。

計費

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

下一步

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