Resolve cross-compute-environment endpoint references for Foundry hosted agents (#17756)

* Resolve cross-compute-environment endpoint references to Foundry hosted agents

Fixes #17749. When a resource deployed to App Service, Azure Container
Apps, or Kubernetes used WithReference() to reference a Foundry hosted
agent, publishing failed because the publisher resolved the endpoint
against its own local endpoint map, which does not contain the agent
(deployed to the Foundry project compute environment).

Introduce a shared ComputeEnvironmentEndpointResolver that, when an
endpoint's owning resource is deployed to a different compute environment
than the current publisher, delegates resolution to that owning
environment's GetEndpointPropertyExpression. The three compute-environment
publishers now call it in both the EndpointReference and
EndpointReferenceExpression branches. Azure Front Door and the Foundry
hosted-agent resolver are refactored onto the same shared lookup.

AzureCognitiveServicesProjectResource gets a GetEndpointPropertyExpression
override because the agent address is already a full https URL; the
default scheme://host composition would produce a malformed double-scheme
value.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add branch tests for ComputeEnvironmentEndpointResolver and correct misleading comment

Add direct unit tests covering each branch of TryGetCrossEnvironmentEndpointExpression:
cross-environment delegation, same-environment deployment target, WithComputeEnvironment
binding backstop, no-compute-environment, bound multi-target (no throw), and unbound
multi-target (throws). Correct the comment on the fast-path loop which incorrectly claimed
it never throws on multi-target resources.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Remove redundant fast-path loop from ComputeEnvironmentEndpointResolver

The first foreach loop using GetDeploymentTargetAnnotation(current) was redundant with
TryGetEffectiveComputeEnvironment + the ReferenceEquals backstop for all well-formed inputs,
and did not provide multi-target throw-safety. Remove it and keep the simpler resolve-then-
compare flow. All six branch tests continue to pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Drop params and move out parameter last in cross-env endpoint resolver

Replace the params IComputeEnvironmentResource?[] with an explicit
IReadOnlyList parameter placed before the out, so the out parameter
comes last per convention. Kubernetes still passes two current
environments (its environment plus OwningComputeEnvironment) via a
collection expression; ACA and AppService pass a single-element list.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add EndpointReference overload for cross-env endpoint resolver

Add an overload taking EndpointReference that uses ep.Property(EndpointProperty.Url)
internally, so the three EndpointReference call sites (ACA, AppService, Kubernetes)
pass the endpoint directly instead of repeating the .Property(Url) projection.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Use hosted-agent deployment name in cross-env Foundry agent URL

Hosted-agent deployment creates the Foundry agent version using the
wrapper AzureHostedAgentResource.Name (e.g. "agent-ha" for a target
named "agent"). The published cross-environment endpoint path was built
from the bare resource name, producing /agents/agent which does not match
the deployed /agents/agent-ha. Resolve the hosted-agent deployment target
and use its name when present, falling back to the resource name for
non-hosted agents.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Auto-wire Azure AI User role for hosted-agent consumers

When a compute resource references a Foundry hosted agent's node app via
WithReference, automatically grant the consumer the Azure AI User role on the
owning Foundry account and provision a managed identity, removing the two manual
post-deploy `az role assignment create` steps.

Introduces a public, experimental ReferenceRoleAssignmentAnnotation in
Aspire.Hosting.Azure. A resource that "fronts" an Azure resource (without being
an IAzureResource itself) carries this annotation; AzureResourcePreparer folds
its (Target, Roles) into the same role-assignment path used for direct Azure
references. Foundry's AsHostedAgent stamps the annotation on the agent's node
app granting only the least-privilege Azure AI User role; account defaults and
explicit WithRoleAssignments suppression remain owned by the preparer and are
not reintroduced. GetAllRoleAssignments now dedupes roles per target to avoid
colliding bicep role-assignment identifiers.

Adds preparer end-to-end tests (suppression preserved, defaults preserved,
dedup) and Foundry stamp tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Regenerate cross-env Foundry snapshots for RBAC auto-wiring

The cross-compute-environment Foundry hosted-agent snapshots were committed
before the RBAC auto-wiring change and never regenerated. With the consumer
now receiving a managed identity (web-identity) plus AZURE_CLIENT_ID and
AZURE_TOKEN_CREDENTIALS env vars, the generated bicep/json changed. CI failed
because the verified baselines were stale; local runs masked it because Verify
auto-accepts on developer machines.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: davidfowl

src/Aspire.Hosting.Azure.AppContainers/Aspire.Hosting.Azure.AppContainers.csproj

@@ -11,6 +11,7 @@
   <ItemGroup>
     <Compile Include="$(SharedDir)AzurePortalUrls.cs" Link="AzurePortalUrls.cs" />
     <Compile Include="$(SharedDir)BicepFormattingHelpers.cs" LinkBase="Shared\BicepFormattingHelpers.cs" />
+    <Compile Include="$(SharedDir)ComputeEnvironmentEndpointResolver.cs" LinkBase="Shared\ComputeEnvironmentEndpointResolver.cs" />
     <Compile Include="$(SharedDir)ContainerRegistryInfrastructure.cs" LinkBase="Shared\ContainerRegistryInfrastructure.cs" />
     <Compile Include="$(SharedDir)ResourceNameComparer.cs" LinkBase="Shared\ResourceNameComparer.cs" />
   </ItemGroup>

src/Aspire.Hosting.Azure.AppContainers/BaseContainerAppContext.cs

@@ -222,6 +222,15 @@ BicepValue<string> GetHostValue(string? prefix = null, string? suffix = null)
 
         if (value is EndpointReference ep)
         {
+            // The referenced endpoint may belong to a resource deployed to a different compute
+            // environment (for example a Foundry hosted agent). In that case delegate to the owning
+            // compute environment instead of looking it up in this environment's local endpoint map.
+            if (ComputeEnvironmentEndpointResolver.TryGetCrossEnvironmentEndpointExpression(
+                ep, [_containerAppEnvironmentContext.Environment], out var crossExpr))
+            {
+                return ProcessValue(crossExpr, secretType, parent);
+            }
+
             var context = ep.Resource == resource
                 ? this
                 : _containerAppEnvironmentContext.GetContainerAppContext(ep.Resource);
@@ -274,6 +283,12 @@ BicepValue<string> GetHostValue(string? prefix = null, string? suffix = null)
 
         if (value is EndpointReferenceExpression epExpr)
         {
+            if (ComputeEnvironmentEndpointResolver.TryGetCrossEnvironmentEndpointExpression(
+                epExpr, [_containerAppEnvironmentContext.Environment], out var crossExpr))
+            {
+                return ProcessValue(crossExpr, secretType, parent);
+            }
+
             var context = epExpr.Endpoint.Resource == resource
                 ? this
                 : _containerAppEnvironmentContext.GetContainerAppContext(epExpr.Endpoint.Resource);

src/Aspire.Hosting.Azure.AppService/Aspire.Hosting.Azure.AppService.csproj

@@ -13,6 +13,7 @@
   <ItemGroup>
     <Compile Include="$(SharedDir)AzurePortalUrls.cs" Link="AzurePortalUrls.cs" />
     <Compile Include="$(SharedDir)BicepFormattingHelpers.cs" LinkBase="Shared\BicepFormattingHelpers.cs" />
+    <Compile Include="$(SharedDir)ComputeEnvironmentEndpointResolver.cs" LinkBase="Shared\ComputeEnvironmentEndpointResolver.cs" />
     <Compile Include="$(SharedDir)ContainerRegistryInfrastructure.cs" LinkBase="Shared\ContainerRegistryInfrastructure.cs" />
     <Compile Include="$(SharedDir)DashboardConfigNames.cs" LinkBase="Shared\DashboardConfigNames.cs" />
     <Compile Include="$(SharedDir)KnownConfigNames.cs" LinkBase="Shared\KnownConfigNames.cs" />

src/Aspire.Hosting.Azure.AppService/AzureAppServiceWebsiteContext.cs

@@ -167,6 +167,15 @@ private void ProcessEndpoints()
 
         if (value is EndpointReference ep)
         {
+            // The referenced endpoint may belong to a resource deployed to a different compute
+            // environment (for example a Foundry hosted agent). In that case delegate to the owning
+            // compute environment instead of looking it up in this environment's local endpoint map.
+            if (ComputeEnvironmentEndpointResolver.TryGetCrossEnvironmentEndpointExpression(
+                ep, [environmentContext.Environment], out var crossExpr))
+            {
+                return ProcessValue(crossExpr, secretType, parent, isSlot);
+            }
+
             var context = environmentContext.GetAppServiceContext(ep.Resource);
             return isSlot ?
                 (GetEndpointValue(context._slotEndpointMapping[ep.EndpointName], EndpointProperty.Url), secretType) :
@@ -206,6 +215,12 @@ private void ProcessEndpoints()
 
         if (value is EndpointReferenceExpression epExpr)
         {
+            if (ComputeEnvironmentEndpointResolver.TryGetCrossEnvironmentEndpointExpression(
+                epExpr, [environmentContext.Environment], out var crossExpr))
+            {
+                return ProcessValue(crossExpr, secretType, parent, isSlot);
+            }
+
             var context = environmentContext.GetAppServiceContext(epExpr.Endpoint.Resource);
             var mapping = isSlot ? context._slotEndpointMapping[epExpr.Endpoint.EndpointName] : context._endpointMapping[epExpr.Endpoint.EndpointName];
             var val = GetEndpointValue(mapping, epExpr.Property);

src/Aspire.Hosting.Azure.FrontDoor/Aspire.Hosting.Azure.FrontDoor.csproj

@@ -15,6 +15,10 @@
     <PackageReference Include="Azure.Provisioning.Cdn" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="$(SharedDir)ComputeEnvironmentEndpointResolver.cs" LinkBase="Shared\ComputeEnvironmentEndpointResolver.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <InternalsVisibleTo Include="Aspire.Hosting.Azure.Tests" />
   </ItemGroup>

src/Aspire.Hosting.Azure.FrontDoor/AzureFrontDoorExtensions.cs

@@ -201,16 +201,11 @@ public static IResourceBuilder<AzureFrontDoorResource> WithOrigin<T>(
 
     private static IComputeEnvironmentResource GetEffectiveComputeEnvironment(IResource resource)
     {
-        if (resource.GetComputeEnvironment() is { } computeEnvironment)
+        if (ComputeEnvironmentEndpointResolver.TryGetEffectiveComputeEnvironment(resource, out var computeEnvironment))
         {
             return computeEnvironment;
         }
 
-        if (resource.GetDeploymentTargetAnnotation()?.ComputeEnvironment is { } deploymentComputeEnvironment)
-        {
-            return deploymentComputeEnvironment;
-        }
-
         throw new InvalidOperationException(
             $"Resource '{resource.Name}' does not have a compute environment. " +
             "Ensure a compute environment (e.g., Azure Container Apps, Azure App Service) is configured in the application model.");

src/Aspire.Hosting.Azure/AzureResourcePreparer.cs

@@ -133,7 +133,8 @@ private async Task BuildRoleAssignmentAnnotations(DistributedApplicationModel ap
             foreach (var resource in resourceSnapshot)
             {
                 var prerequisiteResources = new HashSet<AzureBicepResource>();
-                var azureReferences = await GetAzureReferences(resource, cancellationToken).ConfigureAwait(false);
+                var directDependencies = await resource.GetResourceDependenciesAsync(executionContext, ResourceDependencyDiscoveryMode.DirectOnly, cancellationToken).ConfigureAwait(false);
+                var azureReferences = new HashSet<IAzureResource>(directDependencies.OfType<IAzureResource>());
 
                 var azureReferencesWithRoleAssignments =
                     (resource.TryGetAnnotationsOfType<RoleAssignmentAnnotation>(out var annotations)
@@ -184,6 +185,42 @@ private async Task BuildRoleAssignmentAnnotations(DistributedApplicationModel ap
                     }
                 }
 
+                // A direct dependency that is not itself an Azure resource can still "front" one
+                // (e.g. a Foundry hosted agent's node app fronts its owning Foundry account). Such a
+                // resource carries ReferenceRoleAssignmentAnnotation(s) declaring that any resource
+                // referencing it should be granted roles on a transitive Azure target the normal
+                // IAzureResource-only reference walk above cannot reach. Fold those implied targets
+                // into the same role-assignment path so the consumer gets an identity + role bicep
+                // exactly as it would for a direct Azure reference.
+                foreach (var dependency in directDependencies)
+                {
+                    if (!dependency.TryGetAnnotationsOfType<ReferenceRoleAssignmentAnnotation>(out var impliedRoleAssignments))
+                    {
+                        continue;
+                    }
+
+                    foreach (var impliedRoleAssignment in impliedRoleAssignments)
+                    {
+                        var target = impliedRoleAssignment.Target;
+                        if (target.IsContainer() || target.IsEmulator())
+                        {
+                            continue;
+                        }
+
+                        if (executionContext.IsRunMode)
+                        {
+                            AppendGlobalRoleAssignments(globalRoleAssignments, target, impliedRoleAssignment.Roles);
+                        }
+                        else
+                        {
+                            // In PublishMode, materialize as an explicit RoleAssignmentAnnotation so
+                            // GetAllRoleAssignments (which groups by target and unions roles) picks it
+                            // up alongside any roles the consumer already declares for the same target.
+                            resource.Annotations.Add(new RoleAssignmentAnnotation(target, impliedRoleAssignment.Roles));
+                        }
+                    }
+                }
+
                 // in PublishMode with SupportsTargetedRoleAssignments, we need to create the identity and role assignment resources
                 // if the resource references any Azure resources, or has role assignments to Azure resources
                 if (executionContext.IsPublishMode)
@@ -250,7 +287,12 @@ private static Dictionary<AzureProvisioningResource, IEnumerable<RoleDefinition>
         {
             foreach (var g in roleAssignments.GroupBy(r => r.Target))
             {
-                result[g.Key] = g.SelectMany(r => r.Roles);
+                // Deduplicate roles per target. A target can accumulate multiple RoleAssignmentAnnotations
+                // (e.g. an implied ReferenceRoleAssignmentAnnotation from two hosted agents on the same
+                // Foundry account, plus a direct reference). Emitting the same RoleDefinition twice would
+                // produce two RoleAssignment bicep resources with the same identifier ("{prefix}_{roleName}")
+                // and fail bicep compilation. This mirrors the RunMode path, which unions into a HashSet.
+                result[g.Key] = g.SelectMany(r => r.Roles).Distinct();
             }
         }
         return result;
@@ -359,19 +401,6 @@ private sealed class AddRoleAssignmentsContext(
         public DistributedApplicationExecutionContext ExecutionContext => executionContext;
     }
 
-    private async Task<HashSet<IAzureResource>> GetAzureReferences(IResource resource, CancellationToken cancellationToken)
-    {
-        var dependencies = await resource.GetResourceDependenciesAsync(executionContext, ResourceDependencyDiscoveryMode.DirectOnly, cancellationToken).ConfigureAwait(false);
-
-        HashSet<IAzureResource> azureReferences = [];
-        foreach (var azureResource in dependencies.OfType<IAzureResource>())
-        {
-            azureReferences.Add(azureResource);
-        }
-
-        return azureReferences;
-    }
-
     private static void AppendGlobalRoleAssignments(Dictionary<AzureProvisioningResource, HashSet<RoleDefinition>> globalRoleAssignments, AzureProvisioningResource azureResource, IEnumerable<RoleDefinition> newRoles)
     {
         if (!globalRoleAssignments.TryGetValue(azureResource, out var existingRoles))

src/Aspire.Hosting.Azure/ReferenceRoleAssignmentAnnotation.cs

@@ -0,0 +1,43 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics.CodeAnalysis;
+using Aspire.Hosting.ApplicationModel;
+
+namespace Aspire.Hosting.Azure;
+
+/// <summary>
+/// Declares that any compute resource referencing the annotated resource should be granted
+/// <see cref="Roles"/> on the Azure resource <see cref="Target"/>.
+/// </summary>
+/// <param name="target">The Azure resource that referencing resources should be granted roles on.</param>
+/// <param name="roles">The roles that referencing resources should be assigned on <paramref name="target"/>.</param>
+/// <remarks>
+/// <para>
+/// This annotation is applied to a resource that "fronts" an Azure resource without being an
+/// <see cref="IAzureResource"/> itself. For example, a Foundry hosted agent's node app is a plain
+/// compute resource, but invoking the agent requires the caller to hold a role on the owning
+/// Foundry account. The account is only a transitive dependency of a consumer, so
+/// <see cref="AzureResourcePreparer"/>'s normal reference walk — which only acts on direct
+/// <see cref="IAzureResource"/> dependencies — cannot reach it.
+/// </para>
+/// <para>
+/// When a compute resource takes a direct dependency on a resource carrying this annotation,
+/// <see cref="AzureResourcePreparer"/> folds <c>(Target, Roles)</c> into the same role-assignment
+/// path used for direct Azure references, so the consumer gets a managed identity and the
+/// corresponding role assignment on <see cref="Target"/> with no additional wiring.
+/// </para>
+/// </remarks>
+[Experimental("ASPIREAZURE003", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
+public sealed class ReferenceRoleAssignmentAnnotation(AzureProvisioningResource target, IReadOnlySet<RoleDefinition> roles) : IResourceAnnotation
+{
+    /// <summary>
+    /// Gets the Azure resource that resources referencing the annotated resource should be granted roles on.
+    /// </summary>
+    public AzureProvisioningResource Target { get; } = target;
+
+    /// <summary>
+    /// Gets the set of roles that resources referencing the annotated resource should be assigned on <see cref="Target"/>.
+    /// </summary>
+    public IReadOnlySet<RoleDefinition> Roles { get; } = roles;
+}

src/Aspire.Hosting.Foundry/Aspire.Hosting.Foundry.csproj

@@ -23,6 +23,7 @@
   <ItemGroup>
     <Compile Include="$(RepoRoot)src\Shared\AzureRoleAssignmentUtils.cs" />
     <Compile Include="$(RepoRoot)src\Shared\ContainerRegistryInfrastructure.cs" />
+    <Compile Include="$(SharedDir)ComputeEnvironmentEndpointResolver.cs" LinkBase="Shared\ComputeEnvironmentEndpointResolver.cs" />
     <Compile Include="$(RepoRoot)src\Aspire.Hosting\Utils\FormattingHelpers.cs" Link="Utils\FormattingHelpers.cs" />
     <Compile Include="..\Shared\AzureCredentialHelper.cs" Link="AzureCredentialHelper.cs" />
     <Compile Remove="tools\**\*.cs" />

src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs

@@ -25,7 +25,10 @@ namespace Aspire.Hosting.Foundry;
 /// </summary>
 public class AzureHostedAgentResource : Resource, IResourceWithEnvironment
 {
-    private const string AzureAIUserRoleDefinitionId = "53ca6127-db72-4b80-b1b0-d745d6d5456d";
+    // The "Azure AI User" built-in role (data-plane access to Foundry agents/inference). Granted to
+    // the agent's own instance identity below, and to consumers that reference the agent (see
+    // HostedAgentResourceBuilderExtensions.GrantHostedAgentConsumerRoles).
+    internal const string AzureAIUserRoleDefinitionId = "53ca6127-db72-4b80-b1b0-d745d6d5456d";
 
     /// <summary>
     /// Creates a new instance of the <see cref="AzureHostedAgentResource"/> class.
@@ -429,8 +432,7 @@ internal static async Task<Dictionary<string, string>> GetResolvedEnvironmentVar
             throw CreateEndpointResolutionException(hostedAgent, resource, environmentVariableName, endpointReference, $"Endpoint '{endpoint.Name}' is internal. Foundry hosted agents can only reference externally exposed endpoints during publish.");
         }
 
-        var deploymentTarget = endpointReference.Resource.GetDeploymentTargetAnnotation();
-        if (deploymentTarget?.ComputeEnvironment is not { } computeEnvironment)
+        if (!ComputeEnvironmentEndpointResolver.TryGetEffectiveComputeEnvironment(endpointReference.Resource, out var computeEnvironment))
         {
             var reason = $"Resource '{endpointReference.Resource.Name}' does not have a compute environment deployment target.";
             throw CreateEndpointResolutionException(hostedAgent, resource, environmentVariableName, endpointReference, reason);