[Kayla Seager (kseager)]

Scope

1. New project, customer VNet.
2. New project, managed VNet.
   • Creates the AMPLS and private endpoint, and adds the ampls-monitor-rule outbound rule.
   • Grants the account identity the Network Connection Approver role.
   • Adds the foundry-account-pe outbound rule (account to itself), required for hosted agents.
   • If no isolation mode is set, it defaults to AllowInternetOutbound.
   • Out of scope: prompt-agent traces on managed egress. They were not observed in testing and are not claimed. Hosted-agent traces are in scope and verified.
3. BYO connection only: parity with the previous PR.
   • Covers connecting an existing App Insights component. It creates no new component for an existing project.
   • Existing-project AMPLS, private endpoint and rule creation stays out of scope and is documented.

Problem

A project with a network: block (VNet-injected agents) could not send traces: native azd monitoring created public-ingestion App Insights, and #10743 skips monitoring in that case. This PR adds a private path so agent traces arrive in App Insights and can be read from inside the network.

What azd now provisions (new project, network: with your own agent subnet, monitoring enabled)

Customer VNet
├─ agent subnet (delegated Microsoft.App/environments)   ← agent containers
└─ pe subnet
     ├─ private endpoint → Foundry account
     ├─ private endpoint → Storage (blob)
     └─ private endpoint "azuremonitor" ──┐
                                          ▼
                    Azure Monitor Private Link Scope (AMPLS)
                      ingestionAccessMode: PrivateOnly
                      queryAccessMode:     Open
                      scoped resources:
                        ├─ Application Insights   public ingestion Disabled, public query Enabled
                        └─ Log Analytics workspace public ingestion Disabled, public query Enabled

Private DNS zones linked to the VNet (Monitor):
  privatelink.monitor.azure.com, privatelink.oms.opinsights.azure.com,
  privatelink.ods.opinsights.azure.com, privatelink.agentsvc.azure-automation.net

Project connection: AppInsights, ApiKey (project-scoped, azd-appinsights-<hash>)
Project capability host (BYO egress)

Ingestion is private only. Traces are sent through the AMPLS private endpoint and the component rejects public ingestion. Query matches Foundry sample 15 (AMPLS query Open). Difference with S2 bug bash sample for VNET is that our set-up connects the App Insight/workspace to the project vs Foundry.

Component re-sync (reliability fix)

In earlier fresh environments, ingestion intermittently returned 403 Component private link id does not match incoming link for 45 minutes or more (one environment stayed stuck for hours) after ARM reported everything Succeeded. Touching the component's tags cleared it immediately.

Suspected cause: a stale routing cache. Private Link data-plane traffic is handled by internal distributed proxies (the Private Link mapping layer), which ARM does not expose. When the component is created, it registers routing metadata with no AMPLS link. Linking it through the AMPLS scoped resource updates the AMPLS side (the scopedServices table), but the proxy mapping for the component appears to be treated as a cache that is only refreshed by a modification event on the component itself. Until one arrives, the mapping can stay stale and ingestion keeps being rejected as a link-id mismatch. ARM only sees control-plane state, so it reports Succeeded while the data plane is still stale.

A second PUT on the component, even one that only changes a tag, makes ARM send a metadata sync to the underlying resource provider. That should invalidate the stale mapping and reload the link ID.

This mechanism is inferred from the symptoms. It is not confirmed by Azure Monitor or Private Link documentation, and I have not verified it with the service team. The only evidence is the live runs below.

To fix this reliably, monitoring-resync.bicep re-declares the component with identical properties after the AMPLS scoped resources exist, adding a deterministic tag azd-ampls-link (a hash of the scope ID and component name; no utcNow, so re-provision is a no-op). The project connection depends on it.

Test evidence (westus3, jump VM inside the VNet, public ingestion off)

Flow per environment: azd provision from a laptop; azd deploy and azd ai agent invoke from the jump VM; traces read privately from the VM.

Env	Build	Ingestion after provision	Deploy + invoke	Private trace read
vtrk07	no re-sync	403 for about 45 min, needed a second provision	pass	pass
vtrk08	with re-sync	accepted about 74 s after provision	pass	pass (29 rows)
vtrk09	with re-sync	accepted about 74 s after provision	not run	not run
vtrk10	with re-sync	accepted about 74 s after provision	pass	pass (34 rows)
vtrm07 (managed, AllowOnlyApprovedOutbound, head fcde87864)	with re-sync	accepted; one uninterrupted from-scratch run, no manual steps	pass	hosted agent: pass (179 traces, 49 dependencies, 18 exceptions)

Notes and limits:

