Add NAT Gateway and Public IP Address support to Azure Virtual Network (#14413)

* Add NAT Gateway and Public IP Address support to Azure Virtual Network

Add AzureNatGatewayResource and AzurePublicIPAddressResource as standalone
top-level Azure provisioning resources. A NAT Gateway provides deterministic
outbound IP addresses for subnet resources.

Key design decisions:
- NAT Gateway is a standalone resource (builder.AddNatGateway), not a VNet child
- A Public IP Address is auto-created inline in the NAT Gateway bicep module
  when no explicit PIP is provided via WithPublicIPAddress()
- AzurePublicIPAddressResource is a public reusable type for explicit PIP scenarios
- Cross-module references use BicepOutputReference + AsProvisioningParameter
- Advanced config (idle timeout, zones) available via ConfigureInfrastructure

New public API:
- AzureNatGatewayResource (.Id, .NameOutput)
- AzurePublicIPAddressResource (.Id, .NameOutput)
- AddNatGateway() extension on IDistributedApplicationBuilder
- AddPublicIPAddress() extension on IDistributedApplicationBuilder
- WithPublicIPAddress() extension on IResourceBuilder<AzureNatGatewayResource>
- WithNatGateway() extension on IResourceBuilder<AzureSubnetResource>

* Address PR feedback

Add Tag to auto-created Public IP Address.

Author: eerhardt

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/Program.cs

@@ -11,6 +11,10 @@
 var containerAppsSubnet = vnet.AddSubnet("container-apps", "10.0.0.0/23");
 var privateEndpointsSubnet = vnet.AddSubnet("private-endpoints", "10.0.2.0/27");
 
+// Create a NAT Gateway for deterministic outbound IP on the ACA subnet
+var natGateway = builder.AddNatGateway("nat");
+containerAppsSubnet.WithNatGateway(natGateway);
+
 // Configure the Container App Environment to use the VNet
 builder.AddAzureContainerAppEnvironment("env")
     .WithDelegatedSubnet(containerAppsSubnet);

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

@@ -3,7 +3,14 @@
   "resources": {
     "vnet": {
       "type": "azure.bicep.v0",
-      "path": "vnet.module.bicep"
+      "path": "vnet.module.bicep",
+      "params": {
+        "nat_outputs_id": "{nat.outputs.id}"
+      }
+    },
+    "nat": {
+      "type": "azure.bicep.v0",
+      "path": "nat.module.bicep"
     },
     "env-acr": {
       "type": "azure.bicep.v0",

playground/AzureVirtualNetworkEndToEnd/AzureVirtualNetworkEndToEnd.AppHost/nat.module.bicep

@@ -0,0 +1,38 @@
+@description('The location for the resource(s) to be deployed.')
+param location string = resourceGroup().location
+
+resource nat_pip 'Microsoft.Network/publicIPAddresses@2025-05-01' = {
+  name: take('nat_pip-${uniqueString(resourceGroup().id)}', 80)
+  location: location
+  properties: {
+    publicIPAllocationMethod: 'Static'
+  }
+  sku: {
+    name: 'Standard'
+  }
+  tags: {
+    'aspire-resource-name': 'nat'
+  }
+}
+
+resource nat 'Microsoft.Network/natGateways@2025-05-01' = {
+  name: take('nat${uniqueString(resourceGroup().id)}', 24)
+  location: location
+  properties: {
+    publicIpAddresses: [
+      {
+        id: nat_pip.id
+      }
+    ]
+  }
+  sku: {
+    name: 'Standard'
+  }
+  tags: {
+    'aspire-resource-name': 'nat'
+  }
+}
+
+output id string = nat.id
+
+output name string = nat.name

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

@@ -1,6 +1,8 @@
 @description('The location for the resource(s) to be deployed.')
 param location string = resourceGroup().location
 
+param nat_outputs_id string
+
 resource vnet 'Microsoft.Network/virtualNetworks@2025-05-01' = {
   name: take('vnet-${uniqueString(resourceGroup().id)}', 64)
   properties: {
@@ -28,6 +30,9 @@ resource container_apps 'Microsoft.Network/virtualNetworks/subnets@2025-05-01' =
         name: 'Microsoft.App/environments'
       }
     ]
+    natGateway: {
+      id: nat_outputs_id
+    }
   }
   parent: vnet
 }

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

@@ -0,0 +1,149 @@
+// 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;
+using Azure.Provisioning.Resources;
+
+namespace Aspire.Hosting;
+
+/// <summary>
+/// Provides extension methods for adding Azure NAT Gateway resources to the application model.
+/// </summary>
+public static class AzureNatGatewayExtensions
+{
+    /// <summary>
+    /// Adds an Azure NAT Gateway resource to the application model.
+    /// </summary>
+    /// <param name="builder">The builder for the distributed application.</param>
+    /// <param name="name">The name of the Azure NAT Gateway resource.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{AzureNatGatewayResource}"/>.</returns>
+    /// <remarks>
+    /// The NAT Gateway is created with Standard SKU. If no Public IP Address is explicitly associated
+    /// via <see cref="WithPublicIPAddress"/>, a Public IP Address is automatically created in the
+    /// NAT Gateway's bicep module with Standard SKU and Static allocation.
+    /// </remarks>
+    /// <example>
+    /// This example creates a NAT Gateway and associates it with a subnet:
+    /// <code>
+    /// var natGateway = builder.AddNatGateway("nat");
+    ///
+    /// var vnet = builder.AddAzureVirtualNetwork("vnet");
+    /// var subnet = vnet.AddSubnet("aca-subnet", "10.0.0.0/23")
+    ///     .WithNatGateway(natGateway);
+    /// </code>
+    /// </example>
+    public static IResourceBuilder<AzureNatGatewayResource> AddNatGateway(
+        this IDistributedApplicationBuilder builder,
+        [ResourceName] string name)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentException.ThrowIfNullOrEmpty(name);
+
+        builder.AddAzureProvisioning();
+
+        var resource = new AzureNatGatewayResource(name, ConfigureNatGateway);
+
+        if (builder.ExecutionContext.IsRunMode)
+        {
+            return builder.CreateResourceBuilder(resource);
+        }
+
+        return builder.AddResource(resource);
+    }
+
+    /// <summary>
+    /// Associates an explicit Public IP Address resource with the NAT Gateway.
+    /// </summary>
+    /// <param name="builder">The NAT Gateway resource builder.</param>
+    /// <param name="publicIPAddress">The Public IP Address resource to associate.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{AzureNatGatewayResource}"/> for chaining.</returns>
+    /// <remarks>
+    /// When an explicit Public IP Address is provided, the NAT Gateway will not auto-create one.
+    /// </remarks>
+    /// <example>
+    /// This example creates a NAT Gateway with an explicit Public IP:
+    /// <code>
+    /// var pip = builder.AddPublicIPAddress("nat-pip");
+    /// var natGateway = builder.AddNatGateway("nat")
+    ///     .WithPublicIPAddress(pip);
+    /// </code>
+    /// </example>
+    public static IResourceBuilder<AzureNatGatewayResource> WithPublicIPAddress(
+        this IResourceBuilder<AzureNatGatewayResource> builder,
+        IResourceBuilder<AzurePublicIPAddressResource> publicIPAddress)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentNullException.ThrowIfNull(publicIPAddress);
+
+        builder.Resource.PublicIPAddresses.Add(publicIPAddress.Resource);
+        return builder;
+    }
+
+    private static void ConfigureNatGateway(AzureResourceInfrastructure infra)
+    {
+        var azureResource = (AzureNatGatewayResource)infra.AspireResource;
+
+        var natGw = AzureProvisioningResource.CreateExistingOrNewProvisionableResource(infra,
+            (identifier, name) =>
+            {
+                var resource = NatGateway.FromExisting(identifier);
+                resource.Name = name;
+                return resource;
+            },
+            (infrastructure) =>
+            {
+                var natGw = new NatGateway(infrastructure.AspireResource.GetBicepIdentifier())
+                {
+                    SkuName = NatGatewaySkuName.Standard,
+                    Tags = { { "aspire-resource-name", infrastructure.AspireResource.Name } }
+                };
+
+                // If explicit Public IP addresses are provided, reference them via parameters
+                if (azureResource.PublicIPAddresses.Count > 0)
+                {
+                    foreach (var pipResource in azureResource.PublicIPAddresses)
+                    {
+                        var pipIdParam = pipResource.Id.AsProvisioningParameter(infrastructure);
+                        natGw.PublicIPAddresses.Add(new WritableSubResource
+                        {
+                            Id = pipIdParam
+                        });
+                    }
+                }
+                else
+                {
+                    // Auto-create a Public IP Address inline
+                    var pip = new PublicIPAddress($"{infrastructure.AspireResource.GetBicepIdentifier()}_pip")
+                    {
+                        Sku = new PublicIPAddressSku()
+                        {
+                            Name = PublicIPAddressSkuName.Standard,
+                        },
+                        PublicIPAllocationMethod = NetworkIPAllocationMethod.Static,
+                        Tags = { { "aspire-resource-name", infrastructure.AspireResource.Name } }
+                    };
+                    infrastructure.Add(pip);
+
+                    natGw.PublicIPAddresses.Add(new WritableSubResource
+                    {
+                        Id = pip.Id
+                    });
+                }
+
+                return natGw;
+            });
+
+        infra.Add(new ProvisioningOutput("id", typeof(string))
+        {
+            Value = natGw.Id
+        });
+
+        infra.Add(new ProvisioningOutput("name", typeof(string))
+        {
+            Value = natGw.Name
+        });
+    }
+}

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

