Skip to content

Deploy infra only with Bicep

Objective

Provision the Azure foundation without building or deploying application images. Use the Agent Landing Zone repository and its infra/ source, including when no Agent Application images will be deployed. Bicep is the default infrastructure provider. For Terraform, use Deploy infra only with Terraform.

When to use

Use this guide when you need foundation resources first, or will supply your own application. To deploy the Agent Application now, use the Deploy full stack guide.

Prerequisites

Complete the permissions and tooling prerequisites. The deployment requires Git, Azure CLI, azd, PowerShell 7, Python and the platform hook dependencies. Review the resource inventory and cost scenarios and regional capacity caveats. Infrastructure-only still creates billable resources.

Blocks marked bash use Bash syntax. In PowerShell, put commands with a trailing backslash (\) on one line and remove the continuation backslashes. Replace every <placeholder> before running a command.

The effective footprint is the combination of enabled services, resource-reuse inputs, application definition, orchestrator topology and network settings. This determines which AI services, backing resources, runtimes, data stores, monitoring, networking and optional add-ons are deployed. Review the root main.parameters.json, Bicep conditions and preview to identify the resources for your deployment.

Procedure

Step 1: Initialize Agent Landing Zone

Create a new, empty project directory, outside any existing checkout:

mkdir agent-landing-zone
cd agent-landing-zone
azd init --template Azure/agent-landing-zone .

The trailing . initializes the current directory rather than creating a template-named subdirectory. Interactive init asks for the environment name and creates/selects it; do not create it again in Step 2. To supply the name explicitly, use azd init --template Azure/agent-landing-zone --environment <environment-name> . instead of the init command above. Initialization does not provision resources; leave --up off until the required choices have been configured.

Run all lifecycle commands from this root, not from infra/. Its infra/ contains the foundation source. manifest.json records the coordinated application component pins. The template's root azure.yaml already selects Bicep; no upstream platform Git history is needed.

Set up Python from the initialized project before lifecycle commands.

Step 2: Select and confirm the target

Use the dedicated environment created in Step 1. Replace the placeholders:

az login
azd auth login
az account set --subscription <subscription-id>
azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
azd env set AZURE_RESOURCE_GROUP <dedicated-resource-group>
azd env set AZURE_LOCATION <region>

Use azd env select <environment-name> to resume an existing local environment and keep its approved inputs; do not reinitialize the template.

Use separate environment, resource-group, identity, configuration and data boundaries for each stage; protect local .azure/ state. Fork or mirror the source only when maintaining your own inputs or automation.

The Bicep deployment through azd uses three resource groups by default:

Group What it contains Default name
Foundry Foundry and its related resources The AZURE_RESOURCE_GROUP name you set above
Application The selected application's services and data resources The same name with -app added
Network Workload networking and private connectivity resources The same name with -network added

For example, choosing rg-agent-dev above gives you rg-agent-dev, rg-agent-dev-app and rg-agent-dev-network.

The deployment scripts, also called hooks, create missing application and network groups. The identity running deployment needs permission to create them. If an administrator creates those groups in advance, set CREATE_RESOURCE_GROUPS=false so the scripts do not create groups.

To use different group names or combine resources into one or two groups, set the resource group destinations before first provision.

Run one azd provision command from the repository root to deploy across all three groups. Do not run a separate deployment for each group. These instructions apply to this Bicep procedure. The integrated Terraform deployment guide uses the same product lifecycle and root parameter source, with separate backend settings. The portal has its own deployment procedure.

Step 3: Choose the network setup

For production and workloads with sensitive data, use private service endpoints. Choose a self-contained private network or connect the workload's private network to an existing corporate hub. Both options are described below.

The template currently defaults to NETWORK_ISOLATION=false. Set it to true explicitly for a private deployment; the template default is not the recommended production configuration.

Use azd env set for the individual settings shown below. For example, azd env set NETWORK_ISOLATION true selects private networking for the selected environment.

Settings containing a list of values or a group of related fields, such as allowed IP ranges or the network address plan, go in the root main.parameters.json file. See Existing networks, private DNS and parameter files below for details.

