Merge pull request #289845 from anthonychu/20241104-sessions-update

[Container Apps] General updates to sessions docs

Author: Jill Grant

articles/container-apps/media/sessions/sessions-overview.png

@@ -257,6 +257,14 @@ Authorization: Bearer <TOKEN>
 }
 ```
 
+## Logging
+
+Code interpreter sessions don't support logging directly. Your application that's interacting with the sessions can log requests to the session pool management API and its responses.
+
+## Billing
+
+Code interpreter sessions are billed based on the duration of each session. See [Billing](billing.md#dynamic-sessions) for more information.
+
 ## Next steps
 
 > [!div class="nextstepaction"]

articles/container-apps/sessions-code-interpreter.md

@@ -63,7 +63,7 @@ az containerapp sessionpool create \
     --registry-username <USER_NAME> \
     --registry-password <PASSWORD> \
     --container-type CustomContainer \
-    --image myregistry.azurecr.io/my-container-image:1.0 \ 
+    --image myregistry.azurecr.io/my-container-image:1.0 \
     --cpu 0.25 --memory 0.5Gi \
     --target-port 80 \
     --cooldown-period 300 \
@@ -96,6 +96,16 @@ This command creates a session pool with the following settings:
 | `--env-vars` | `"key1=value1" "key2=value2"` | The environment variables to set in the container. |
 | `--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:
