AzureFeeds

Enterprise teams deploying Microsoft Foundry into private networks can lose hours to failures caused not by the template itself but by surrounding operational state. Each failed deployment can cost thirty to forty-five minutes to redeploy, and residue from one attempt can block the next. 

This article introduces three tools that make private network deployments easier to operate end to end. Preflight – catches preventable failures before deployment starts. Diagnostic checks – isolate the cause when agent invocation or tool connectivity fails after a successful deployment. Cleanup – restores the environment to a clean state so redeployment can proceed without leftover platform state. 

For enterprise architects and platform teams, the operational problem is not just deployment complexity, but the hidden runtime state that private networking introduces. These tools matter because they reduce time lost to failed redeploys, shorten diagnosis when deployments appear healthy, but calls still fail, and make teardown safe enough to support repeated testing and rollout. 

What a private network Foundry deployment sets up, and where it gets fragile

A private network Foundry deployment brings together several moving parts: a Foundry account and one or more projects, an agent subnet inside a VNet delegated to Microsoft.App/environments, a Service Association Link created on that subnet by the account capability host, private endpoints for the Foundry account and other data-plane dependencies such as AI Search, Cosmos DB, and Storage, private DNS zones linked to the VNet, and role assignments that allow the project managed identity to reach each dependency over the private path. 

The main variation between deployments is which dependencies the customer brings into the architecture. Template 16 adds an existing private APIM instance so API traffic remains inside the VNet. Template 19 takes the full bring-your-own approach with customer-managed Search, Cosmos DB, and Storage resources and lets customers put tools behind vNet. 

This architecture is what makes enterprise adoption possible, but it also makes troubleshooting expensive. Any link in the chain can appear healthy in deployment output while still failing at runtime. The deployment succeeds, the portal shows no errors, and the first agent call that uses a tool fails because the relevant problem lives in runtime state the template cannot inspect. 

Preflight checks to catch preventable failures before deployment runs

The preflight script catches misconfigurations that the deployment itself cannot surface early enough to be useful: issues detectable from the inputs before any resource is created. Most of these failures interrupt deployment partway through, from an unregistered resource provider to a Bring Your Own (BYO) Cosmos account left in its default local-auth-enabled state, which prevents project capability host creation.

Preflight runs the following categories of checks against the inputs to a deployment. 

Each check exits with an explicit pass, warn, or fail. For the failures whose fix is a single command, preflight emits the exact az command, so the path from “failure surfaced” to “deployment unblocked” is one paste away. 

Diagnostic script pinpoints cause of failures after a clean deployment

The diagnostic script helps identify the root cause of failures that look identical from the agent’s point of view but can stem from different underlying issues, each requiring a different fix. 

Consider an agent that cannot reach Azure AI Search. The user sees a connection that returns no data and an error such as tool_user_error: Invalid endpoint or connection failed. The obvious next step is to inspect the Search resource, but the same symptom can come from several different underlying causes: 

1. The project’s managed identity may be missing Search Index Data Contributor or Search Service Contributor on the Search resource, so the bearer token reaches Search and Search rejects it.  


2. The project-scoped capability host may not have been created yet, or may be in a Failed provisioning state because the role assignments above had not propagated when it was attempted. 


3. The private endpoint for Search may exist and be approved, but the privatelink.search.windows.net zone may not be linked to the VNet the agent runs in, so the lookup resolves to the public IP and the network rules reject it. 

All three produce the same agent-side symptoms. Diagnostic’s RBAC, capability host, and DNS-zone checks separate them in a single run, so the next action is unambiguous. 

Diagnostic runs fifteen checks against a deployed environment. Each check exits with an explicit pass, warn, or fail. 

Cleanup unblocks a stuck redeploy 

A common failure after a teardown is that the next redeploy refuses to run. The deployment fails with SubnetIsInUseByAnotherResource, or the VNet delete fails with InUseSubnetCannotBeDeleted. The Foundry account is gone, the agent subnet shows nothing visible using it, and nothing in the portal explains why the deployment cannot move forward. 

The deployment built a dependency chain bottom-to-top: VNet, agent subnet with Microsoft.App/environments delegation, Foundry account, account capability host plus the Service Association Link it places on the subnet, project, and project capability host. Every link is pinned by the one below it, which means cleanup must unwind in the opposite order. 

The cause of the stuck-redeploy symptom is almost always an orphaned SAL left over because the chain was torn down out of order. The usual path is the team deletes the Foundry account hoping the rest will cascade, but capability host teardown and SAL release happen asynchronously on the platform side, and the soft-deleted account is never purged, so the capability host is never released and the SAL it depends on is never released either. The account is gone from the portal, but the subnet is still pinned. In this case, redeployment will fail, and resource group is blocked and cannot get deleted. 

The cleanup script exists to resolve this in one command, and it follows the exact inverse of the dependency chain created during deployment: 

1. Delete the project capability hosts: The project capability host depends on the account capability host; must be deleted first because the account capability host can’t be deleted while project capability hosts depend on it. 


2. Delete the account capability hosts: Only safe now that no project capability host depends on them. 


3. Delete the projects and purge the AI accounts: Includes handling the soft-deleted state Foundry accounts go into, so the same account name can be redeployed cleanly. 


4. Wait for SAL cleanup on the agent subnet: SAL removal is asynchronous; proceeding to delete or reuse the subnet before the SAL is gone is exactly how the SubnetIsInUseByAnotherResource error is reproduced. The wait polls the subnets it discovered from capability host properties earlier in the run, there is no API to delete a SAL directly, only the owning platform resource can release it. 


5. Optional resource group delete: Now safe because nothing platform-internal still holds the subnet. 

Each step is idempotent, so rerunning cleanup on a partially cleaned environment completes the remaining work instead of failing. A -DryRun switch prints the full plan without changing anything, which makes it the safest way to inspect the script before using it in an environment you care about. 

Private network deployments become manageable when teams treat preflight checks, deployment, diagnosis, and teardown as one operational workflow rather than isolated tasks. Used together, preflight, diagnostic, and cleanup reduce avoidable failures, make post-deployment issues easier to localize, and prevent teardown residue from blocking the next rollout. 

Next Steps 

Want to explore the tools in more detail?  

Start with the deployment-tools and the individual documentation for preflight, diagnostic, and cleanup. 

Ready to deploy?  

Start with Template 16: private network with BYO APIM or Template 19: private network with BYO agent tools, and run preflight first.