DEPLOYMENT_MODE identifies the network design, but does not configure routing, DNS or isolation by itself. Configure those through the settings for your chosen approach below. ORCHESTRATION_HOST selects hosted or container_apps; APPLICATION_MODE selects conversational, workflow or both. See Deployment inputs for input formats and generated files.

Private standalone network

Choose this when your workload team will manage its own network, private DNS and outbound firewall rather than use shared hub services.

azd env set NETWORK_ISOLATION true
azd env set DEPLOYMENT_MODE standalone
azd env set DEPLOY_AZURE_FIREWALL true
azd env set DEPLOY_JUMPBOX true
azd env set DEPLOY_BASTION true
azd env set DEPLOY_NAT_GATEWAY true

Review the standalone reference for nonoverlapping subnets, network security groups (NSGs), outbound routing and private DNS. For native Bastion Remote Desktop Protocol (RDP), choose BASTION_SKU_NAME=Standard and BASTION_ENABLE_TUNNELING=true; portal access does not require the native tunneling workflow. Have a connected host ready for Agent post-provision configuration, or use explicit deferral below.

Private spoke using an existing hub

Choose this when your organization already provides shared networking services. The workload gets its own private network, called a spoke, connected to that shared hub.

Agree hub routing, reverse peering, DNS and permissions with their owners first. For a new spoke VNet with a hub firewall:

azd env set NETWORK_ISOLATION true
azd env set DEPLOYMENT_MODE ailz-integrated
azd env set DEPLOY_AZURE_FIREWALL false
azd env set DEPLOY_BASTION false
azd env set DEPLOY_NAT_GATEWAY false
azd env set DEPLOY_JUMPBOX true
azd env set EXISTING_BASTION_RESOURCE_ID <hub-bastion-resource-id>
azd env set HUB_INTEGRATION_HUB_VNET_RESOURCE_ID <hub-vnet-resource-id>
azd env set HUB_INTEGRATION_CREATE_HUB_PEERING true
azd env set HUB_INTEGRATION_EGRESS_NEXT_HOP_IP <hub-firewall-private-ip>

Instead of a next-hop IP, a platform-managed route table can be selected with HUB_INTEGRATION_EXISTING_ROUTE_TABLE_RESOURCE_ID; these inputs are mutually exclusive. Set one when hub egress is required. Shared monitoring uses EXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID and, when applicable, EXISTING_APPLICATION_INSIGHTS_RESOURCE_ID with its protected connection string.

Apply the hub-and-spoke DNS and peering contract before provisioning. A network operator may need to complete reverse peering and DNS links as soon as a fresh spoke VNet exists, before bootstrap can finish. Use an existing, approved production hub with its network and DNS owners.

Public service endpoints

Use this option only for an organization-approved, short-lived evaluation or demonstration with synthetic or non-sensitive data, when private connectivity is not available. It is not the recommended production setup.

The commands below select public service endpoints, not private networking. Authentication and authorization are still required, but they do not prevent network access to those public endpoints or make them private.

Use a separate test environment. Do not disable isolation on an existing private environment to fix a deployment or connectivity failure.

azd env set NETWORK_ISOLATION false
azd env set DEPLOYMENT_MODE standalone

Existing networks, private DNS and parameter files

Choice Required review
Existing VNet Choose subnet ownership and apply the matching inputs. Both peering directions are externally managed for BYO VNet
Shared private DNS Supply the applicable EXISTING_PRIVATE_DNS_ZONE_*_RESOURCE_ID inputs. Their owner supplies VNet links or resolver forwarding; peering alone does not propagate DNS
Azure Policy-managed DNS Use POLICY_MANAGED_PRIVATE_DNS=true instead of BYO zone overrides and agree who creates zone groups, records and links
Approved public exception Review native allowedIpRanges and Storage trusted-service/resource-instance exceptions to confirm the approved service-specific public access
Controlled public frontend Review Application Gateway ingress, certificate ownership, WAF policy and cost before opting in