+
+```bash
+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](#tab/arm)
@@ -107,7 +117,7 @@ Before you send the request, replace the placeholders between the `<>` brackets
 ```json
 {
   "type": "Microsoft.App/sessionPools",
-  "apiVersion": "2024-02-02-preview",
+  "apiVersion": "2024-08-02-preview",
   "name": "my-session-pool",
   "location": "westus2",
   "properties": {
@@ -122,7 +132,18 @@ Before you send the request, replace the placeholders between the `<>` brackets
       "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",
@@ -174,6 +195,10 @@ This template creates a session pool with the following settings:
 | `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` | The number of seconds that a session can be idle before the session is terminated. The idle period is reset each time the session's API is called. Value must be between `300` and `3600`. |
+| `secrets` | `[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]` | A list of secrets. |
+| `customContainerTemplate.registryCredentials.server` | `myregistry.azurecr.io` | The container registry server hostname. |
+| `customContainerTemplate.registryCredentials.username` | `myregistry` | The username to log in to the container registry. |
+| `customContainerTemplate.registryCredentials.passwordSecretRef` | `registrypassword` | The name of the secret that contains the password to log in to the container registry. |
 | `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` | The name of the container. |
 | `customContainerTemplate.containers[0].resources.cpu` | `0.25` | The required CPU in cores. |
@@ -189,13 +214,20 @@ This template creates a session pool with the following settings:
 > [!IMPORTANT]
 > If the session is used to run untrusted code, don't include information or data that you don't want the untrusted code to access. Assume the code is malicious and has full access to the container, including its environment variables, secrets, and files. 
 
+#### 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.
+
+Any changes to the image aren't automatically reflected in the sessions. To update the image, update the session pool with a new image tag. Use a unique tag for each image update to ensure that the new image is pulled.
+
 ### 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:
+
 ```bash
 az containerapp sessionpool show \
     --name <SESSION_POOL_NAME> \
@@ -240,6 +272,118 @@ This request is forwarded to the custom container session with the identifier fo
 
 In the example, the session's container receives the request at `http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>`.
 
+### Using managed identity
+
+A managed identity from Microsoft Entra ID allows your custom container session pools and their sessions to access other Microsoft Entra protected resources. For more about managed identities in Microsoft Entra ID, see [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md).
+
+You can enable managed identities for your custom container session pools. Both system-assigned and user-assigned managed identities are supported.
+
+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. Due to its security implications, this capability is disabled by default.
+
+    > [!IMPORTANT]
+    > 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. Since sessions typically run untrusted code, use this feature with caution.
+
+# [Azure CLI](#tab/azure-cli)
+
+To enable managed identity for a custom container session pool, use Azure Resource Manager.
+
+# [Azure Resource Manager](#tab/arm)
+
+To enable managed identity for a custom container session pool, add an `identity` property to the session pool resource. The `identity` property must have a `type` property with the value `SystemAssigned` or `UserAssigned`. For details on how to configure this property, see [Configure managed identities](managed-identity.md?tabs=arm%2Cdotnet#configure-managed-identities).
+
+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.
+
+```json
+{
+  "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>": {}
+    }
+  }
+}
+```
+
+This template contains the following additional settings for managed identity:
+
+| Parameter | Value | Description |
+|---------|-------|-------------|
+| `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.<br><br>- `None` (default): The session can't access the identity. It's only used for image pull.<br><br>- `Main`: In addition to image pull, the main session can also access the identity. **Use with caution.** |
+
+---
+
+## 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`.
+
 ## Billing
 
 Custom container sessions are billed based on the resources consumed by the session pool. For more information, see [Azure Container Apps billing](billing.md#custom-container).

articles/container-apps/sessions-custom-container.md

@@ -5,7 +5,7 @@ services: container-apps
 author: craigshoemaker
 ms.service: azure-container-apps
 ms.topic: conceptual
-ms.date: 04/04/2024
+ms.date: 11/04/2024
 ms.author: cshoe
 ms.custom: references_regions
 ---
@@ -60,24 +60,30 @@ You can configure pools to set the maximum number of sessions that can be alloca
 
 A session is a sandboxed environment that runs your code or application. Each session is isolated from other sessions and from the host environment with a [Hyper-V](/windows-server/virtualization/hyper-v/hyper-v-technology-overview) sandbox. Optionally, you can enable network isolation to further enhance security.
 
-#### Session identifiers
+You interact with sessions in a session pool by sending HTTP requests. Each session pool has a unique pool management endpoint.
 
-When you interact with sessions in a pool, you must define a session identifier to manage each session. The session identifier is a free-form string, meaning you can define it in any way that suits your application's needs. This identifier is a key element in determining the behavior of the session:
+For code interpreter sessions, you can also use an integration with an [LLM framework](./sessions-code-interpreter.md#llm-framework-integrations).
 
-- Reuse of existing sessions: This session is reused if there's already a running session that matches the identifier.
-- Allocation of new sessions: If no running session matches the identifier, a new session is automatically allocated from the pool.
+### Session identifiers
 
-The session identifier is a string that you define that is unique within the session pool. If you're building a web application, you can use the user's ID. If you're building a chatbot, you can use the conversation ID.
+To send an HTTP request to a session, you must provide a session identifier in the request. You pass the session identifier in a query parameter named `identifier` in the URL when you make a request to a session.
 
-The identifier must be a string that is 4 to 128 characters long and can contain only alphanumeric characters and special characters from this list: `|`, `-`, `&`, `^`, `%`, `$`, `#`, `(`, `)`, `{`, `}`, `[`, `]`, `;`, `<`, and `>`.
+* If a session with the identifier already exists, the request is sent to the existing session.
+* If a session with the identifier doesn't exist, a new session is automatically allocated before the request is sent to it.
+
+:::image type="content" source="media/sessions/sessions-overview.png" alt-text="Screenshot of session pool and sessions usage.":::
+
+#### Identifier format
 
-You pass the session identifier in a query parameter named `identifier` in the URL when you make a request to a session.
+The session identifier is a free-form string, meaning you can define it in any way that suits your application's needs.
 
-For code interpreter sessions, you can also use an integration with an [LLM framework](./sessions-code-interpreter.md#llm-framework-integrations). The framework handles the token generation and management for you. Ensure that the application is configured with a managed identity that has the necessary role assignments on the session pool.
+The session identifier is a string that you define that is unique within the session pool. If you're building a web application, you can use the user's ID as the session identifier. If you're building a chatbot, you can use the conversation ID.
 
-##### Protecting session identifiers
+The identifier must be a string that is 4 to 128 characters long and can contain only alphanumeric characters and special characters from this list: `|`, `-`, `&`, `^`, `%`, `$`, `#`, `(`, `)`, `{`, `}`, `[`, `]`, `;`, `<`, and `>`.
+
+#### Protecting session identifiers
 
-The session identifier is sensitive information which requires a secure process as you create and manage its value. To protect this value, your application must ensure each user or tenant only has access to their own sessions.
+The session identifier is sensitive information which you must manage securely. Your application needs to ensure each user or tenant only has access to their own sessions.
 
 The specific strategies that prevent misuse of session identifiers differ depending on the design and architecture of your app. However, your app must always have complete control over the creation and use of session identifiers so that a malicious user can't access another user's session.
 
@@ -89,22 +95,17 @@ Example strategies include:
 > [!IMPORTANT]
 > Failure to secure access to sessions may result in misuse or unauthorized access to data stored in your users' sessions.
 
-### Authentication
+### <a name="authentication"></a>Authentication and authorization
 
-Authentication is handled using Microsoft Entra (formerly Azure Active Directory) tokens. Valid Microsoft Entra tokens are generated by an identity belonging to the *Azure ContainerApps Session Executor* and *Contributor* roles on the session pool.
+When you send requests to a session using the pool management API, authentication is handled using Microsoft Entra (formerly Azure Active Directory) tokens. Only Microsoft Entra tokens from an identity belonging to the *Azure ContainerApps Session Executor* role on the session pool are authorized to call the pool management API.
 
-To assign the roles to an identity, use the following Azure CLI commands:
+To assign the role to an identity, use the following Azure CLI command:
 
 ```bash
 az role assignment create \
     --role "Azure ContainerApps Session Executor" \
     --assignee <PRINCIPAL_ID> \
     --scope <SESSION_POOL_RESOURCE_ID>
-
-az role assignment create \
-    --role "Contributor" \
-    --assignee <PRINCIPAL_ID> \
-    --scope <SESSION_POOL_RESOURCE_ID>
 ```
 
 If you're using an [LLM framework integration](sessions-code-interpreter.md#llm-framework-integrations), the framework handles the token generation and management for you. Ensure that the application is configured with a managed identity with the necessary role assignments on the session pool.
@@ -177,7 +178,7 @@ access_token = token.token
 ---
 
 > [!IMPORTANT]
-> A valid token can be used to create and access any session in the pool. Keep your tokens secure and don't share them with untrusted parties. End users should access sessions through your application, not directly.
+> A valid token can be used to create and access any session in the pool. Keep your tokens secure and don't share them with untrusted parties. End users should access sessions through your application, not directly. They should never have access to the tokens used to authenticate requests to the session pool.
 
 #### Lifecycle
 
@@ -195,6 +196,10 @@ The Container Apps runtime automatically manages the lifecycle for each session
 
 Azure Container Apps dynamic sessions are built to run untrusted code and applications in a secure and isolated environment. While sessions are isolated from one another, anything within a single session, including files and environment variables, is accessible by users of the session. You should only configure or upload sensitive data to a session if you trust the users of the session.
 
+By default, sessions are prevented from making outbound network requests. You can control network access by configuring network status settings on the session pool.
+
+In addition, follow the guidance in the [authentication and authorization](#authentication) section to ensure that only authorized users can access sessions and in the [protecting session identifiers](#protecting-session-identifiers) section to ensure that session identifiers are secure.
+
 ## Preview limitations
 
 Azure Container Apps dynamic sessions is currently in preview. The following limitations apply:
@@ -211,8 +216,6 @@ Azure Container Apps dynamic sessions is currently in preview. The following lim
     | North Central US | ✔ | - |
     | North Europe | ✔ | ✔ |
     | West US 2 | ✔ | ✔ |
-    
-* Logging isn't supported. Your application can log requests to the session pool management API and its responses.
 
 ## Next steps