// 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 ASPIREAZURE003 // Type is for evaluation purposes only and is subject to change or removal in future updates.
using System.Diagnostics.CodeAnalysis;
using Aspire.Hosting.ApplicationModel;
using Aspire.Hosting.Azure;
namespace Aspire.Hosting;
/// <summary>
/// Extension methods for reaching Azure Container Apps or Azure App Service through Azure Front Door Private Link.
/// </summary>
public static class AzureFrontDoorPrivateLinkExtensions
{
/// <summary>
/// Connects an Azure Front Door to a compute environment, such as an Azure Container Apps environment, over Private
/// Link and disables public network access to its apps, so that the apps in the environment are reachable only
/// through the Front Door.
/// </summary>
/// <typeparam name="T">The type of the compute environment, which implements <see cref="IAzureCdnPrivateLinkTarget"/>.</typeparam>
/// <param name="environment">The compute environment to connect to.</param>
/// <param name="frontDoor">
/// The Azure Front Door, created with <see cref="AzureFrontDoorExtensions.AddAzureFrontDoor"/>, whose origins in
/// <paramref name="environment"/> use Private Link.
/// </param>
/// <returns>A reference to the <see cref="IResourceBuilder{T}"/> for <paramref name="environment"/>, for chaining.</returns>
/// <ats-returns>The resource builder.</ats-returns>
/// <remarks>
/// <para>
/// Add the apps to the Front Door with <see cref="AzureFrontDoorExtensions.WithOrigin"/>, before or after this call.
/// When publishing, every origin of <paramref name="frontDoor"/> that runs in <paramref name="environment"/> becomes a
/// Private Link origin: the Front Door profile uses the Premium SKU, and the origin connects to the environment through
/// a Front Door managed private endpoint. The apps must expose external HTTP endpoints, for example with
/// <c>WithExternalHttpEndpoints</c>. Origins in other compute environments are left as they are.
/// </para>
/// <para>
/// Like a private endpoint to any other Azure resource, the Private Link disables public network access to the
/// environment. Apps in the environment are no longer reachable from the Internet except through Front Door. Callers
/// outside the environment must reach the apps through the Front Door, or through a route of their own.
/// </para>
/// <para>
/// An Azure Container Apps environment can only have its public network access disabled when Aspire provisions it, so it
/// can't be marked as existing, and it must be a workload profiles environment, not an
/// <see href="https://learn.microsoft.com/azure/container-apps/express-overview">Azure Container Apps Express</see>
/// environment.
/// </para>
/// <para>
/// For Azure App Service, each origin targets its own website with the <c>sites</c> group ID, not the App Service plan.
/// Public network access is disabled on all workload websites in the connected environment, including websites that
/// are not Front Door origins. The separately provisioned Aspire dashboard is unchanged. Existing App Service plans
/// are supported because Aspire still provisions the websites. Front Door Private Link cannot target a deployment slot,
/// so with <c>WithDeploymentSlot</c> each origin targets the production site and the slot, which has public access
/// disabled and no private endpoint, is not reachable through Front Door: deploy to the slot and swap it into production.
/// The production site is created only if it does not exist, so enabling this on a site that already exists doesn't
/// disable its public access. Unlike Container Apps, App Service does not provide an environment-local ingress route between apps:
/// service-to-service callers must use Front Door URLs or configure their own private network access and DNS.
/// </para>
/// <para>
/// Front Door creates a connection request in the Pending state, and no traffic reaches the apps until the owner of
/// the target approves it. Approve it in the Azure portal, under the Container Apps environment's or each App Service
/// website's networking settings, or with
/// the Azure CLI by finding the request with <c>az network private-endpoint-connection list</c> and approving it with
/// <c>az network private-endpoint-connection approve</c>. Front Door can create more than one request; approve each
/// one that has the message of this connection. Traffic starts flowing a few minutes after approval.
/// </para>
/// <para>
/// Front Door creates its private endpoint in the region of <paramref name="environment"/>. Front Door Private Link is
/// only available in some
/// <see href="https://learn.microsoft.com/azure/frontdoor/private-link#region-availability">regions</see>, so for an
/// environment in another region the private endpoint is created in the supported region of the same geography, such as
/// <c>westus2</c> for <c>westus</c>, at the cost of an extra network hop. Deployment fails when the geography has no
/// supported region. To choose another region, set the origin's <c>SharedPrivateLinkResource.PrivateLinkLocation</c> in
/// <see cref="AzureProvisioningResourceExtensions.ConfigureInfrastructure{T}"/> on <paramref name="frontDoor"/>, for
/// example to a parameter.
/// </para>
/// <para>
/// Private Link has no run-mode counterpart, so this method does nothing when the AppHost runs locally.
/// </para>
/// </remarks>
/// <ats-remarks>
/// <para>
/// Add the apps to the Front Door with <c>withOrigin</c>, before or after this call. Every origin of the Front Door that
/// runs in the environment becomes a Private Link origin: the Front Door profile uses the Premium SKU, and the origin
/// connects to the environment through a Front Door managed private endpoint. The apps must expose external HTTP
/// endpoints. Origins in other compute environments are left as they are.
/// </para>
/// <para>
/// Public network access to the environment is disabled, so the apps are reachable only through the Front Door. The
/// Container Apps environment must be a workload profiles environment that Aspire provisions. For App Service,
/// each origin targets its own website, all workload websites have public access disabled, and with deployment slots
/// each origin targets the production site; the slot isn't reachable through Front Door, so swap it into production.
/// The separately provisioned dashboard is unchanged. App Service callers must use Front Door
/// URLs or their own private networking for service-to-service traffic.
/// </para>
/// <para>
/// Front Door creates a connection request in the Pending state, and no traffic reaches the apps until the owner of
/// the environment approves it in the Azure portal or with <c>az network private-endpoint-connection approve</c>.
/// </para>
/// </ats-remarks>
/// <exception cref="ArgumentNullException"><paramref name="environment"/> or <paramref name="frontDoor"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">
/// Publishing fails for existing or Express Container Apps environments, when
/// <paramref name="frontDoor"/> has no origin in the environment, and when another Front Door has an origin in the
/// environment without being connected to it.
/// </exception>
/// <example>
/// <code lang="csharp">
/// var environment = builder.AddAzureContainerAppEnvironment("env");
/// var frontDoor = builder.AddAzureFrontDoor("frontdoor");
/// environment.WithAzureFrontDoorPrivateLink(frontDoor);
///
/// var api = builder.AddDotnetProject("api", "../Api/Api.csproj")
/// .WithExternalHttpEndpoints();
/// var web = builder.AddDotnetProject("web", "../Web/Web.csproj")
/// .WithExternalHttpEndpoints()
/// .WithReference(api);
/// frontDoor.WithOrigin(api).WithOrigin(web);
/// </code>
/// </example>
/// <seealso href="https://learn.microsoft.com/azure/container-apps/how-to-integrate-with-azure-front-door">Access a container app using Azure Front Door with Private Link</seealso>
/// <seealso href="https://learn.microsoft.com/azure/frontdoor/standard-premium/how-to-enable-private-link-web-app">Connect Azure Front Door to an App Service origin using Private Link</seealso>
[AspireExport("withFrontDoorAzureFrontDoorPrivateLink", MethodName = "withAzureFrontDoorPrivateLink")]
[Experimental("ASPIREAZURE003", UrlFormat = "https://aka.ms/aspire/diagnostics#{0}")]
public static IResourceBuilder<T> WithAzureFrontDoorPrivateLink<T>(
this IResourceBuilder<T> environment,
IResourceBuilder<AzureFrontDoorResource> frontDoor)
where T : IAzureCdnPrivateLinkTarget
{
ArgumentNullException.ThrowIfNull(environment);
ArgumentNullException.ThrowIfNull(frontDoor);
if (!environment.ApplicationBuilder.ExecutionContext.IsPublishMode)
{
return environment;
}
// Calling this again for the same environment and Front Door has nothing more to do.
if (frontDoor.Resource.Annotations
.OfType<AzureFrontDoorPrivateLinkAnnotation>()
.Any(annotation => ReferenceEquals(annotation.Environment, environment.Resource)))
{
return environment;
}
frontDoor.WithAnnotation(new AzureFrontDoorPrivateLinkAnnotation(frontDoor.Resource, environment.Resource));
// A private link target denies public network access, as it does for a private endpoint to any other Azure
// resource. The Front Door is the resource that creates the managed private endpoint.
environment.WithAnnotation(new PrivateEndpointTargetAnnotation(frontDoor.Resource));
return environment;
}
}