Use azd env set for settings documented as environment variables that take one value, such as NETWORK_ISOLATION. Put settings containing lists or groups of related fields, such as the complete address plan, allowedIpRanges, Storage controls and publicIngress, in the reviewed root main.parameters.json.

Platform hooks regenerate the tracked Bicep seed infra/bicep/main.parameters.json; do not edit that generated copy or commit resolved environment values. The parameter reference describes foundation inputs; Deployment settings describes platform composition and overrides.

Bind the future application

Choose the orchestrator topology and ingestion selection now, even if images will be deployed later. For a different application:

azd env set AGENTLZ_APP_DEFINITION <path-to-app-definition.json>

Otherwise use the Agent Application definition. The first provision binds the environment to its application ID; a different ID requires a new environment. Preserve the existing layout and ingestion selection during recovery.

The defaults are ORCHESTRATION_HOST=hosted and APPLICATION_MODE=conversational, with the UI included automatically and Agent App Ingestion off. History, feedback and attachments default to off; workflow or both requires UI metadata regardless of those flags. Set HOSTED_AGENT_RESOURCE_SCOPE for Hosted to the approved delegated Foundry audience followed by /.default before provisioning, even when application deployment will happen later. See the linked full-stack guide for identity inputs, downstream consent and protected-retrieval acceptance.

Step 4: Preview and provision

Review component egress

With the prepared Python environment and intended application/component selection, review the local, read-only declaration plan:

python -m config.deployment.egress --plan --environment <environment-name>

This requires no Azure access and does not run preparation hooks or create groups. Review the policy ownership, selected components, destinations and purposes before approving provisioning.

Once infrastructure exists and the local outputs are current, inspect the resolved plan without applying changes:

python -m config.deployment.egress --review --environment <environment-name>

For a managed firewall this reports proposed additions, updates and removals. An external policy remains report-only and needs its owner's action. A fresh deployment cannot resolve workload subnet prefixes before provision. See the ownership and scope contract.

After approved declaration or selection changes, run the selected provider's normal provisioning sequence before deploying. It saves the environment's plan and reconciles authorized owned rules. Keep the same binding and inputs.

First run azd hooks run preup to validate the definition and binding before azd's resource-group initialization. Normal azd provision automatically runs the Agent preprovision hook to compose parameters and bootstrap authorized additional groups. Manual preparation is needed only if you choose to preview first.

Optional preview

Preview preparation can create resource groups

With azd 1.37.1, azd provision --preview does not run preprovision hooks. It reads the existing infra/bicep/main.parameters.json, which may still be the checked-in seed or another environment's composition, and cannot bootstrap missing additional destination groups.

Before an optional preview, select the intended azd environment, activate the prepared Python environment and run one matching hook from the platform root: pwsh -File scripts/preProvision.ps1 on Windows, or sh scripts/preProvision.sh on Linux/macOS. These hooks load selected azd values, compose parameters and can create missing additional groups when CREATE_RESOURCE_GROUPS=true. Otherwise those groups must already exist, or a composed split-group preview can fail with NotFound.

Native preview can also create the empty Foundry/root resource group. Neither fresh-environment preparation nor preview is guaranteed write-free; authorize group creation before running them. A successful preview does not prove private connectivity, service configuration or application readiness.

After this preparation, the optional preview command is:

azd provision --preview

If previewing, review its scopes, names, routes, resource changes, public access and role assignments. Resolve quota, Policy, subnet and capacity findings rather than skipping preflight.

Provision

With the resource changes approved, provision normally:

azd provision

Test connectivity after provisioning and application behavior after deploying your selected application.

Provisioning completes validation and binding, foundation deployment, then service configuration, role reconciliation and selected runtime publication unless explicitly deferred. It does not build or deploy application images.

Selected Container Apps can run placeholder images at this point. A placeholder response checks basic network and runtime reachability. Validate sign-in, tools, ingestion and document authorization after deploying the Agent Application. For initial infrastructure provisioning, inspect platform outputs below and continue to Validation. Use lifecycle tasks only when needed.

Platform outputs

