Azure Container Apps custom container sessions

Oprócz wbudowanego interpretera kodu, który udostępnia dynamiczne sesje usługi Azure Container Apps, można również użyć kontenerów niestandardowych do zdefiniowania swoich własnych izolowanych środowisk sesji.

Uses for custom container sessions

Kontenery niestandardowe umożliwiają tworzenie rozwiązań dostosowanych do Twoich potrzeb. Umożliwiają one wykonywanie kodu lub uruchamianie aplikacji w środowiskach, które są szybkie i efemeryczne oraz oferują bezpieczne, piaskownicowe miejsca z funkcją Hyper-V. Ponadto można je skonfigurować z opcjonalną izolacją sieci. Przykłady obejmują:

• Interpretery kodu: gdy potrzebujesz wykonać niezaufany kod w bezpiecznych piaskownicach z użyciem języka, który nie jest obsługiwany przez wbudowany interpreter, lub gdy potrzebujesz pełnej kontroli nad środowiskiem interpretera kodu.

• Isolated execution: When you need to run applications in hostile, multitenant scenarios where each tenant or user has their own sandboxed environment. Te środowiska są odizolowane od siebie i od aplikacji hosta. Niektóre przykłady obejmują aplikacje, które uruchamiają kod dostarczony przez użytkownika, kod, który przyznaje użytkownikowi końcowemu dostęp do powłoki opartej na chmurze, agentów sztucznej inteligencji i środowisk deweloperskich.

Using custom container sessions

To use custom container sessions, you first create a session pool with a custom container image. Azure Container Apps automatically starts containers in their own Hyper-V sandboxes using the provided image. Once the container starts up, it's available to the session pool.

When your application requests a session, an instance is instantly allocated from the pool. Sesja pozostaje aktywna, dopóki nie wejdzie w stan bezczynności, który zostanie automatycznie zatrzymany i zniszczony.

Creating a custom container session pool

To create a custom container session pool, you need to provide a container image and pool configuration settings.

You invoke or communicate with each session using HTTP requests. Kontener niestandardowy musi uwidocznić serwer HTTP na porcie określonym w celu odpowiadania na te żądania.

Azure CLI

Aby utworzyć niestandardową pulę sesji kontenera przy użyciu interfejsu wiersza polecenia platformy Azure, upewnij się, że masz najnowsze wersje interfejsu wiersza polecenia platformy Azure i rozszerzenie Azure Container Apps za pomocą następujących poleceń:

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

Custom container session pools require a workload profile enabled Azure Container Apps environment. Jeśli nie masz środowiska, użyj az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles polecenia , aby go utworzyć.

Use the az containerapp sessionpool create command to create a custom container session pool.

The following example creates a session pool named my-session-pool with a custom container image myregistry.azurecr.io/my-container-image:1.0.

Before you send the request, replace the placeholders between the <> brackets with the appropriate values for your session pool and session identifier.

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>

To polecenie tworzy pulę sesji z następującymi ustawieniami:

Parameter	Wartość	Opis
--name	my-session-pool	The name of the session pool.
--resource-group	my-resource-group	The resource group that contains the session pool.
--environment	my-environment	Nazwa lub identyfikator zasobu środowiska aplikacji kontenera.
--container-type	CustomContainer	The container type of the session pool. Must be CustomContainer for custom container sessions.
--image	myregistry.azurecr.io/my-container-image:1.0	The container image to use for the session pool.
--registry-server	myregistry.azurecr.io	Nazwa hosta serwera rejestru kontenerów.
--registry-username	my-username	Nazwa użytkownika do zalogowania się do rejestru kontenerów.
--registry-password	my-password	Hasło do logowania się do rejestru kontenerów.
--cpu	0.25	Wymagana liczba rdzeni procesora.
--memory	0.5Gi	Wymagana pamięć.
--target-port	80	The session port used for ingress traffic.
--cooldown-period	300	Liczba sekund bezczynności sesji przed zakończeniem sesji. The idle period is reset each time the session's API is called. Wartość musi zawierać się między 300 i 3600.
--network-status	EgressDisabled	Określa, czy wychodzący ruch sieciowy jest dozwolony z sesji. Prawidłowe wartości to EgressDisabled (wartość domyślna) i EgressEnabled.
--max-sessions	10	Maksymalna liczba sesji, które można przydzielić w tym samym czasie.
--ready-sessions	5	The target number of sessions that are ready in the session pool all the time. Increase this number if sessions are allocated faster than the pool is being replenished.
--env-vars	"key1=value1" "key2=value2"	Zmienne środowiskowe do ustawienia w kontenerze.
--location	"Supported Location"	The location of the session pool.