@@ -0,0 +1,60 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Azure.Provisioning.Network;
+using Azure.Provisioning.Primitives;
+
+namespace Aspire.Hosting.Azure;
+
+/// <summary>
+/// Represents an Azure NAT Gateway resource.
+/// </summary>
+/// <remarks>
+/// A NAT Gateway provides outbound internet connectivity for resources in a virtual network subnet.
+/// Use <see cref="AzureProvisioningResourceExtensions.ConfigureInfrastructure{T}(ApplicationModel.IResourceBuilder{T}, Action{AzureResourceInfrastructure})"/>
+/// to configure specific <see cref="Azure.Provisioning"/> properties.
+/// </remarks>
+/// <param name="name">The name of the resource.</param>
+/// <param name="configureInfrastructure">Callback to configure the Azure NAT Gateway resource.</param>
+public class AzureNatGatewayResource(string name, Action<AzureResourceInfrastructure> configureInfrastructure)
+    : AzureProvisioningResource(name, configureInfrastructure)
+{
+    /// <summary>
+    /// Gets the "id" output reference from the Azure NAT Gateway resource.
+    /// </summary>
+    public BicepOutputReference Id => new("id", this);
+
+    /// <summary>
+    /// Gets the "name" output reference for the resource.
+    /// </summary>
+    public BicepOutputReference NameOutput => new("name", this);
+
+    /// <summary>
+    /// Gets the list of explicit Public IP Address resources associated with this NAT Gateway.
+    /// </summary>
+    internal List<AzurePublicIPAddressResource> PublicIPAddresses { get; } = [];
+
+    /// <inheritdoc/>
+    public override ProvisionableResource AddAsExistingResource(AzureResourceInfrastructure infra)
+    {
+        var bicepIdentifier = this.GetBicepIdentifier();
+        var resources = infra.GetProvisionableResources();
+
+        var existing = resources.OfType<NatGateway>().SingleOrDefault(r => r.BicepIdentifier == bicepIdentifier);
+
+        if (existing is not null)
+        {
+            return existing;
+        }
+
+        var natGw = NatGateway.FromExisting(bicepIdentifier);
+
+        if (!TryApplyExistingResourceAnnotation(this, infra, natGw))
+        {
+            natGw.Name = NameOutput.AsProvisioningParameter(infra);
+        }
+
+        infra.Add(natGw);
+        return natGw;
+    }
+}

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