Deployment discovery uses the native DEPLOYMENT_METADATA output. Hooks read the selected successful Bicep deployment and verify its original inputs, application/group bindings and live resource destinations before configuration. The executor needs deployment-output and selected ARM/identity read permissions, plus each selected operation's existing configuration permissions. See metadata recovery.

Custom applications can omit the store using runtime configuration mode. Required selected service setup still runs. This does not change the bundled application or sample runtime prerequisites.

In appConfig mode, after configuration completes, App Configuration publishes the JSON AGENTLZ_PLATFORM_OUTPUTS and matching flat keys under label agent-lz. Search and Cosmos sections are omitted when their endpoints are absent; other required fields must validate. These derived keys are not written back to the azd environment.

Flat key JSON path
AGENTLZ_FOUNDRY_PROJECT_ENDPOINT foundry.projectEndpoint
AGENTLZ_FOUNDRY_ACCOUNT_NAME foundry.accountName
AGENTLZ_ACR_LOGIN_SERVER registry.loginServer
AGENTLZ_APPCONFIG_ENDPOINT appConfig.endpoint
AGENTLZ_SEARCH_ENDPOINT search.endpoint
AGENTLZ_STORAGE_BLOB_ENDPOINT storage.blobEndpoint
AGENTLZ_COSMOS_ENDPOINT cosmos.endpoint
AGENTLZ_KEYVAULT_URI keyVault.uri

AGENTLZ_NETWORK_ISOLATED records isolation. AGENTLZ_IDENTITY_<COMPONENT>_CLIENT_ID and the JSON identities array contain discovered Container App identity client IDs, not principal IDs. Hosted runtime identities are created later, during application deployment. Missing or ambiguous identities fail publication; system-assigned identity resolution also requires the exact Entra service-principal read. AGENTLZ_COMPONENT_IDENTITIES is an explicit override input, not an automatic output.

az appconfig kv show --endpoint <app-configuration-endpoint> \
  --key AGENTLZ_PLATFORM_OUTPUTS --label agent-lz --auth-mode login

If only output publication needs refreshing after successful configuration:

azd env refresh
python -m config.deployment.outputs

This does not replace deferred or failed service configuration.

Access the jumpbox

Use Azure Bastion's portal connection to the deployed Windows VM. Unless overridden, its administrator username is testvmuser. The password comes from the secure vmAdminPassword provisioning input, not a documented Key Vault secret. Missing credentials need an authorized administrator's approved reset procedure. Never expose passwords in shell history or logs.

Install the deployment prerequisites. Docker is not installed by default and is unnecessary for ACR Task pool builds. The VM's managed identity still needs the required scoped configuration/build roles. Hosted authoring requires Foundry User on the exact project and account read access, not broader subscription or resource-group Owner. Allow new grants to propagate.

Then continue with the same-environment procedure below. For Terraform, preserve its additional records through deferred private configuration.

Complete a deferred post-provision

Private configuration can be explicitly deferred by RUN_FROM_JUMPBOX=false, or by AZURE_SKIP_NETWORK_ISOLATION_WARNING=true when RUN_FROM_JUMPBOX is not truthy. Set the approved deferral before the first provision when the connected host does not exist yet. Successful provisioning then reports that application setup is incomplete. Deferral does not bypass earlier topology/private-service checks.

On a new connected host, restore the same reviewed source revision and root parameter file. Install the prerequisites and Python dependencies and authenticate both CLIs. If that environment's local state is absent, create it once with azd env new <same-environment-name>; if template initialization already created it, use azd env select <same-environment-name> instead. Then set the existing target and refresh outputs:

azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
azd env set AZURE_RESOURCE_GROUP <existing-resource-group>
azd env set AZURE_LOCATION <region>
azd env refresh

Reapply the approved deployment inputs: refresh restores outputs, not your full configuration.

For the multi-group path, restore the same approved application/network destination mapping as well; the root group alone is not sufficient. Securely restore .azure/<same-environment-name>/resource-groups.json from that environment's original host before running its hooks. Output refresh does not recreate this immutable destination binding; do not generate or edit a replacement to bypass the check.

