You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This article shows you how to manage and interact with dynamic sessions.
18
18
19
-
## Session access
19
+
## Management endpoint and routing
20
20
21
-
Your application interacts with a session using the session pool's management API.
21
+
Your application interacts with a session using the session pool's management API. For a conceptual overview of how requests are routed, see [Key concepts](./sessions.md#key-concepts).
For more information managing session pools, see [session pools management endpoint](./session-pool.md#management-endpoint)
30
-
31
-
## Forwarding requests to a session's container
29
+
For more information managing session pools, see [session pools management endpoint](./session-pool.md#management-endpoint).
32
30
33
31
To send a request into a session's container, you use the management endpoint as the root for your request. Anything in the path following the base pool management endpoint is forwarded to the session's container.
34
32
35
33
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`.
36
34
37
35
## Continuous interaction
38
36
39
-
As you continue to make calls to the same session, the session remains [allocated](sessions.md#session-lifecycle) in the pool. Once there are no requests to the session after the cooldown period has elapsed, the session is automatically destroyed.
37
+
As you continue to make calls to the same session, the session remains [allocated](sessions.md#key-concepts) in the pool. Once there are no requests to the session after the cooldown period has elapsed, the session is automatically destroyed.
40
38
41
39
## Sample request
42
40
@@ -54,7 +52,7 @@ Authorization: Bearer <TOKEN>
54
52
55
53
This request is forwarded to the container in the session with the identifier for the user's ID.
56
54
57
-
If the session isn't already running, Azure Container Apps automatically allocates a session from the pool before forwarding the request.
55
+
If no session exists for the given identifier, Azure Container Apps automatically allocates one from the pool before forwarding the request.
58
56
59
57
In this example, the session's container receives the request at `http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>`.
60
58
@@ -78,31 +76,26 @@ The identifier must be a string that is 4 to 128 characters long and can contain
78
76
79
77
## Security
80
78
79
+
### Security model
80
+
81
81
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.
82
82
83
83
Only configure or upload sensitive data to a session if you trust the users of the session.
84
84
85
+
### Network access
86
+
85
87
By default, sessions are prevented from making outbound network requests. You can control network access by configuring network status settings on the session pool.
86
88
87
-
-**Use strong, unique session identifiers**: Always generate session identifiers that are long and complex to prevent brute-force attacks. Use cryptographic algorithms to create identifiers that are hard to guess.
89
+
### Best practices
88
90
91
+
-**Secure identifiers**: Use secure [session identifiers](sessions-usage.md#identifiers) at all times. Generate session identifiers using cryptographic methods to ensure unique and unpredictable values. Avoid using sequential IDs that could be guessed by an attacker.
92
+
-**Use HTTPS**: Always use HTTPS to encrypt data in transit. This protects session identifiers and any sensitive data exchanged between the client and server from being intercepted.
93
+
-**Limit session lifetime**: Implement timeouts for sessions. For instance, allow a maximum of 15 minutes of inactivity before the session is automatically terminated. This helps mitigate risks due to a lost or unattended device.
89
94
-**Limit session visibility**: Set strict access controls to ensure that session identifiers are only visible to the session pool. Avoid exposing session IDs in URLs or logs.
90
-
91
-
-**Implement short expiration times**: Configure session identifiers to expire after a short period of inactivity. This approach minimizes the risk of sessions being hijacked after a user has finished interacting with your application.
92
-
93
95
-**Regularly rotate session credentials**: Periodically review and update the credentials associated with your sessions. Rotation decreases the risk of unauthorized access.
94
-
95
-
-**Utilize secure transmission protocols**: Always use HTTPS to encrypt data in transit, including session identifiers. This approach protects against man-in-the-middle attacks.
96
-
97
96
-**Monitor session activity**: Implement logging and monitoring to track session activities. Use these logs to identify unusual patterns or potential security breaches.
98
-
99
97
-**Validate user input**: Treat all user input as dangerous. Use input validation and sanitation techniques to protect against injection attacks and ensure that only trusted data is processed.
100
98
101
-
To fully secure your sessions, you can:
102
-
103
-
-[Use Microsoft Entra ID authentication and authorization](#authentication)
### <aname="authentication"></a>Authentication and authorization
107
100
108
101
When you send requests to a session using the pool management API, authentication is handled using Microsoft Entra 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.
Azure Container Apps dynamic sessions provide fast access to secure sandboxed environments that are ideal for running code or applications that require strong isolation from other workloads.
16
16
17
-
Sessions operate within the context of a [session pool](session-pool.md)which mitigates cold start to ensure immediate availability of a session.
17
+
Dynamic sessions offer prewarmed environments through a [session pools](./session-pool.md)that starts the container in milliseconds, scales on demand, and maintains strong isolation. This makes them ideal for interactive workloads, running LLM generated scripts, and secure execution of custom code.
18
18
19
-
With sessions, you get:
20
-
21
-
***Strong isolation**: Sessions are isolated from each other and from the host environment. Each session runs in its own Hyper-V sandbox, providing enterprise-grade security and isolation. Optionally, you can enable network isolation to further enhance security.
22
-
23
-
***Simple access**: Sessions are accessed through a REST API. A unique identifier marks each session. If a session with a given identifier doesn't exist, a new session is automatically allocated.
24
-
25
-
***Fully managed**: Container Apps fully manages a session's lifecycle. Sessions are automatically cleaned up when no longer in use.
26
-
27
-
***Fast startup**: New sessions are allocated in milliseconds. Rapid start-ups are achieved by automatically maintaining a pool of ready but unallocated sessions.
28
-
29
-
***Scalable**: Sessions can run at a high scale. You can run hundreds or thousands of sessions concurrently.
30
-
31
-
***API access**: Sessions are exposed to your application via a single HTTP endpoint.
32
-
33
-
## Session
34
-
35
-
A session is a sandboxed environment that runs untrusted code or your application.
36
19
37
-
Each session is isolated from all other sessions and from the host environment with a [Hyper-V](/windows-server/virtualization/hyper-v/hyper-v-technology-overview) sandbox. Hyper-V technology is at the foundation for session isolation, ensuring that different sessions operate independently with the necessary security boundaries in place. For enhanced network security, you can enable session network isolation on your session.
38
-
39
-
There are two different types of sessions.
40
-
41
-
## Session types
42
-
43
-
Azure Container Apps supports two types of sessions:
20
+
## Benefits
21
+
With sessions, you get:
44
22
45
-
| Type | Description | Billing model |
46
-
|------|-------------|---------------|
47
-
|[Code interpreter sessions](./sessions-code-interpreter.md)| Fully managed code interpreter which allows you to run code in a sandbox preinstalled with popular libraries.<br><br>Ideal for running untrusted code, such as code provided by users of your application or code generated by a large language model (LLM).<br><br>You can use the session out-of-the-box or with a [language model framework](./sessions-code-interpreter.md#llm-framework-integrations). | Per session (consumption) |
48
-
|[Custom container sessions](./sessions-custom-container.md)| Bring-your-own-container option where you run your own container images in secure, isolated sandboxes.<br><br>This approach is a good option if you want to run a custom code interpreter for a language that isn't supported out of the box, or workloads that require strong isolation. | Container Apps Dedicated Plan |
23
+
-**Secure isolation**: Hyper-V isolation and optional network controls protect your environment. Sessions are isolated from each other and from the host environment, providing enterprise-grade security and isolation.
24
+
-**Sandboxed environments**: Each session runs in its own isolated environment, ensuring that workloads don't interfere with each other.
25
+
-**Instant Startup**: Prewarmed pools enable subsecond launch times for interactive workloads. New sessions are allocated in milliseconds thanks to pools of ready but unallocated sessions.
26
+
-**Scalable by Design**: Handle hundreds or thousands of concurrent sessions without manual intervention.
27
+
-**Managed lifecycle**: Sessions are automatically deprovisioned after use or after a configurable cooldown period, ensuring efficient resource usage.
49
28
50
-
Each session, regardless of type, runs in the context of a session pool.
51
29
52
-
## Session pools
30
+
## Common Scenarios
31
+
Dynamic sessions are useful in a variety of situations, including:
32
+
-**AI/LLM Workflows**: Safely execute AI-generated code in isolated environments without risking your production systems.
33
+
-**Interactive Development**: Provide developers with fast, disposable environments for testing scripts or prototypes without provisioning full apps.
34
+
-**Secure Code Execution**: Run untrusted or user-submitted code in a sandboxed environment with strong isolation.
35
+
-**Custom Compute Tasks**: Execute short-lived jobs that require custom dependencies or runtime environments without long startup times.
36
+
-**Burst Workloads**: Handle unpredictable spikes in demand by scaling sessions up and down automatically.
53
37
54
-
To provide subsecond session allocation times, Azure Container Apps maintains a pool of ready but unallocated sessions. When your application makes a request for a session that hasn't been used before, the pool automatically assigns a new session for you. As sessions are allocated, the pool is automatically replenished to maintain a constant number of ready sessions.
55
38
56
-
Each session pool is available to your app through a [unique pool management endpoint location](sessions-usage.md).
39
+
## Key Concepts
40
+
-**Session Pool**: A session pool is the foundation for dynamic sessions. It contains a set of prewarmed, ready-to-use sessions that enable near instant startup. When a request comes in, the system allocates a session from the pool instead of creating one from scratch, which dramatically reduces latency.
57
41
58
-
## Session lifecycle
42
+
-**Session**: A session is the actual execution environment where your code or container runs. Sessions are ephemeral and isolated, designed for short-lived tasks. When you create a session, it's allocated from the session pool, ensuring fast startup. After the task completes or the cooldown period expires, the session is destroyed and resources are cleaned up.
59
43
60
-
The Container Apps runtime automatically manages the lifecycle for each session in a pool. A session's life begins as the session starts and continues while the session is in use. After there are no requests to the session after the cool down time has elapsed, the session is destroyed.
44
+
-**Session lifecycle**: When your application sends a request with a session identifier, the session pool allocates a session automatically. The session stays active as long as requests continue. Once the cooldown period expires with no activity, the session is destroyed and its resources are cleaned up automatically.
61
45
62
-
The following states define this lifecycle:
46
+
-**Request routing and identifiers**: Sessions are accessed through the session pool management endpoint. Requests include an `identifier` query parameter, and the pool routes the request to an existing session or allocates a new one if needed. The request path after the management endpoint is forwarded to the session container.
63
47
64
-
1.**Pending**: When a session is starting up, it's in the pending state. The amount of time a session spends in this state depends on the container image and settings specified for the session pool. A session in this state isn't added to the pool of ready sessions.
48
+
-**Session pool types**
49
+
-**Code interpreter session pools**: These use platform built-in containers that provide preconfigured environments for running code, including AI-generated scripts. Ideal for scenarios like LLM-driven workflows or secure code execution.
50
+
-**Custom container session pools**: Bring-your-own-container for custom workloads that require specific dependencies or runtime environments.
65
51
66
-
1.**Unallocated**: Once a session is done starting up, it's added to the pool and becomes available for allocation. For custom container sessions, you can specify how many ready sessions to maintain in the pool. This number should be increased if sessions are allocated faster than they're replenished.
67
52
68
-
1.**Allocated**: When you send a request to a nonrunning session, the pool provides a new session and places it in an allocated state. Subsequent requests with the same session identifier are routed to the same session, allowing for efficient reuse without cold starts. Each allocated session is associated with a [session identifier](./sessions-usage.md#identifiers).
53
+
#### Session pool types comparison
69
54
70
-
1.**Destroyed**: If a session doesn't receive requests for a duration defined by the `cooldownPeriodInSeconds` setting, the session and its Hyper-V sandbox are securely deleted. This automatic cleanup setup enhances resource management and security.
|**Best for**| Running AI‑generated code, user-submitted scripts, or quick secure code execution without managing a runtime environment. | Workloads requiring a custom runtime, libraries, binaries, or specialized tools not supported by built-in interpreters. |
58
+
|**Environment**| Preconfigured with common runtimes and tools; no container build or image publishing required. | Fully customizable container image with your own dependencies, packages, and configuration. |
59
+
|**When to choose**| Choose this for simplicity, fastest startup, and minimal setup. | Choose this when you need full control over the execution environment or rely on custom dependencies. |
60
+
|**Ideal use cases**| LLM workflows, code interpretation, educational/sandbox scenarios, safe execution of user code. | Custom compute tasks, proprietary interpreters, specialized environments, or workloads with specific OS/library requirements. |
61
+
|**Language and protocol**| Limited to the built-in runtimes and the REST API surface provided by the code interpreter. | Any language or stack supported by your container, with any TCP protocol you choose to expose. |
62
+
|**Image requirement**| None—uses platform built‑in interpreter environments. | Required—supply your own container image URI. |
71
63
72
-
The Container Apps runtime automatically manages the lifecycle for each session in a session pool.
64
+
For more information, see [Usage](./sessions-usage.md).
73
65
74
-
## Region availability
75
66
76
-
Dynamic sessions are available in the following regions:
67
+
## Supported regions
77
68
78
-
| Region | Code interpreter | Custom container |
79
-
|--------|------------------|------------------|
80
-
| Australia East | ✔ | ✔ |
81
-
| Australia Southeast | ✔ | ✔ |
82
-
| Brazil South | ✔ | ✔ |
83
-
| Canada Central | ✔ | ✔ |
84
-
| Canada East | ✔ | ✔ |
85
-
| Central India | ✔ | ✔ |
86
-
| Central US | ✔ | ✔ |
87
-
| East Asia | ✔ | ✔ |
88
-
| East US | ✔ | ✔ |
89
-
| East US 2 | ✔ | ✔ |
90
-
| France Central | ✔ | ✔ |
91
-
| Germany West Central | ✔ | ✔ |
92
-
| Italy North | ✔ | ✔ |
93
-
| Japan East | ✔ | ✔ |
94
-
| Japan West | ✔ | ✔ |
95
-
| Korea Central | ✔ | ✔ |
96
-
| North Central US | ✔ | ✔ |
97
-
| North Europe | ✔ | ✔ |
98
-
| Norway East | ✔ | ✔ |
99
-
| Poland Central | ✔ | ✔ |
100
-
| South Africa North | ✔ | ✔ |
101
-
| South India | ✔ | ✔ |
102
-
| Southeast Asia | ✔ | ✔ |
103
-
| Sweden Central | ✔ | ✔ |
104
-
| Switzerland North | ✔ | ✔ |
105
-
| Switzerland West | ✔ | ✔ |
106
-
| UAE North | ✔ | ✔ |
107
-
| UK South | ✔ | ✔ |
108
-
| UK West | ✔ | ✔ |
109
-
| West Central US | ✔ | ✔ |
110
-
| West Europe | ✔ | ✔ |
111
-
| West US | ✔ | ✔ |
112
-
| West US 2 | ✔ | ✔ |
113
-
| West US 3 | ✔ | ✔ |
69
+
Dynamic sessions are available in the following regions. Both code interpreter and custom container sessions are supported in all listed regions.
114
70
115
-
## Billing
71
+
| Americas | Europe | Asia Pacific | Middle East & Africa |
| Brazil South | France Central | Australia East | South Africa North |
74
+
| Canada Central | Germany West Central | Australia Southeast | UAE North |
75
+
| Canada East | Italy North | Central India ||
76
+
| Central US | North Europe | East Asia ||
77
+
| East US | Norway East | Japan East ||
78
+
| East US 2 | Poland Central | Japan West ||
79
+
| North Central US | Sweden Central | Korea Central ||
80
+
| West Central US | Switzerland North | South India ||
81
+
| West US | Switzerland West | Southeast Asia ||
82
+
| West US 2 | UK South |||
83
+
| West US 3 | UK West |||
84
+
|| West Europe |||
116
85
117
-
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).
86
+
> [!NOTE]
87
+
> Regional availability may change. To verify current availability, check the **Location** dropdown when creating a session pool in the Azure portal.
118
88
119
89
## Security
90
+
Dynamic sessions are designed to run untrusted code in isolated environments. For information about securing your sessions, see [Security](./sessions-usage.md#security).
120
91
121
-
Use the following methods to help harden the security of your dynamic sessions.
122
-
123
-
***Secure identifiers**: Use secure [session identifiers](sessions-usage.md#identifiers) at all times. Generate session identifiers using cryptographic methods to ensure unique and unpredictable values. Avoid using sequential IDs that could be guessed by an attacker.
124
92
125
-
***Use HTTPS**: Always use HTTPS to encrypt data in transit. This protects session identifiers and any sensitive data exchanged between the client and server from being intercepted.
126
-
127
-
***Limit session lifetime**: Implement timeouts for sessions. For instance, allow a maximum of 15 minutes of inactivity before the session is automatically terminated. This helps mitigate risks due to a lost or unattended device.
93
+
## Billing
94
+
Custom container sessions are billed based on the resources consumed by the session pool. For more information, see [Azure Container Apps billing](./billing.md#dynamic-sessions).
128
95
129
-
***Regular audits and monitoring**: Periodically review session management practices and logs. Implement monitoring tools to alert suspicious activities, such as repeated failed login attempts or abnormal session lengths.
130
96
131
-
## Related content
97
+
## Next steps
98
+
- Learn how to configure [session pools](./session-pool.md)
99
+
- Learn how to use [dynamic sessions](./sessions-usage.md), including security and best practices
0 commit comments