• vtrk09 has ingestion evidence only. My local azd client was killed mid-run, so deploy and invoke were not run.
• Hosted-agent invokes hit the model rate limit (the fixture's gpt-4.1-mini deployment has capacity 1). Retries spaced 75 s apart produced traces. This is a fixture limit, not this PR.
• Three fresh environments with the re-sync saw no 403, against roughly 2 of 5 stuck earlier. There is no controlled run without the re-sync, so causation is not proven.
• Prompt-agent traces were confirmed on customer-VNet (BYO egress) environments. On managed egress (vtrm07) I did not observe them after two invoke rounds and a component tag touch. This is descoped from this PR: not observed, not proven to be unsupported.
• The unit tests check template shape only. Live behavior was verified by hand.

Behavior and limits

• Supported on a customer VNet (own agent subnet, BYO egress) or a managed VNet, with an azd-created component or an existing component (azd creates its own Private Link Scope, private endpoint and DNS zones and links the existing component and its workspace). Shared private DNS zones (network.dns), a VNet that already has an azuremonitor private endpoint, or a network azd cannot inspect do not block provisioning: monitoring is skipped with a warning (opt-out: monitoring.enabled: false).
• Managed egress adds two outbound private-endpoint rules and grants the account identity the Network Connection Approver role:
  • ampls-monitor-rule (target azuremonitor) lets the agent runtime reach the Private Link Scope.
  • foundry-account-pe (target account, to the account itself) is required for hosted agents. Without it they fail with Public access is disabled. Prompt agents are not affected. Writes to this rule can be slow or fail transiently; re-running azd provision is the recovery.
• Hosted agents export telemetry with their own agent identity, which exists only after deploy. On azd deploy (azd-created components on the private path only; skip with AZD_AGENT_SKIP_ROLE_ASSIGNMENTS=true), azd grants that identity Monitoring Metrics Publisher on the Application Insights component and updates a component tag so Application Insights refreshes its cached ingestion authorization (otherwise 403 for 20+ minutes). The deployer needs Owner, or User Access Administrator plus Contributor, on the component. If the grant is skipped or fails, the deploy note carries the az role assignment create command.
• A VNet can connect to only one AMPLS; a second one overrides Monitor DNS.
• With AMPLS ingestion PrivateOnly, telemetry from the VNet to Azure Monitor resources that are not in the scope is blocked.
• Users reading traces need Log Analytics Reader (plus Privileged Monitoring Data Reader if tables are protected). Because AMPLS query is Open, queries are not restricted to the private network. Verified live: private ingestion plus a read from inside the VNet, not a private-only read.

Changes

• synthesis/templates/modules/monitor-private-link.bicep: AMPLS, scoped resources, azuremonitor private endpoint, four DNS zones (create-and-link or reuse existing).
• synthesis/templates/modules/monitoring-resync.bicep (new), wired into monitoring.bicep; added to both eject module lists.
• Project capability host in resources.bicep.
• Go: private-link conflict preflight, monitoring policy for private networks, and the deploy-time hosted-agent role grant.
• Regenerated main.arm.json and existing-project.arm.json.
• Tests: TestMonitorPrivateLinkAccessModes, TestMonitoringResyncMatchesComponent, TestCheckMonitorPrivateLinkConflict, TestMonitoringKeyPolicyForPrivateNetwork, VNet requirement tests, preflight tests, hosted-agent grant tests.
• README.md and azure.ai.agents/docs/private-networking.md.

Not covered

One region. Prompt-agent traces under managed egress (descoped; not observed). Terraform parity and eject for this module follow the same shape but were not live-tested. The project-scoped connection was exercised live only in the runs above.

[azure-pipelines]

Azure Pipelines:
5 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[microsoft-github-policy-service]

Thank you for your contribution Kayla Seager (@kseager)! We will review the pull request and get back to you soon.

[Copilot]

🟡 Changes recommended

Critical gaps in private-monitoring conflict checks can disrupt shared DNS and existing telemetry, while workspace ingestion remains publicly accessible despite the private-only configuration.

9 open issues

• Skip monitoring when endpoint conflict checks are inconclusive · New
• Check conflicts before the existing-connection early return · New
• Exempt only the exact planned scope ID from conflict checks · New
• Gate monitoring creation on BYO egress · New
• Protect the Bicep deployment path from endpoint conflicts · New
• Validate shared DNS zones before binding Monitor endpoints · New
• Disable public ingestion on the workspace too · New
• Make skip warnings persistent and visible in automated runs · New
• Document VNet-wide Monitor routing impact and opt-out · New

What changed in this PR

Extends the Foundry infrastructure synthesis shared by the Projects and Agents extensions to support private Application Insights ingestion for new projects using customer-provided agent subnets.

Changes:

• Adds Azure Monitor private-link infrastructure, DNS integration, a project capability host, and an ordered component re-sync.
• Enables BYO-network monitoring with endpoint-conflict checks and private-ingestion policy validation.
• Updates embedded ARM templates, Bicep exports, tests, and networking documentation.

Extension user-contract review: blocked (23 files inspected; 0 new contract comments; 0 matched threads; review history unavailable).

File	Description
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​vnet_requirements_test.go	Checks capability-host template requirements.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​modules/​resources.bicep	Adds the project capability host and network outputs.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​modules/​monitoring.bicep	Wires private monitoring and component re-sync.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​modules/​monitoring-resync.bicep	Reapplies the component after private-link setup.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​modules/​monitor-private-link.bicep	Defines the Monitor scope, endpoint, and DNS resources.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​main.bicep	Passes network settings into monitoring.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​main.arm.json	Regenerates embedded new-project infrastructure.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​templates/​existing-project.arm.json	Regenerates the embedded monitoring module.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​synthesizer.go	Enables monitoring creation for BYO networks.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​monitoring_test.go	Updates network-specific monitoring expectations.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​monitoring_resolver.go	Applies private-network component validation.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​monitoring_private_link.go	Adds Monitor endpoint-conflict discovery.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​monitoring_private_link_test.go	Tests conflicts, template settings, and ingestion policy.
cli/​azd/​extensions/​azure.ai.projects/​synthesis/​monitoring_policy.go	Allows disabled public ingestion on private paths.
cli/​azd/​extensions/​azure.ai.projects/​README.md	Documents private monitoring behavior and limits.
cli/​azd/​extensions/​azure.ai.projects/​internal/​provisioning/​monitoring_preflight.go	Integrates private-network monitoring checks and skips.
cli/​azd/​extensions/​azure.ai.projects/​internal/​provisioning/​monitoring_preflight_test.go	Retargets the unsupported-network skip test to reuse.
cli/​azd/​extensions/​azure.ai.projects/​internal/​provisioning/​monitoring_graph.go	Applies private-network policy during graph validation.
cli/​azd/​extensions/​azure.ai.projects/​internal/​cmd/​project_existing_infra.go	Exports the new monitoring Bicep dependencies.
cli/​azd/​extensions/​azure.ai.projects/​cspell.yaml	Adds Monitor terminology to spell checking.
cli/​azd/​extensions/​azure.ai.agents/​internal/​cmd/​init_infra.go	Includes both new modules in Bicep exports.
cli/​azd/​extensions/​azure.ai.agents/​docs/​private-networking.md	Describes private monitoring support and exclusions.
cli/​azd/​extensions/​azure.ai.agents/​cspell.yaml	Adds the Azure Monitor group identifier.

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because private-monitoring safety gaps across network checks, legacy templates, and shared DNS reuse can permit public ingestion or disrupt other projects’ telemetry.

No open issues 🎉

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

The monitoring-role grant ignores the explicit opt-out, attempts assignments beyond private-network scenarios, and sends failure recovery guidance to normally discarded stderr.

4 open issues

• Avoid unnecessary role assignments for public monitoring · New
• Make failed-grant recovery guidance visible to deployers · New
• Update claims to account for deploy-time role assignment · New
• Honor the role-assignment opt-out before granting monitoring access · New

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

The monitoring gate applies RBAC and tag writes to public-network and customer-owned components, contradicting documented ownership guarantees and introducing unnecessary deployment permission requirements.

4 open issues

• Honor the role-assignment opt-out before granting monitoring access
• Update claims to account for deploy-time role assignment
• Make failed-grant recovery guidance visible to deployers
• Avoid unnecessary role assignments for public monitoring

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

Activity-only hosted agents drop failed or skipped publisher-grant warnings when no artifacts are produced, leaving successful deployments without the recovery command.

1 open issue

• Preserve publisher-grant warning when hosted agent has no artifacts · New

4 resolved since last review

• Honor the role-assignment opt-out before granting monitoring access
• Update claims to account for deploy-time role assignment
• Make failed-grant recovery guidance visible to deployers
• Avoid unnecessary role assignments for public monitoring

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

The new tests bypass the ARM tag-handling closure, leaving repeat-deployment behavior, failed-refresh recovery, and tag-update failures without coverage.

2 open issues

• Preserve publisher-grant warning when hosted agent has no artifacts
• Add coverage for ARM tag-handling and refresh-failure paths · New

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because private-network DNS conflicts and monitoring-dependent egress rules can block provisioning, disrupt existing workloads, or break hosted-agent connectivity.

No open issues 🎉

2 resolved since last review

• Preserve publisher-grant warning when hosted agent has no artifacts
• Add coverage for ARM tag-handling and refresh-failure paths

_{Review effort: Max}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because interactions among monitoring, private networking, and authorization can cause provisioning failures, hosted-agent connectivity loss, or silent permission-refresh failures.

No open issues 🎉

_{Review effort: Max}

[Zhijie Huang (hund030)]

/check-enforcer override