Deploy & Track
Applies to all private network deployments.
Deploy
az deployment group create \
--resource-group <rg> \
--template-file main.bicep \
--parameters main.bicepparam \
--name <deployment-name>⚠️ Capability host provisioning is asynchronous (10–20 min). The CLI produces no output during this phase.
Managed VNet — Required Post-Deploy Step
After the deployment succeeds, you must create the managed network's outbound private endpoint rules:
- A self-referencing private endpoint back to the Foundry account.
- Private endpoints to its dependent data resources.
⚠️ Without them, hosted agents fail with
500 (403: Public access is disabled)— the agent container in Microsoft's managed VNet can't reach the account privately. Prompt agents are unaffected.
The account's managed identity must hold Azure AI Enterprise Network Connection Approver so the rules auto-approve.
See the Managed VNet doc (Key Documentation) for current steps, or the template README for its specific script.
Monitor Progress
Use exponential backoff — do NOT poll every 30 seconds.
| Poll | Wait |
|---|---|
| 1st | 1 min after deploy starts |
| 2nd | 3 min after 1st |
| 3rd | 5 min after 2nd |
| 4th+ | Every 5 min |
# Overall state
az deployment group show \
--resource-group <rg> --name <deployment-name> \
--query "{state:properties.provisioningState,error:properties.error}" -o json
# Per-resource progress
az deployment operation group list \
--resource-group <rg> --name <deployment-name> \
--query "[].{resource:properties.targetResource.resourceType,state:properties.provisioningState}" -o tableOr block with timeout:
az deployment group wait \
--resource-group <rg> --name <deployment-name> \
--created --timeout 1800Error Recovery
When a deployment fails, follow this workflow:
Step 1 — Identify the error
az deployment operation group list \
--resource-group <rg> \
--name <deployment-name> \
--query "[?properties.provisioningState=='Failed'].{resource:properties.targetResource.resourceType,error:properties.statusMessage}" \
-o jsonStep 2 — Resolve
Use microsoft_docs_search with the error code or message to find current remediation. The legionservicelink retry rule is documented in the main workflow's Error Handling section.
| Error | Likely cause | Fix |
|---|---|---|
legionservicelink / subnet in use |
Capability host association still linked to the agent subnet | Use a new vnetName, or purge the account and delete the capability host, then wait for the link to clear before reusing the subnet |
AuthorizationFailed on validate/action |
Missing Contributor role | Assign Contributor + User Access Administrator to deploying identity |
SubnetDelegationAlreadyExists |
Agent subnet already delegated to another resource | Use a new VNet or open a support ticket to remove the delegation |
disableLocalAuth policy violation |
Template defaults to false |
Set disableLocalAuth: true in Bicep params |
defaultOutboundAccess policy violation |
Subnets missing the property | Add defaultOutboundAccess: false to subnet properties |
Step 3 — Present fix to user and get approval
Before re-deploying, show the user:
- What failed and why
- What file/parameter will be changed
- The new
vnetNameto use (must be different from the failed run)
Step 4 — Re-deploy with a new deployment name
# Update main.bicepparam: change vnetName to a new unique name
az deployment group create \
--resource-group <rg> \
--template-file main.bicep \
--parameters main.bicepparam \
--name <deployment-name>-retry