To check on the status of the session pool, use the az containerapp sessionpool show command:

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

To update the session pool, use the az containerapp sessionpool update command.

Azure Resource Manager

To create a custom container session pool using Azure Resource Manager, create a session pool resource with the Microsoft.ContainerApps/sessionPools resource type. The following example shows an ARM template snippet that creates a custom container session pool.

Before you send the request, replace the placeholders between the <> brackets with the appropriate values for your session pool and session identifier.

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

Ten szablon tworzy pulę sesji z następującymi ustawieniami:

Parameter	Wartość	Opis
name	my-session-pool	The name of the session pool.
location	westus2	The location of the session pool.
environmentId	/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>	Identyfikator zasobu środowiska aplikacji kontenera.
poolManagementType	Dynamic	Must be Dynamic for custom container sessions.
containerType	CustomContainer	The container type of the session pool. Must be CustomContainer for custom container sessions.
scaleConfiguration.maxConcurrentSessions	10	Maksymalna liczba sesji, które można przydzielić w tym samym czasie.
scaleConfiguration.readySessionInstances	5	The target number of sessions that are ready in the session pool all the time. Increase this number if sessions are allocated faster than the pool is being replenished.
dynamicPoolConfiguration.executionType	Timed	The type of execution for the session pool. Must be Timed for custom container sessions.
dynamicPoolConfiguration.cooldownPeriodInSeconds	600	Liczba sekund bezczynności sesji przed zakończeniem sesji. The idle period is reset each time the session's API is called. Wartość musi zawierać się między 300 i 3600.
secrets	[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]	Lista tajemnic.
customContainerTemplate.registryCredentials.server	myregistry.azurecr.io	Nazwa hosta serwera rejestru kontenerów.
customContainerTemplate.registryCredentials.username	myregistry	Nazwa użytkownika do zalogowania się do rejestru kontenerów.
customContainerTemplate.registryCredentials.passwordSecretRef	registrypassword	Nazwa wpisu tajnego zawierającego hasło do logowania się do rejestru kontenerów.
customContainerTemplate.containers[0].image	myregistry.azurecr.io/my-container-image:1.0	The container image to use for the session pool.
customContainerTemplate.containers[0].name	mycontainer	Nazwa kontenera.
customContainerTemplate.containers[0].resources.cpu	0.25	Wymagana liczba rdzeni procesora.
customContainerTemplate.containers[0].resources.memory	0.5Gi	Wymagana pamięć.
customContainerTemplate.containers[0].env	Array of name-value pairs	Zmienne środowiskowe do ustawienia w kontenerze.
customContainerTemplate.containers[0].command	["/bin/sh"]	The command to run in the container.
customContainerTemplate.containers[0].args	["-c", "while true; do echo hello; sleep 10;done"]	The arguments to pass to the command.
customContainerTemplate.containers[0].ingress.targetPort	80	The session port used for ingress traffic.
sessionNetworkConfiguration.status	EgressDisabled	Określa, czy wychodzący ruch sieciowy jest dozwolony z sesji. Prawidłowe wartości to EgressDisabled (wartość domyślna) i EgressEnabled.

Ważne

Jeśli sesja jest używana do uruchamiania niezaufanego kodu, nie dołączaj informacji ani danych, do których nie chcesz uzyskiwać dostępu za pomocą niezaufanego kodu. Załóżmy, że kod jest złośliwy i ma pełny dostęp do kontenera, w tym jego zmiennych środowiskowych, wpisów tajnych i plików.

Image caching

When a session pool is created or updated, Azure Container Apps caches the container image in the pool. This caching helps speed up the process of creating new sessions.

Wszelkie zmiany obrazu nie są automatycznie odzwierciedlane w sesjach. To update the image, update the session pool with a new image tag. Użyj unikatowego tagu dla każdej aktualizacji obrazu, aby upewnić się, że nowy obraz jest ściągany.

Working with sessions

Aplikacja wchodzi w interakcję z sesją przy użyciu interfejsu API do zarządzania pulą sesji.

A pool management endpoint for custom container sessions follows this format: https://<SESSION_POOL>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io.

To retrieve the session pool's management endpoint, use the az containerapp sessionpool show command:

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

All requests to the pool management endpoint must include an Authorization header with a bearer token. Aby dowiedzieć się, jak uwierzytelniać się za pomocą interfejsu API zarządzania pulą, zobacz Uwierzytelnianie.

Każde żądanie interfejsu API musi również zawierać parametr ciągu zapytania identifier z identyfikatorem sesji. Ten unikatowy identyfikator sesji umożliwia aplikacji interakcję z określonymi sesjami. Aby dowiedzieć się więcej na temat identyfikatorów sesji, zobacz Identyfikatory sesji.

