Repository navigation
Resolve cross-compute-environment endpoint references for Foundry hosted agents - #17756
Conversation
…ed 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>
…isleading 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>
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>
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 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>
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17756Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17756" |
There was a problem hiding this comment.
Pull request overview
This PR adds shared cross-compute-environment endpoint resolution so ACA, App Service, and Kubernetes publishers can resolve references to Foundry hosted agents owned by another compute environment.
Changes:
- Adds
ComputeEnvironmentEndpointResolverand wires it into ACA, App Service, Kubernetes, Foundry, and Front Door flows. - Adds Foundry project endpoint-property handling for hosted agent URLs.
- Adds unit and publisher regression tests with snapshots for ACA, App Service, and AKS scenarios.
Show a summary per file
| File | Description |
|---|---|
src/Shared/ComputeEnvironmentEndpointResolver.cs |
Adds shared helper for delegated endpoint resolution. |
src/Aspire.Hosting.Azure.AppContainers/BaseContainerAppContext.cs |
Uses helper before local ACA endpoint lookup. |
src/Aspire.Hosting.Azure.AppContainers/Aspire.Hosting.Azure.AppContainers.csproj |
Links shared resolver. |
src/Aspire.Hosting.Azure.AppService/AzureAppServiceWebsiteContext.cs |
Uses helper before local App Service endpoint lookup. |
src/Aspire.Hosting.Azure.AppService/Aspire.Hosting.Azure.AppService.csproj |
Links shared resolver. |
src/Aspire.Hosting.Kubernetes/KubernetesResource.cs |
Uses helper before local Kubernetes endpoint lookup. |
src/Aspire.Hosting.Kubernetes/Aspire.Hosting.Kubernetes.csproj |
Links shared resolver. |
src/Aspire.Hosting.Foundry/Project/ProjectResource.cs |
Adds Foundry endpoint property override. |
src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs |
Reuses shared effective-compute-environment lookup. |
src/Aspire.Hosting.Foundry/Aspire.Hosting.Foundry.csproj |
Links shared resolver. |
src/Aspire.Hosting.Azure.FrontDoor/AzureFrontDoorExtensions.cs |
Reuses shared effective-compute-environment lookup. |
src/Aspire.Hosting.Azure.FrontDoor/Aspire.Hosting.Azure.FrontDoor.csproj |
Links shared resolver. |
tests/Aspire.Hosting.Tests/ComputeEnvironmentEndpointResolverTests.cs |
Adds unit coverage for helper behavior. |
tests/Aspire.Hosting.Tests/Aspire.Hosting.Tests.csproj |
Links shared resolver into tests. |
tests/Aspire.Hosting.Azure.Tests/AzureContainerAppsTests.cs |
Adds ACA regression test. |
tests/Aspire.Hosting.Azure.Tests/AzureAppServiceTests.cs |
Adds App Service regression test. |
tests/Aspire.Hosting.Azure.Kubernetes.Tests/AzureKubernetesFoundryReferenceTests.cs |
Adds AKS/Kubernetes regression test. |
tests/Aspire.Hosting.Azure.Tests/Snapshots/AzureContainerAppsTests.EndpointReferenceToFoundryHostedAgentIsResolvedAcrossComputeEnvironments.verified.json |
Adds ACA snapshot manifest. |
tests/Aspire.Hosting.Azure.Tests/Snapshots/AzureContainerAppsTests.EndpointReferenceToFoundryHostedAgentIsResolvedAcrossComputeEnvironments.verified.bicep |
Adds ACA generated Bicep snapshot. |
tests/Aspire.Hosting.Azure.Tests/Snapshots/AzureAppServiceTests.EndpointReferenceToFoundryHostedAgentIsResolvedAcrossComputeEnvironments.verified.json |
Adds App Service snapshot manifest. |
tests/Aspire.Hosting.Azure.Tests/Snapshots/AzureAppServiceTests.EndpointReferenceToFoundryHostedAgentIsResolvedAcrossComputeEnvironments.verified.bicep |
Adds App Service generated Bicep snapshot. |
Copilot's findings
- Files reviewed: 21/21 changed files
- Comments generated: 1
PR Testing Report — End-to-End Azure DeployPR Information
CLI Version Verification
ScenarioReal end-to-end Azure deploy of a TypeScript AppHost exercising the exact bug class the PR fixes: an Azure App Service web frontend (
Result: ✅ Fix VERIFIED (cross-env resolution works end-to-end)Before this PR, the cross-environment reference threw the "compute environment context not found" error during deploy and the pipeline never reached provisioning (#17749). With the PR build:
Downstream blocker (separate from this PR's fix)The deploy did not fully complete. The final Root cause: the app-setting key inherits the hyphen from the referenced resource name This is a pre-existing App Service limitation, independent of the cross-env resolution fix — any reference (same-env or cross-env) to a hyphenated resource name on App Service hits it. The repo already has a guard for it: Gap worth a follow-upThat early validation did not catch the cross-environment-generated Workaround for a fully green runRename the hosted-agent resource to be dash-free (e.g. Summary
Overall✅ PR #17756 VERIFIED for its stated scope — cross-compute-environment endpoint references now resolve correctly during |
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>
|
/deployment-tests |
|
/deployment-test |
|
🚀 Deployment tests starting on PR #17756... This will deploy to real Azure infrastructure. Results will be posted here when complete. |
|
❌ Deployment E2E Tests failed — 36 passed, 4 failed, 0 cancelled View test results and recordings
|
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>
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>
James Newton-King (JamesNK)
left a comment
There was a problem hiding this comment.
Looks good. However, I'm not an expert in this area.
A SME in deployment should double check if there is time.
| /// This mirrors the inverse-direction logic used by Foundry hosted agents when they reference | ||
| /// endpoints owned by App Service/ACA/Kubernetes resources. | ||
| /// </remarks> | ||
| internal static class ComputeEnvironmentEndpointResolver |
There was a problem hiding this comment.
Will everyone building hosting/deploy integrations require code like this? Would this be made public sometime in the future?
I want to make sure the design holds up beyond our own bits.
There was a problem hiding this comment.
We have a public API, this makes that public API a little less verbose.
| /// </para> | ||
| /// </remarks> | ||
| [Experimental("ASPIREAZURE003", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")] | ||
| public sealed class ReferenceRoleAssignmentAnnotation(AzureProvisioningResource target, IReadOnlySet<RoleDefinition> roles) : IResourceAnnotation |
There was a problem hiding this comment.
nit: DebuggerDisplay
Most annotations have a DebuggerDisplay. Add one?
(might not be true for annotations in integrations/hosting. Could be fixed up in the future)
| /// <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; |
There was a problem hiding this comment.
Double checking that order will never matter.
RoleDefinition is a record so it should override methods needed for working well in a hash set. Are there tests that exercise this?
| // So the minimal, least-privilege grant for a pure agent consumer is "Azure AI User" alone. | ||
| var roles = new HashSet<RoleDefinition> | ||
| { | ||
| new(AzureHostedAgentResource.AzureAIUserRoleDefinitionId, "Azure AI User") |
There was a problem hiding this comment.
Does this string have to be "Azure AI User", or is it our description? A comment confirming/denying would be useful.
|
Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
|
|
Will follow up on the comments. This is for BUILD. Mitch Denny (@mitchdenny) 4 deployment tests were failing but unrelated to these changes. |
|
❓ CLI E2E Tests unknown — 110 passed, 0 failed, 2 unknown (commit View all recordings
📹 Recordings uploaded automatically from CI run #26729041681 |
|
Pull request created: #1143
|
|
📝 Documentation has been drafted in microsoft/aspire.dev#1143 targeting Drafted docs PR covering two user-facing changes from this PR:
Note This draft PR needs human review before merging. |
Description
This PR fixes two related gaps that surface when a Foundry hosted agent is referenced from a resource deployed to a different compute environment (#17749). Each is independently useful, but together they make the reported scenario deploy and run end-to-end with no manual steps.
1. Cross-compute-environment endpoint resolution
aspire deployfailed when a resource referenced (viaWithReference()) an endpoint whose owning resource was deployed to a different compute environment. Each publisher resolved endpoint references against its local endpoint map, which doesn't contain a resource owned by another environment, so resolution threw a "context not found" error and deployment broke.This isn't specific to one resource type or one environment. The bug affected cross-environment endpoint references in general — across the Azure Container Apps (ACA), Azure App Service, and Kubernetes (AKS) publishers — and the referenced resource can be any resource with endpoints (a Foundry hosted agent referenced from a different environment was just the originally reported repro from #17749).
This change teaches the publishers to detect when a referenced endpoint's owning resource lives in a different compute environment and to delegate endpoint resolution to that owning environment instead of failing against the local map. Same-environment references are unaffected and continue to resolve locally, so existing generated artifacts (bicep/manifests) stay byte-for-byte unchanged.
The fix is entirely publisher-side: it runs at publish/deploy time against the already-resolved application model, so it applies regardless of how the cross-environment reference was introduced into the model. Resolution is implemented in C#, but because it operates on the resolved model it applies equally to C# and TypeScript AppHosts — a TypeScript AppHost that wires the same cross-environment reference benefits from the fix without any TypeScript-side changes.
The shared logic lives in a new internal helper,
ComputeEnvironmentEndpointResolver, which the ACA, App Service, and Kubernetes publishers now call. The Foundry hosted agent resource and the previously bespoke Azure Front Door cross-environment handling were refactored onto the same helper so there is a single resolution path.2. RBAC auto-wiring for hosted-agent consumers
Even after endpoint resolution succeeded, the deployed consumer could not actually call the hosted agent: invoking a Foundry hosted agent requires the caller to authenticate with a managed identity that holds the Azure AI User role on the owning Foundry account. Previously the app model emitted neither the identity nor the role assignment for a consumer that only referenced the agent's node app, so the developer had to run two manual
az role assignment create/ identity steps after every deploy.The blocker is structural:
AzureResourcePreparerdiscovers role targets by walking a resource's direct dependencies and acting on the ones that are themselvesIAzureResource. A consumer that references a hosted agent references the agent's node app (a plain compute resource), and the owning Foundry account is only a transitive dependency behind it — so the preparer's walk never reaches the account and no identity/role is wired.This PR closes that gap with a small, sanctioned hook rather than bespoke per-resource logic:
ReferenceRoleAssignmentAnnotation([Experimental("ASPIREAZURE003")]), expresses "this resource implies these roles on that Azure resource". It is the redirect that the dependency walk cannot derive on its own.AzureResourcePreparernow honors that annotation as a first-class input alongside the existingRoleAssignmentAnnotationpath (RunMode → global role assignments; PublishMode → an explicit role-assignment annotation on the consumer), and de-duplicates roles per target so generated bicep contains no duplicate role-assignment identifiers.WithRoleAssignments(...)still suppresses them.The net effect: referencing a hosted agent now auto-provisions the consumer's managed identity and grants Azure AI User on the Foundry account, eliminating the two manual post-deploy steps.
User-facing usage
A service deployed to one compute environment (here, Azure Kubernetes) can now reference a hosted agent hosted in another (the Foundry project environment) and both deploy and invoke it successfully, with the required identity and role assignment generated automatically. This works for both C# and TypeScript AppHosts.
C# AppHost:
TypeScript AppHost:
Fixes #17749
Validation
ComputeEnvironmentEndpointResolverTests(7 tests) covering each observable branch of the helper: cross-environment delegation (both theEndpointReferenceandEndpointReferenceExpressionoverloads), same-environment via deployment target, binding-backstop, no-environment, bound multi-target (no throw), and unbound multi-target (throws).AzureResourcePreparerTestscoverage for the RBAC hook: thatReferenceRoleAssignmentAnnotationproduces the implied identity + role assignment in both Run and Publish modes, that roles are de-duplicated per target, and that the hosted-agent consumer is granted only Azure AI User (account defaults are not silently folded in, and explicitWithRoleAssignmentssuppression is honored).HostedAgentExtensionTestsasserting the consumer stamps the single least-privilege Azure AI User role.agentweb→apiservice→ Foundry hosted agent) returns real agent responses with no manual role-assignment steps — the consumer's managed identity and Azure AI User grant are emitted by the app model.Checklist
ReferenceRoleAssignmentAnnotationinAspire.Hosting.Azure, gated behind[Experimental("ASPIREAZURE003")].<remarks />and<code />elements on your triple slash comments?WithRoleAssignments(...). No other roles or defaults are folded in.