@@ -0,0 +1,84 @@
+// 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 Public IP Address resources to the application model.
+/// </summary>
+public static class AzurePublicIPAddressExtensions
+{
+    /// <summary>
+    /// Adds an Azure Public IP Address resource to the application model.
+    /// </summary>
+    /// <param name="builder">The builder for the distributed application.</param>
+    /// <param name="name">The name of the Azure Public IP Address resource.</param>
+    /// <returns>A reference to the <see cref="IResourceBuilder{AzurePublicIPAddressResource}"/>.</returns>
+    /// <remarks>
+    /// The Public IP Address is created with Standard SKU and Static allocation by default.
+    /// Use <see cref="AzureProvisioningResourceExtensions.ConfigureInfrastructure{T}(IResourceBuilder{T}, Action{AzureResourceInfrastructure})"/>
+    /// to customize properties such as DNS labels, availability zones, or IP version.
+    /// </remarks>
+    /// <example>
+    /// This example creates a Public IP Address:
+    /// <code>
+    /// var pip = builder.AddPublicIPAddress("my-pip");
+    /// </code>
+    /// </example>
+    public static IResourceBuilder<AzurePublicIPAddressResource> AddPublicIPAddress(
+        this IDistributedApplicationBuilder builder,
+        [ResourceName] string name)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+        ArgumentException.ThrowIfNullOrEmpty(name);
+
+        builder.AddAzureProvisioning();
+
+        var resource = new AzurePublicIPAddressResource(name, ConfigurePublicIPAddress);
+
+        if (builder.ExecutionContext.IsRunMode)
+        {
+            return builder.CreateResourceBuilder(resource);
+        }
+
+        return builder.AddResource(resource);
+    }
+
+    private static void ConfigurePublicIPAddress(AzureResourceInfrastructure infra)
+    {
+        var pip = AzureProvisioningResource.CreateExistingOrNewProvisionableResource(infra,
+            (identifier, name) =>
+            {
+                var resource = PublicIPAddress.FromExisting(identifier);
+                resource.Name = name;
+                return resource;
+            },
+            (infrastructure) =>
+            {
+                return new PublicIPAddress(infrastructure.AspireResource.GetBicepIdentifier())
+                {
+                    Sku = new PublicIPAddressSku()
+                    {
+                        Name = PublicIPAddressSkuName.Standard,
+                    },
+                    PublicIPAllocationMethod = NetworkIPAllocationMethod.Static,
+                    Tags = { { "aspire-resource-name", infrastructure.AspireResource.Name } }
+                };
+            });
+
+        infra.Add(new ProvisioningOutput("id", typeof(string))
+        {
+            Value = pip.Id
+        });
+
+        infra.Add(new ProvisioningOutput("name", typeof(string))
+        {
+            Value = pip.Name
+        });
+    }
+}