Ważne

Identyfikator sesji jest poufną informacją, która wymaga bezpiecznego procesu podczas tworzenia i zarządzania jego wartością. Aby chronić tę wartość, aplikacja musi zapewnić, że każdy użytkownik lub klient ma dostęp tylko do własnych sesji. Brak bezpiecznego dostępu do sesji może spowodować nieprawidłowe użycie lub nieautoryzowany dostęp do danych przechowywanych w sesjach użytkowników. Aby uzyskać więcej informacji, zobacz Identyfikatory sesji

Przekazywanie żądań do kontenera sesji:

Anything in the path following the base pool management endpoint is forwarded to the session's container.

Jeśli na przykład wykonasz wywołanie metody <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, żądanie jest kierowane do kontenera sesji pod adresem 0.0.0.0:<TARGET_PORT>/api/uploadfile.

Continuous session interaction:

Możesz nadal wysyłać żądania do tej samej sesji. Jeśli nie ma żadnych żądań do sesji przez dłuższy niż okres ochładzania, sesja zostanie automatycznie usunięta.

Przykładowe żądanie

The following example shows a request to a custom container session by a user ID.

Przed wysłaniem żądania zastąp symbole zastępcze między <> nawiasami wartościami specyficznymi dla żądania.

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

This request is forwarded to the custom container session with the identifier for the user's ID. Jeśli sesja nie jest jeszcze uruchomiona, usługa Azure Container Apps przydziela sesję z puli przed przekazaniem żądania.

W tym przykładzie kontener sesji odbiera żądanie pod adresem http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Korzystanie z tożsamości zarządzanej

A managed identity from Microsoft Entra ID allows your custom container session pools and their sessions to access other Microsoft Entra protected resources. Aby uzyskać więcej informacji na temat tożsamości zarządzanych w usłudze Microsoft Entra ID, zobacz Tożsamości zarządzane dla zasobów platformy Azure.

You can enable managed identities for your custom container session pools. Obsługiwane są tożsamości zarządzane przypisane przez system i przypisane przez użytkownika.

There are two ways to use managed identities with custom container session pools:

• Image pull authentication: Use the managed identity to authenticate with the container registry to pull the container image.

• Resource access: Use the session pool's managed identity in a session to access other Microsoft Entra protected resources. Ze względu na jego implikacje dotyczące zabezpieczeń ta funkcja jest domyślnie wyłączona.

  Ważne

  If you enable access to managed identity in a session, any code or programs running in the session can create Entra tokens for the pool's managed identity. Ponieważ sesje zwykle uruchamiają niezaufany kod, należy używać tej funkcji z ostrożnością.

Azure CLI

Aby włączyć tożsamość zarządzaną dla niestandardowej puli sesji kontenerów, użyj usługi Azure Resource Manager.

Azure Resource Manager

To enable managed identity for a custom container session pool, add an identity property to the session pool resource. Właściwość identity musi mieć właściwość type, której wartość to SystemAssigned lub UserAssigned. Aby uzyskać szczegółowe informacje na temat konfigurowania tej właściwości, zobacz Konfigurowanie tożsamości zarządzanych.

The following example shows an ARM template snippet that enables a user-assigned identity for a custom container session pool and use it for image pull authentication. Before you send the request, replace the placeholders between the <> brackets with the appropriate values for your session pool and session identifier.

{
  "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>": {}
    }
  }
}

Ten szablon zawiera następujące dodatkowe ustawienia tożsamości zarządzanej:

Parameter	Wartość	Opis
customContainerTemplate.registryCredentials.identity	<IDENTITY_RESOURCE_ID>	The resource ID of the managed identity to use for image pull authentication.
managedIdentitySettings.identity	<IDENTITY_RESOURCE_ID>	The resource ID of the managed identity to use in the session.
managedIdentitySettings.lifecycle	None	The session lifecycle where the managed identity is available. - None (ustawienie domyślne): sesja nie może uzyskać dostępu do tożsamości. Jest on używany tylko do ściągania obrazu. - Main: In addition to image pull, the main session can also access the identity. Należy zachować ostrożność.

Logging

Console logs from custom container sessions are available in the Azure Log Analytics workspace associated with the Azure Container Apps environment in a table named AppEnvSessionConsoleLogs_CL.

Rozliczenia

Custom container sessions are billed based on the resources consumed by the session pool. Aby uzyskać więcej informacji, zobacz Rozliczenia usługi Azure Container Apps.

Następne kroki

Omówienie sesji dynamicznych usługi Azure Container Apps