Add Network Security Group (NSG) support for Azure Virtual Networks (#14383)

## Description

Adds Network Security Group (NSG) support for Azure Virtual Networks, enabling fine-grained network traffic control for subnets. Includes both a **shorthand API** for the common case and an **explicit API** for full control.

### Shorthand API (recommended for most users)

Fluent methods on subnet builders that auto-create an NSG, auto-increment priority, and auto-generate rule names:

```csharp
var subnet = vnet.AddSubnet("web", "10.0.1.0/24")
    .AllowInbound(port: "443", from: "AzureLoadBalancer", protocol: SecurityRuleProtocol.Tcp)
    .DenyInbound(from: "VirtualNetwork")
    .DenyInbound(from: "Internet");
```

### Explicit API (for full control)

Create standalone NSG resources with explicit `AzureSecurityRule` objects:

```csharp
var nsg = builder.AddNetworkSecurityGroup("web-nsg")
    .WithSecurityRule(new AzureSecurityRule
    {
        Name = "allow-https",
        Priority = 100,
        Direction = SecurityRuleDirection.Inbound,
        Access = SecurityRuleAccess.Allow,
        Protocol = SecurityRuleProtocol.Tcp,
        DestinationPortRange = "443"
    });

var subnet = vnet.AddSubnet("web-subnet", "10.0.1.0/24")
    .WithNetworkSecurityGroup(nsg);
```

### New public APIs

**Types:**
- `AzureNetworkSecurityGroupResource` — standalone `AzureProvisioningResource` with its own bicep module, `Id` and `NameOutput` outputs, and `AddAsExistingResource` support
- `AzureSecurityRule` — data class for rule configuration. `SourcePortRange`, `SourceAddressPrefix`, and `DestinationAddressPrefix` default to `"*"` to reduce verbosity

**Extension methods on `IDistributedApplicationBuilder`:**
- `AddNetworkSecurityGroup(name)` — creates a top-level NSG resource

**Extension methods on `IResourceBuilder<AzureNetworkSecurityGroupResource>`:**
- `WithSecurityRule(rule)` — adds a security rule (rejects duplicate names)

**Extension methods on `IResourceBuilder<AzureSubnetResource>`:**
- `WithNetworkSecurityGroup(nsg)` — associates an explicit NSG with a subnet
- `AllowInbound(port, from, to, protocol, priority, name)` — shorthand allow inbound rule
- `DenyInbound(...)` — shorthand deny inbound rule
- `AllowOutbound(...)` — shorthand allow outbound rule
- `DenyOutbound(...)` — shorthand deny outbound rule

### Key design decisions

- **NSG is a standalone `AzureProvisioningResource`** — generates its own bicep module (not inline in the VNet module). Subnets reference the NSG via cross-module parameter (`param nsg_outputs_id string`)
- **NSG is a top-level resource** (not a child of VNet), matching Azure's actual resource model
- **Shorthand methods auto-create an implicit NSG** named `{subnet}-nsg` when no NSG is assigned. Calling `WithNetworkSecurityGroup` after shorthand methods throws `InvalidOperationException` to prevent silent rule loss
- **Priority auto-increments** by 100 (100, 200, 300...) from the max existing priority
- **Rule names auto-generate** from access/direction/port/source (e.g., `allow-inbound-443-AzureLoadBalancer`)
- **Sensible defaults on `AzureSecurityRule`** — `SourcePortRange`, `SourceAddressPrefix`, `DestinationAddressPrefix` all default to `"*"`, reducing the common 10-line rule to ~5 required properties
- **A single NSG can be shared across multiple subnets**
- **Duplicate rule names** within an NSG are rejected with `ArgumentException`

Author: eerhardt

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/Program.cs

@@ -1,20 +1,30 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+#pragma warning disable AZPROVISION001 // Azure.Provisioning.Network is experimental
+
+using Azure.Provisioning.Network;
+
 var builder = DistributedApplication.CreateBuilder(args);
 
 // Create a virtual network with two subnets:
 // - One for the Container App Environment (with service delegation)
 // - One for private endpoints
 var vnet = builder.AddAzureVirtualNetwork("vnet");
 
-var containerAppsSubnet = vnet.AddSubnet("container-apps", "10.0.0.0/23");
-var privateEndpointsSubnet = vnet.AddSubnet("private-endpoints", "10.0.2.0/27");
+var containerAppsSubnet = vnet.AddSubnet("container-apps", "10.0.0.0/23")
+    .AllowInbound(port: "443", from: "AzureLoadBalancer", protocol: SecurityRuleProtocol.Tcp)
+    .DenyInbound(from: "VirtualNetwork")
+    .DenyInbound(from: "Internet");
 
 // Create a NAT Gateway for deterministic outbound IP on the ACA subnet
 var natGateway = builder.AddNatGateway("nat");
 containerAppsSubnet.WithNatGateway(natGateway);
 
+var privateEndpointsSubnet = vnet.AddSubnet("private-endpoints", "10.0.2.0/27")
+    .AllowInbound(port: "443", from: "VirtualNetwork", protocol: SecurityRuleProtocol.Tcp)
+    .DenyInbound(from: "Internet");
+
 // Configure the Container App Environment to use the VNet
 builder.AddAzureContainerAppEnvironment("env")
     .WithDelegatedSubnet(containerAppsSubnet);

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/aspire-manifest.json

@@ -5,13 +5,23 @@
       "type": "azure.bicep.v0",
       "path": "vnet.module.bicep",
       "params": {
-        "nat_outputs_id": "{nat.outputs.id}"
+        "nat_outputs_id": "{nat.outputs.id}",
+        "container_apps_nsg_outputs_id": "{container-apps-nsg.outputs.id}",
+        "private_endpoints_nsg_outputs_id": "{private-endpoints-nsg.outputs.id}"
       }
     },