Do not publish or copy another stage's .azure/ state as an input artifact. An authorized runner can use managed-identity sign-in. Verify its scoped configuration and build roles before running the hooks.

From the connected host, clear deferral and finish configuration:

azd env set RUN_FROM_JUMPBOX true
azd env set AZURE_SKIP_NETWORK_ISOLATION_WARNING false
azd hooks run postprovision

RUN_FROM_JUMPBOX requests connectivity checks on the connected host. Verify platform outputs and required data-plane access before deploying. Private native Blob sources can require an administrator to approve the exact Search shared private-link request reported by the readiness gate. Do not approve every pending connection or bypass the gate.

Review infrastructure changes

Record the approved inputs, outputs and resource ownership, and back up required data and configuration. Before applying resource changes, follow selected-environment preparation and review the provisioning preview.

Retry a failed installation with the same approved revision and environment after repairing the specific failure. Do not delete data, rename subnets, move resources to another region, weaken isolation or bypass preflight to recover. Resource deletion and permission cleanup require separate approval.

Add an application later

Deploy the same bound application and selected components. Follow Step 4 of the full-stack deployment guide: run azd deploy from the configured foundation. Deployment automatically prepares the hosted image and its handoff; no second provision is required. Custom definitions follow their own component contract.

Optional PostgreSQL before first provision

For a fresh custom consumer, choose Basic dedicated ACA NAT/restricted public PG or isolated PE/DNS, then supply the explicit Entra admin. Follow Optional PostgreSQL for inputs/defaults, operator access and manual OID-bound schema CRUD. No bundled runtime/NL2SQL/Cosmos migration occurs.

Preserve .azure/<environment>/postgresql-binding.json. Protection/readback precedes additive discovery; same-binding recovery is supported. Retrofit, disable and immutable replacement/down are blocked, including Terraform state-scoped destruction. The independent lock is outside both provider graphs. Review backups/exact ownership before separately approved removal. Privileged bypass and the pre-lock partial-provision window remain risks.

Remove the foundation

Use the safe environment removal procedure from the selected source root and environment. Confirm ownership and backups before deletion. For a spoke, have network/DNS owners remove only the recorded spoke-specific attachments and preserve shared services. Purge is a separate irreversible decision, not a normal retry or rollback.

Validation

  1. Inspect the selected target and inventory:

    azd env get-value AZURE_SUBSCRIPTION_ID
    azd env get-value AZURE_RESOURCE_GROUP
    az resource list -g <resource-group> --query "[].{name:name,type:type}" -o table
    az network private-endpoint list -g <resource-group> \
      --query "[].{name:name,state:provisioningState,connections:privateLinkServiceConnections[].privateLinkServiceConnectionState.status}" -o json
    

    For the multi-group path, repeat resource inventory for every distinct destination, and inspect private endpoints in their actual group. Do not infer a Foundry or network resource's group from the application group.

  2. Compare the inventory with enabled features and reuse inputs. Account for both new and reused resources.

  3. For private deployments, verify approved connections, private DNS and TCP/TLS reachability from the actual deployment host. Use the standalone checks or hub checks.
  4. Test required service operations with the authorized configuration identity and confirm telemetry reaches the intended workspace.
  5. Inspect post-provision logs and platform outputs. Record explicit deferral or any logged configuration failure as incomplete. A placeholder HTTP response does not prove application readiness.

Rollback

  1. Stop retries and record which resources and configuration changed. If only local inputs changed, restore reviewed inputs before provisioning.
  2. Compare previous inputs with deployed state. Preview the previous compatible source and parameters with azd provision --preview from the selected root, following the Agent preview preparation when applicable.
  3. Apply with azd provision only if reviewed changes preserve data, shared resources and the approved network posture.
  4. Repeat Validation. If inputs cannot safely reverse a change, stop and arrange service-specific forward repair or recovery with its owner.

Successful provisioning does not restore deleted data or reverse schema changes. Disabling a flag does not delete resources or revoke grants. Use the separately authorized removal procedure only for intentional retirement, not as a retry.

© 2026 Azure AI Landing Zones