Azure Container Apps custom container sessions (preview)

In addition to the built-in code interpreter that Azure Container Apps dynamic sessions provide, you can also use custom containers to define your own session sandboxes.

Uses for custom container sessions

Custom containers allow you to build solutions tailored to your needs. They enable you to execute code or run applications in environments that are fast and ephemeral and offer secure, sandboxed spaces with Hyper-V. Additionally, they can be configured with optional network isolation. Some examples include:

• Code interpreters: When you need to execute untrusted code in secure sandboxes by a language not supported in the built-in interpreter, or you need full control over the code interpreter environment.

• Isolated execution: When you need to run applications in hostile, multitenant scenarios where each tenant or user has their own sandboxed environment. These environments are isolated from each other and from the host application. Some examples include applications that run user-provided code, code that grants end user access to a cloud-based shell, AI agents, and development environments.

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. The session remains active until it enters an idle state, which is then automatically stopped and destroyed.

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. The custom container must expose an HTTP server on a port that you specify to respond to these requests.

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

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 1.0 --memory 2.0Gi \
    --target-port 80 \
    --cooldown-period 300 \
    --network-status EgressDisabled \
    --max-sessions 10 \
    --ready-sessions 5 \
    --env-vars "key1=value1" "key2=value2"

{
  "type": "Microsoft.ContainerApps/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>",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 300
    },
    "customContainerTemplate": {
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "resources": {
            "cpu": 1.0,
            "memory": "2.0Gi"
          },
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ],
          "command": ["/bin/sh"],
          "args": ["-c", "while true; do echo hello; sleep 10; done"]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressDisabled"
    }
  }
}

Working with sessions

Your application interacts with a session using the session pool's management API.

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. To learn how to authenticate with the pool management API, see Authentication.

Each API request must also include the query string parameter identifier with the session ID. This unique session ID enables your application to interact with specific sessions. To learn more about session identifiers, see Session identifiers.

Forwarding requests to the session's container:

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

For example, if you make a call to <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, the request is routed to the session's container at 0.0.0.0:<TARGET_PORT>/api/uploadfile.

Continuous session interaction:

You can continue making requests to the same session. If there are no requests to the session for longer than the cooldown period, the session is automatically deleted.

Sample request

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

Before you send the request, replace the placeholders between the <> brackets with values specific to your request.

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. If the session isn't already running, Azure Container Apps allocates a session from the pool before forwarding the request.

In the example, the session's container receives the request at http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Next steps