+    "container-apps-nsg": {
+      "type": "azure.bicep.v0",
+      "path": "container-apps-nsg.module.bicep"
+    },
     "nat": {
       "type": "azure.bicep.v0",
       "path": "nat.module.bicep"
     },
+    "private-endpoints-nsg": {
+      "type": "azure.bicep.v0",
+      "path": "private-endpoints-nsg.module.bicep"
+    },
     "env-acr": {
       "type": "azure.bicep.v0",
       "path": "env-acr.module.bicep"

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/container-apps-nsg.module.bicep

@@ -0,0 +1,59 @@
+@description('The location for the resource(s) to be deployed.')
+param location string = resourceGroup().location
+
+resource container_apps_nsg 'Microsoft.Network/networkSecurityGroups@2025-05-01' = {
+  name: take('container_apps_nsg-${uniqueString(resourceGroup().id)}', 80)
+  location: location
+  tags: {
+    'aspire-resource-name': 'container-apps-nsg'
+  }
+}
+
+resource container_apps_nsg_allow_inbound_443_AzureLoadBalancer 'Microsoft.Network/networkSecurityGroups/securityRules@2025-05-01' = {
+  name: 'allow-inbound-443-AzureLoadBalancer'
+  properties: {
+    access: 'Allow'
+    destinationAddressPrefix: '*'
+    destinationPortRange: '443'
+    direction: 'Inbound'
+    priority: 100
+    protocol: 'Tcp'
+    sourceAddressPrefix: 'AzureLoadBalancer'
+    sourcePortRange: '*'
+  }
+  parent: container_apps_nsg
+}
+
+resource container_apps_nsg_deny_inbound_VirtualNetwork 'Microsoft.Network/networkSecurityGroups/securityRules@2025-05-01' = {
+  name: 'deny-inbound-VirtualNetwork'
+  properties: {
+    access: 'Deny'
+    destinationAddressPrefix: '*'
+    destinationPortRange: '*'
+    direction: 'Inbound'
+    priority: 200
+    protocol: '*'
+    sourceAddressPrefix: 'VirtualNetwork'
+    sourcePortRange: '*'
+  }
+  parent: container_apps_nsg
+}
+
+resource container_apps_nsg_deny_inbound_Internet 'Microsoft.Network/networkSecurityGroups/securityRules@2025-05-01' = {
+  name: 'deny-inbound-Internet'
+  properties: {
+    access: 'Deny'
+    destinationAddressPrefix: '*'
+    destinationPortRange: '*'
+    direction: 'Inbound'
+    priority: 300
+    protocol: '*'
+    sourceAddressPrefix: 'Internet'
+    sourcePortRange: '*'
+  }
+  parent: container_apps_nsg
+}
+
+output id string = container_apps_nsg.id
+
+output name string = container_apps_nsg.name

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/private-endpoints-nsg.module.bicep

@@ -0,0 +1,44 @@
+@description('The location for the resource(s) to be deployed.')
+param location string = resourceGroup().location
+
+resource private_endpoints_nsg 'Microsoft.Network/networkSecurityGroups@2025-05-01' = {
+  name: take('private_endpoints_nsg-${uniqueString(resourceGroup().id)}', 80)
+  location: location
+  tags: {
+    'aspire-resource-name': 'private-endpoints-nsg'
+  }
+}
+
+resource private_endpoints_nsg_allow_inbound_443_VirtualNetwork 'Microsoft.Network/networkSecurityGroups/securityRules@2025-05-01' = {
+  name: 'allow-inbound-443-VirtualNetwork'
+  properties: {
+    access: 'Allow'
+    destinationAddressPrefix: '*'
+    destinationPortRange: '443'
+    direction: 'Inbound'
+    priority: 100
+    protocol: 'Tcp'
+    sourceAddressPrefix: 'VirtualNetwork'
+    sourcePortRange: '*'
+  }
+  parent: private_endpoints_nsg
+}
+
+resource private_endpoints_nsg_deny_inbound_Internet 'Microsoft.Network/networkSecurityGroups/securityRules@2025-05-01' = {
+  name: 'deny-inbound-Internet'
+  properties: {
+    access: 'Deny'
+    destinationAddressPrefix: '*'
+    destinationPortRange: '*'
+    direction: 'Inbound'
+    priority: 200
+    protocol: '*'
+    sourceAddressPrefix: 'Internet'
+    sourcePortRange: '*'
+  }
+  parent: private_endpoints_nsg
+}
+
+output id string = private_endpoints_nsg.id
+
+output name string = private_endpoints_nsg.name

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/vnet.module.bicep

@@ -3,6 +3,10 @@ param location string = resourceGroup().location
 
 param nat_outputs_id string
 
+param container_apps_nsg_outputs_id string
+
+param private_endpoints_nsg_outputs_id string
+
 resource vnet 'Microsoft.Network/virtualNetworks@2025-05-01' = {
   name: take('vnet-${uniqueString(resourceGroup().id)}', 64)
   properties: {
@@ -33,6 +37,9 @@ resource container_apps 'Microsoft.Network/virtualNetworks/subnets@2025-05-01' =
     natGateway: {
       id: nat_outputs_id
     }
+    networkSecurityGroup: {
+      id: container_apps_nsg_outputs_id
+    }
   }
   parent: vnet
 }
@@ -41,6 +48,9 @@ resource private_endpoints 'Microsoft.Network/virtualNetworks/subnets@2025-05-01
   name: 'private-endpoints'
   properties: {
     addressPrefix: '10.0.2.0/27'
+    networkSecurityGroup: {
+      id: private_endpoints_nsg_outputs_id
+    }
   }
   parent: vnet
   dependsOn: [

src/Aspire.Hosting.Azure.Network/AzureNetworkSecurityGroupExtensions.cs

@@ -0,0 +1,153 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Aspire.Hosting.ApplicationModel;
+using Aspire.Hosting.Azure;
+using Azure.Provisioning;
+using Azure.Provisioning.Network;
+
+namespace Aspire.Hosting;
+
+/// <summary>
+/// Provides extension methods for adding Azure Network Security Group resources to the application model.
+/// </summary>
+public static class AzureNetworkSecurityGroupExtensions
+{
+    /// <summary>
+    /// Adds an Azure Network Security Group to the application model.
+    /// </summary>
+    /// <param name="builder">The builder for the distributed application.</param>
+    /// <param name="name">The name of the Network Security Group resource.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{AzureNetworkSecurityGroupResource}"/>.</returns>
+    /// <example>
+    /// This example adds a Network Security Group with a security rule:
+    /// <code>
+    /// var nsg = builder.AddNetworkSecurityGroup("web-nsg")
+    ///     .WithSecurityRule(new AzureSecurityRule
+    ///     {
+    ///         Name = "allow-https",
+    ///         Priority = 100,
+    ///         Direction = SecurityRuleDirection.Inbound,
+    ///         Access = SecurityRuleAccess.Allow,
+    ///         Protocol = SecurityRuleProtocol.Tcp,
+    ///         DestinationPortRange = "443"
+    ///     });
+    /// </code>
+    /// </example>
+    public static IResourceBuilder<AzureNetworkSecurityGroupResource> AddNetworkSecurityGroup(
+        this IDistributedApplicationBuilder builder,
+        [ResourceName] string name)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentException.ThrowIfNullOrEmpty(name);
+
+        builder.AddAzureProvisioning();
+
+        var resource = new AzureNetworkSecurityGroupResource(name, ConfigureNetworkSecurityGroup);
+
+        if (builder.ExecutionContext.IsRunMode)
+        {
+            return builder.CreateResourceBuilder(resource);
+        }
+
+        return builder.AddResource(resource);
+    }
+
+    /// <summary>
+    /// Adds a security rule to the Network Security Group.
+    /// </summary>
+    /// <param name="builder">The Network Security Group resource builder.</param>
+    /// <param name="rule">The security rule configuration.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{AzureNetworkSecurityGroupResource}"/> for chaining.</returns>
+    /// <example>
+    /// This example adds multiple security rules to a Network Security Group:
+    /// <code>
+    /// var nsg = builder.AddNetworkSecurityGroup("web-nsg")
+    ///     .WithSecurityRule(new AzureSecurityRule
+    ///     {
+    ///         Name = "allow-https",
+    ///         Priority = 100,
+    ///         Direction = SecurityRuleDirection.Inbound,
+    ///         Access = SecurityRuleAccess.Allow,
+    ///         Protocol = SecurityRuleProtocol.Tcp,
+    ///         DestinationPortRange = "443"
+    ///     })
+    ///     .WithSecurityRule(new AzureSecurityRule
+    ///     {
+    ///         Name = "deny-all-inbound",
+    ///         Priority = 4096,
+    ///         Direction = SecurityRuleDirection.Inbound,
+    ///         Access = SecurityRuleAccess.Deny,
+    ///         Protocol = SecurityRuleProtocol.Asterisk,
+    ///         DestinationPortRange = "*"
+    ///     });
+    /// </code>
+    /// </example>
+    public static IResourceBuilder<AzureNetworkSecurityGroupResource> WithSecurityRule(
+        this IResourceBuilder<AzureNetworkSecurityGroupResource> builder,
+        AzureSecurityRule rule)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(rule);
+        ArgumentException.ThrowIfNullOrEmpty(rule.Name);
+
+        if (builder.Resource.SecurityRules.Any(existing => string.Equals(existing.Name, rule.Name, StringComparison.OrdinalIgnoreCase)))
+        {
+            throw new ArgumentException(
+                $"A security rule named '{rule.Name}' already exists in Network Security Group '{builder.Resource.Name}'.",
+                nameof(rule));
+        }
+
+        builder.Resource.SecurityRules.Add(rule);
+        return builder;
+    }
+
+    private static void ConfigureNetworkSecurityGroup(AzureResourceInfrastructure infra)
+    {
+        var azureResource = (AzureNetworkSecurityGroupResource)infra.AspireResource;
+
+        var nsg = AzureProvisioningResource.CreateExistingOrNewProvisionableResource(infra,
+            (identifier, name) =>
+            {
+                var resource = NetworkSecurityGroup.FromExisting(identifier);
+                resource.Name = name;
+                return resource;
+            },
+            (infrastructure) =>
+            {
+                return new NetworkSecurityGroup(infrastructure.AspireResource.GetBicepIdentifier())
+                {
+                    Tags = { { "aspire-resource-name", infrastructure.AspireResource.Name } }
+                };
+            });
+
+        foreach (var rule in azureResource.SecurityRules)
+        {
+            var ruleIdentifier = Infrastructure.NormalizeBicepIdentifier($"{nsg.BicepIdentifier}_{rule.Name}");
+            var securityRule = new SecurityRule(ruleIdentifier)
+            {
+                Name = rule.Name,
+                Priority = rule.Priority,
+                Direction = rule.Direction,
+                Access = rule.Access,
+                Protocol = rule.Protocol,
+                SourceAddressPrefix = rule.SourceAddressPrefix,
+                SourcePortRange = rule.SourcePortRange,
+                DestinationAddressPrefix = rule.DestinationAddressPrefix,
+                DestinationPortRange = rule.DestinationPortRange,
+                Parent = nsg,
+            };
+            infra.Add(securityRule);
+        }
+
+        infra.Add(new ProvisioningOutput("id", typeof(string))
+        {
+            Value = nsg.Id
+        });
+
+        infra.Add(new ProvisioningOutput("name", typeof(string))
+        {
+            Value = nsg.Name
+        });
+    }
+}