Add details about how container networks are managed

docs/architecture/overview.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire architecture overview  
 description: Learn about the overall architecture of .NET Aspire, including its integrations, orchestration, and networking capabilities.  
-ms.date: 05/09/2025
+ms.date: 07/11/2025
 ---
 
 # .NET Aspire architecture overview  
@@ -165,7 +165,9 @@
 
 :::image type="content" source="media/dcp-architecture-thumb.png" alt-text="A diagram depicting the architecture of the Developer Control Plane (DCP)." lightbox="media/dcp-architecture.png":::
 
-DCP logs are streamed back to the app host, which then forwards them to the developer dashboard. While the developer dashboard exposes commands such as start, stop, and restart, these commands are not part of DCP itself. Instead, they are implemented by the app model runtime, specifically within its "dashboard service" component. These commands operate by manipulating DCP objects—creating new ones, deleting old ones, or updating their properties. For example, restarting a .NET project involves stopping and deleting the existing <xref:Aspire.Hosting.ApplicationModel.ExecutableResource> representing the project and creating a new one with the same specifications. For more information on commands, see [Custom resource commands in .NET Aspire](../fundamentals/custom-resource-commands.md).
+DCP logs are streamed back to the app host, which then forwards them to the developer dashboard. While the developer dashboard exposes commands such as start, stop, and restart, these commands are not part of DCP itself. Instead, they are implemented by the app model runtime, specifically within its "dashboard service" component. These commands operate by manipulating DCP objects—creating new ones, deleting old ones, or updating their properties. For example, restarting a .NET project involves stopping and deleting the existing <xref:Aspire.Hosting.ApplicationModel.ExecutableResource> representing the project and creating a new one with the same specifications. 
+
+For more information on container networking, see [How container networks are managed](../fundamentals/networking-overview.md#how-container-networks-are-managed).
 
 ## Developer dashboard
 

docs/fundamentals/networking-overview.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire inner loop networking overview
 description: Learn how .NET Aspire handles networking and endpoints, and how you can use them in your app code.
-ms.date: 10/29/2024
+ms.date: 07/11/2025
 ms.topic: overview
 ---
 
@@ -30,6 +30,29 @@ To help visualize how endpoints work, consider the .NET Aspire starter templates
 
 :::image type="content" source="media/networking/networking-proxies-1x.png" lightbox="media/networking/networking-proxies.png" alt-text=".NET Aspire Starter Application template inner loop networking diagram.":::
 
+## How container networks are managed
+
+When you add one or more container resource(s), .NET Aspire creates a dedicated container bridge network to enable service discovery between containers. This bridge network is a virtual network that lets containers communicate with each other and provides a DNS server for container-to-container service discovery using DNS names.
+
+The network's lifetime depends on the container resources:
+
+- If all containers have a session lifetime, the network is also session-based and is cleaned up when the app host process ends.
+- If any container has a persistent lifetime, the network is persistent and remains running after the app host process terminates. Aspire reuses this network on subsequent runs, allowing persistent containers to keep communicating even when the app host isn't running.
+
+For more information on container lifetimes, see [Container resource lifetime](orchestrate-resources.md#container-resource-lifetime).
+
+Here are the naming conventions for container networks:
+
+- **Session networks**: `aspire-session-network-<unique-id>-<app-host-name>`
+- **Persistent networks**: `aspire-persistent-network-<project-hash>-<app-host-name>`
+
+Each app host instance gets its own network resources. The only differences are the network's lifetime and name; service discovery works the same way for both.
+
+Containers register themselves on the network using their resource name. Aspire uses this name for service discovery between containers. For example, a `pgadmin` container can connect to a database resource named `postgres` using `postgres:5432`.
+
+> [!NOTE]
+> Host services, such as projects or other executables, don't use container networks. They rely on exposed container ports for service discovery and communication with containers. For more details on service discovery, see [service discovery overview](../service-discovery/overview.md).
+
 ## Launch profiles
 
 When you call <xref:Aspire.Hosting.ProjectResourceBuilderExtensions.AddProject%2A>, the app host looks for _Properties/launchSettings.json_ to determine the default set of endpoints. The app host selects a specific launch profile using the following rules: