Skip to content

Deployment settings

Use this reference to configure provisioning with Bicep or Terraform. Deployment choices explains the decisions and Network design explains connectivity. For commands and execution order, choose a deployment guide.

Application resource requirements remain here because they affect provisioning. Functional behavior, effective runtime values and reloads belong in Agent Application and Application settings. Read individual nonsecret keys rather than dumping whole environments.

Deployment inputs

Kind Where it belongs How to use it
Mapped environment input The selected azd environment. Use the documented variable name. Tables below give its default or condition.
Native root parameter parameters.<name>.value in root main.parameters.json. Use typed JSON. A native parameter does not automatically have an environment mapping.
Generated provider input Bicep's infra/bicep/main.parameters.json or Terraform's infra/terraform/main.tfvars.json. Read for diagnosis, never edit resolved values as the source of a change.
Generated metadata or script state Native provider outputs or workflow-owned local records. Let the owning workflow produce it. App Configuration is not deployment discovery authority. See generated values.
Application runtime setting Normally App Configuration under agent-lz. Follow its application guide, including ownership and reload requirements.

Both providers resolve the root inputs before provision. Bicep's tracked seed is regenerated by the hooks. Terraform's input is ignored by Git. Its ignored infra/shared/main.parameters.json is a preflight diagnostic artifact, never a Terraform deployment input. Do not edit or commit resolved values in these files or generated .azure/ inputs.

Keep booleans, numbers, arrays and objects as their native JSON types. For example, the root parameter allowedIpRanges takes an array. There is no implied ALLOWED_IP_RANGES environment binding. Retain the same reviewed root document on every authorized runner.

Keep four authorities separate: declared inputs select the deployment, provider DEPLOYMENT_METADATA identifies its evaluated resources, runtime settings configure the application, and Key Vault holds secret values. Runtime settings and cached azd output aliases cannot redirect deployment resource or identity bindings.

Initialization and setting order

For a new installation, initialize a project with azd in a new empty directory. Init creates/selects the environment; do not create it again with azd env new. Run subsequent commands from the directory containing root azure.yaml, manifest.json and main.parameters.json.

Before azd provision, select the infrastructure provider in root azure.yaml, confirm the environment's subscription/region and set the documented deployment inputs and typed root parameters. Terraform also needs its existing remote-state backend configured first. After provisioning and required identity/service configuration, use azd deploy for the application. Do not use init's --up shortcut before these choices are ready.

The lifecycle inputs ENABLE_CHAT_HISTORY, ENABLE_USER_FEEDBACK and ENABLE_PRIVATE_ATTACHMENTS have verified azd env set mappings. Set them before provision so the lifecycle includes their metadata resources and grants, then deploy. Do not enable them solely by editing App Configuration or additionalAppConfigurationSettings. See Enable a product feature.

Functional keys such as SEARCH_RETRIEVAL_ENABLED, FOUNDRY_IQ_ENABLED and MULTIMODAL_ENABLED instead require explicit declarations in parameters.additionalAppConfigurationSettings.value in root main.parameters.json, using name, a string value and label agent-lz. Keep existing entries and update or append the intended keys; there is no implied same-named azd input. Follow the capability's requirements and configuration procedure before provisioning and deploying it.

Terraform backend settings

Use an existing Azure Storage account and container outside every workload resource group. Backend settings are separate from workload parameters:

Variable Required value or default
TF_STATE_RESOURCE_GROUP Backend storage account's resource group
TF_STATE_STORAGE_ACCOUNT Existing storage account name
TF_STATE_CONTAINER Existing state container name
TF_STATE_SUBSCRIPTION_ID Defaults to AZURE_SUBSCRIPTION_ID
ARM_ENVIRONMENT Canonical public, usgovernment or china; qualified from CLI metadata or explicitly selected for process credentials

The state key is agent-landing-zone/${AZURE_ENV_NAME}.tfstate. AzureAD Blob authentication requires account Reader for metadata and container Storage Blob Data Contributor. The workload does not bootstrap the backend or include it in azd down.

Native azd disables state locking. Shared and production environments require one authorized writer with queued, non-canceling execution per actual state identity. This is an access/execution control, not backend locking. See the single-writer policy. Follow backend preparation for setup commands.

The adapter records the backend binding on first use before persisting its settings and verifies it thereafter. A clean runner needs the original private backend, group and application/environment records, not reconstructed files. The provider selected in root azure.yaml applies to the checkout, not independently to each azd environment.

Azure cloud

The adapter generates the azureCloud context and passes the canonical ARM_ENVIRONMENT into the backend:

Cloud Storage DNS suffix
public core.windows.net
usgovernment core.usgovcloudapi.net
china core.chinacloudapi.cn

CLI authentication must match the selected subscription and active CLI cloud. Process credentials require an explicit cloud; any azd-store and process values must agree. Preprovision persists the qualified cloud before native backend initialization. The hooks do not change global cloud or authentication settings.

Environment boundaries

DEV, TEST and PROD need separate azd environments and resource groups. Separate subscriptions strengthen administrative and quota boundaries. Permissions, identities and dedicated stores enforce the following boundaries.

Boundary Keep separate
Target and deployment access Resource group/subscription, azd environment and environment-scoped deployment identity. DEV must not deploy to PROD.
Runtime access Component identities, grants and Entra registrations, or explicitly separated callbacks and consent.
Configuration and secrets App Configuration store/endpoint and Key Vault. The agent-lz label is shared by convention, not an environment separator.
Data Sources, indexes, conversation/history stores and retention. Use approved test data instead of copying production documents.
Network and builds DNS, routes, private endpoints and a connected runner. An ACR build pool does not connect the deployment host.

Approved nonsecret inputs can be version-controlled. An environments/ folder is not loaded automatically; its settings need explicit application. Local .azure contains private deployment state, which hooks copy to child projects. Those workspaces need the same protection and cannot safely be copied between DEV, TEST and PROD.

Deployment parameters

Resource naming

Resource naming explains defaults, overrides and name stability. Names resolve before the first provision; later changes can create new resources instead of updating existing ones.

Resource group destinations

This Agent azd interface is shared by the product's Bicep and integrated Terraform paths using the compatible components pinned by the platform manifest. For direct shared-module use or portal deployment, follow those implementations' input references.

New environments use three resource groups by default: Foundry/grounding, application and workload networking. Existing environments keep their mapping. All workload destinations must be in AZURE_SUBSCRIPTION_ID.

Equal names are valid: one, two or three distinct groups can express the same three logical destinations. These inputs do not enable services, change network isolation or create a platform hub; existing BYO VNet, DNS and hub settings still apply.

Variable Default Purpose
AZURE_RESOURCE_GROUP rg-<environment-name> Foundry and grounding destination, and the native azd root deployment group. An explicitly supplied name is preserved.
AZURE_APP_RESOURCE_GROUP <AZURE_RESOURCE_GROUP>-app Application destination (applicationResourceGroupName): Container Apps, registry, App Configuration, Key Vault, application Cosmos DB and monitoring.
AZURE_NETWORK_RESOURCE_GROUP <AZURE_RESOURCE_GROUP>-network Destination (networkResourceGroupName) for workload-owned network resources. Existing network/private-endpoint overrides retain their own contract.
CREATE_RESOURCE_GROUPS true for new environments Strict boolean (true or false): allows creating missing additional destination groups. Set false to require pre-created additional groups. Does not disable azd's normal root-group creation.

The hook saves these defaults in the selected azd environment before provision. For long custom root names, generated names include a stable hash and suffix within Azure's 90-character limit. These are first-run defaults, not automatic changes to existing environments.

Set destinations before first provision. For three pre-created groups:

azd env set AZURE_RESOURCE_GROUP rg-ai
azd env set AZURE_APP_RESOURCE_GROUP rg-app
azd env set AZURE_NETWORK_RESOURCE_GROUP rg-net
azd env set CREATE_RESOURCE_GROUPS false

For two groups, set AZURE_NETWORK_RESOURCE_GROUP to rg-ai to keep networking with Foundry, or rg-app to keep it with the application. For one group, explicitly select the same name for all destinations:

azd env set AZURE_RESOURCE_GROUP rg-workload
azd env set AZURE_APP_RESOURCE_GROUP rg-workload
azd env set AZURE_NETWORK_RESOURCE_GROUP rg-workload

With false, a missing additional destination fails before services are provisioned. With true, existing groups are reused without changing their tags or location; only missing additional groups are created.

The additional destinations are application and network; azd manages creation of the Foundry/root group through its normal lifecycle. New additional groups do not receive the azd-env-name tag.

Run the normal product-root lifecycle: each azd provision coordinates the selected provider across the configured destinations. Bicep uses its resource-group-scoped root and scoped modules; Terraform uses its repository-owned composition. Do not replace the lifecycle with three manual deployments. Hosted image preparation remains part of application deployment.

Resource group permissions

  • Existing groups: Contributor on each target covers resource management and Microsoft.Resources/deployments/*, not RBAC grants or data access. Splitting existing groups does not itself require subscription Owner or subscription-scope deployment permission.
  • Creating missing groups: CREATE_RESOURCE_GROUPS=true additionally needs Microsoft.Resources/subscriptions/resourceGroups/write at subscription scope. A scoped custom role can grant that action; subscription Contributor is broader, not a universal prerequisite.
  • RBAC: the deploying identity needs Microsoft.Authorization/roleAssignments/write at each assignment scope, for example through Role Based Access Control Administrator, subject to its conditions. Creating a group does not automatically grant this access.
  • Service configuration: keep the required Foundry, Search, App Configuration, Key Vault and other service-specific data-plane roles. Management-plane Contributor does not replace them. External network/DNS resources require their owners' scoped permissions.

Resource-group Contributor and scoped RBAC administration do not grant Entra directory reads; for platform-output client-ID discovery, restricted automation can instead supply AGENTLZ_COMPONENT_IDENTITIES as a nonsecret JSON map of Container App component names to pre-resolved managed-identity client IDs, without granting broad directory rights.

The workflow records the mapping with the environment and uses the deploying identity's permissions. Preserve that mapping for provisioning, deployment and recovery.

After partial failure, repair the cause and retry with the same destinations. Do not delete groups as automatic rollback. Review every destination and shared dependency before any environment removal.

For Bicep, the predown guard blocks split-group azd down; arrange owner-reviewed, separately authorized cleanup. For Terraform, the guard verifies the original common group binding, terraform-resource-groups.json and terraform-backend.json, then permits native state-scoped destroy across recorded owned/BYO groups. It rejects missing records or retargeted groups/backend settings. See Terraform removal.

Values set by azd or by you

A principal is a user or service identity. Its object ID identifies that identity in the Entra directory; it is not an application's client ID.

Variable Description
AZURE_ENV_NAME Environment name, created/selected during azd init for a new project or azd env new for an additional environment. Used to derive resource names.
AZURE_LOCATION Primary Azure region. Set it before provision so the first-run hook can create the additional resource groups.
AZURE_PRINCIPAL_ID Deployment identity's object ID for service setup and access. azd resolves it for Bicep; Terraform preprovision detects a missing value for ordinary CLI, service-principal and managed-identity authentication.

For certificate, OIDC or custom managed-identity authentication, explicitly set AZURE_PRINCIPAL_ID and AZURE_PRINCIPAL_TYPE to identify the caller. These inputs are not credentials; use the caller's object ID, not its client ID. See Terraform authentication.

Shared template defaults

These mappings have no inline default in main.parameters.json. When unset, they use the template defaults shown below.

Variable Template default Description
NETWORK_ISOLATION false Set true explicitly for private production. Public endpoints are only for approved evaluations without sensitive data. Jumpbox, Bastion and firewall also depend on component flags. See Network design.
AZURE_AI_FOUNDRY_LOCATION Deployment region Region for the Microsoft Foundry account.
AZURE_COSMOS_LOCATION Deployment region Region for Agent Application Cosmos DB.
USE_UAI false Uses user-assigned managed identities instead of system-assigned identities.
ENABLE_AGENTIC_RETRIEVAL false Enables the template's agentic retrieval resource configuration. This is separate from the Agent Application setting RETRIEVAL_BACKEND.
USE_EXISTING_VNET false Deploys into a virtual network you already have when network isolation is enabled.
EXISTING_VNET_RESOURCE_ID Empty Resource ID required when reusing a virtual network.
SIDE_BY_SIDE true Selects side-by-side placement for private endpoints and DNS zones rather than placing them in the existing VNet's resource group. See the private endpoint group precedence below.

General

Variable Default Description
AZURE_PRINCIPAL_TYPE User; inferred during Terraform caller detection Type of AZURE_PRINCIPAL_ID: User or ServicePrincipal. Explicit service identities use ServicePrincipal.
DEPLOYMENT_MODE standalone Declares deployment intent for tags and preflight. ailz-integrated does not automatically attach a hub or override component flags. Supply the hub, routing, resource reuse and DNS inputs explicitly.
POLICY_MANAGED_PRIVATE_DNS false Delegates private DNS zone groups/records to Azure Policy. Use instead of BYO private DNS zone IDs; agree policy coverage, VNet links and readiness with the DNS owner.
RESOURCE_NAMING_MODE caf Uses Cloud Adoption Framework prefixes and naming tokens. See Resource naming.
APP_RUNTIME_CONFIGURATION_MODE appConfig Selects runtime delivery, not deployment discovery. See runtime configuration mode.
DEPLOY_COSMOS_DB false without a required consumer; selected automatically when required Generic application Cosmos can also be explicitly selected without MCP or the orchestrator. Foundry backing storage is separate.
ENABLE_COSMOS_ANALYTICAL_STORAGE false Enables the Agent Application Cosmos DB analytical store.
AZURE_SEARCH_LOCATION Empty Region for both the Agent Application Search service and the separate Foundry Agent Service Search service. Leave empty to use AZURE_LOCATION.
AZURE_SPEECH_LOCATION Empty Region for Azure AI Speech. Leave empty to use the deployment region.
AZURE_PE_LOCATION Empty Region for private endpoints. Leave empty to use the deployment region.
AZURE_PE_RESOURCE_GROUP_NAME Empty Explicit private endpoint group override (privateEndpointResourceGroupName) takes precedence. When empty, USE_EXISTING_VNET=true with SIDE_BY_SIDE=false uses the existing VNet's group; otherwise uses the resolved network group (AZURE_NETWORK_RESOURCE_GROUP). New Foundry-root environments initialize a separate network group; existing single-group environments retain their mapping.
EXISTING_APPLICATION_INSIGHTS_CONNECTION_STRING None Sends telemetry to an Application Insights resource you already have.

Supported EXISTING_* inputs select reuse, subject to each resource's conditions. They are listed in Network and security. Foundry backing-service reuse uses the native parameters below. A supported resource ID selects reuse; naming and deployment flags control resource creation.

Runtime configuration mode

Mode Store selection Runtime delivery
appConfig Requires a provisioned, usable store Existing centralized settings, feature flags and Key Vault references under agent-lz
containerEnv deployAppConfig may be false or true Curated Container App environment settings and secret references, without store discovery or publication
none Independent of store presence No new runtime configuration injection

Set APP_RUNTIME_CONFIGURATION_MODE in the selected azd environment. To omit the store, set parameters.deployAppConfig.value to the JSON boolean false in root main.parameters.json. There is no implied environment mapping for that native parameter. A provisioned store does not select appConfig mode.

Both providers still run selected Foundry, Search, governance, Container Apps and panel configuration using verified metadata. Selected features retain their real prerequisites, including Key Vault operations and private connectivity. The bundled Agent Application, Agent App MCP Server and samples/custom-app/containerapp require App Configuration, while samples/custom-app/hosted reads platform-injected FOUNDRY_PROJECT_ENDPOINT directly without APP_CONFIG_ENDPOINT. A custom store-free application must own compatible runtime configuration and declare its dependencies. This setting does not delete an existing store or migrate an application's runtime mode in place.

Application Cosmos DB

The default application layout does not create application Cosmos DB resources or their dedicated identity. Foundry backing storage is independent. Native Hosted execution uses Foundry persistence; durable Container Apps execution uses Durable Task Scheduler (DTS). Neither uses application Cosmos as a duplicate execution checkpoint store.

Workflow mode or both selects UI metadata even when ENABLE_CHAT_HISTORY=false and ENABLE_USER_FEEDBACK=false, their defaults. Enabled history, feedback or private attachments also selects this dependency.

The UI consumes DATABASE_ACCOUNT_NAME, DATABASE_NAME and NATIVE_UI_METADATA_CONTAINER (default native-ui-metadata, partition key /principal_id, owner tid:oid), with its grant assigned only to the frontend. Existing COSMOS_DB_ENDPOINT and COSMOS_DB_ACCOUNT_RESOURCE_ID outputs remain conditional; no separate native endpoint key is introduced.

The explicitly selected NL2SQL toolset uses the same application account for its separate approved-source and vector-metadata containers, with grants assigned to the MCP identity, not the orchestrator.

A custom component may declare another application storage requirement. UI metadata contains descriptors and references, not bytes, transcripts or tokens.

With conversational mode and every product flag off, bounded volatile UI owner maps are lost on restart.

Do not omit a store required by a selected consumer, or enable ingestion just to supply metadata storage. Leave deployment selection consistent with the application definition and review all consumers before changing it. An explicit Cosmos exclusion that conflicts with a required consumer fails with guidance to unset DEPLOY_COSMOS_DB=false for automatic selection or set it explicitly to true. Deliberately set or persisted false is not silently overridden.

For an additional application storage requirement, opt in before provisioning:

azd env set DEPLOY_COSMOS_DB true

This selection also works for generic storage without MCP or the reference orchestrator, including a custom AGENTLZ_APP_DEFINITION. Custom Cosmos capabilities can declare the dependency directly. Enabling Cosmos alone does not deploy MCP or enable vector search.

Normal application Cosmos is serverless. NL2SQL selects vector capability and its catalog policies; a retained catalog preserves them. Custom applications may explicitly select generic vector capability with COSMOS_VECTOR_SEARCH_ENABLED without injecting the reference catalog. Generic Cosmos by itself does not enable vector search.

Direct foundation-template deployments also default deployCosmosDb to false; set it to true when application storage is needed. For an existing deployment, review the provision preview and retain the account until its consumers and data-retention requirements have been reviewed.

Optional application PostgreSQL

DEPLOY_POSTGRESQL=false is the strict default-off selector for both providers. Fresh custom ACA deployments explicitly supply administrator OID/name/type. Defaults: version16, Burstable/Standard_B1ms, 32 GiB, backup7, HA Disabled, geo-backup/auto-grow false. Basic uses dedicated ACA NAT/restricted public PG; isolated uses Private Link/public PG disabled regardless of common allowlists. Typed operator ranges and existing PG DNS IDs have no string aliases. Optional PostgreSQL lists all inputs, validations, flat agent-lz keys, manual SQL grants and independent-lock recovery/removal. It does not select MCP/NL2SQL or replace Cosmos; retrofit/disable/mode replacement are blocked.

Agent App MCP Server selection

Variable Default Effect
DEPLOY_AGENT_APP_MCP false Adds optional Agent App MCP Server compute and authentication only; does not select SQL or catalog/model/secret access.

Set this selector before provision. It is independent of ORCHESTRATION_HOST=hosted|container_apps and APPLICATION_MODE=conversational|workflow|both. Select tools explicitly with application/runtime setting MCP_TOOLSETS, published under label agent-lz, not new tool-specific Bicep/Terraform parameters. The default [] registers zero tools and initializes no NL2SQL clients or dependencies. The only supported nonempty value is ["nl2sql"]:

azd env set DEPLOY_AGENT_APP_MCP true
azd env set MCP_TOOLSETS '["nl2sql"]'

Set both before provision/deploy for SQL. Unknown names, duplicates and invalid values fail closed. In the reference application, nonempty toolsets require server compute selection. DEPLOY_AGENT_APP_MCP is rejected for custom definitions before Azure calls. Custom applications may explicitly supply MCP_TOOLSETS as runtime configuration and declare their own compute, dependencies and permissions; this adds no automatic reference catalog or model resources. Do not manually copy generated endpoint/authentication settings.

Only when NL2SQL is selected, Bicep and Terraform create the dependency when absent or reuse the compatible application account managed by this deployment. Provision captures and preserves the exact existing capability set and data, adds EnableNoSQLVectorSearch and provisions mcp-sources and mcp-nl2sql-metadata, partitioned by /source_id.

The metadata vector policy uses /embedding, float32, cosine, quantizedFlat and the selected model dimensions (default 3072). Model selection and dimensions must resolve before policies are provisioned.

Existing catalog name/dimension changes are rejected in place; use an explicit migration/reindexing plan instead of changing settings on the existing catalog.

Incompatible throughput or policies fail explicitly. The lifecycle does not recreate accounts/containers, convert shared throughput or choose an unrelated external or Foundry backing account.

The MCP receives catalog read, model access and only required secret grants; the importer has separately authorized catalog write access. SQL users and grants remain the SQL owner's responsibility. MCP_SQL_SECRET_NAMES=[] declares optional SQL password-secret names for secret-scoped MCP vault grants; do not place passwords in that list.

The deployment helper configures the Entra API registration/service principal and MCP.Invoke app role automatically, creating or reusing the registration by the exact application object ID recorded in App Configuration.

The deployer must have directory rights for registration and application-role assignments, separate from ARM permissions; there is no broad ARM-token authentication fallback.

An empty server retains mandatory tenant/audience/app-role/client restrictions but receives no NL2SQL catalog, model or secret grants.

Selection does not enable DEPLOY_SEARCH_SERVICE, create Search indexes or grant Search access. Other retrieval consumers keep their independent Search requirements. Generated settings are published under agent-lz; see the MCP contract.

Use the MCP component guide for fresh and existing-installation steps. Toolsets are startup-only: changes require restart/redeployment. Setting MCP_TOOLSETS=[] stops NL2SQL registration and dependency initialization; it does not automatically revoke old roles. Disabling server compute likewise does not delete catalog metadata.

The retained COSMOS_VECTOR_SEARCH_ENABLED marker preserves vector capability. The catalog account, container declarations and vector policies are retained for owner-reviewed safe cleanup.

Agent App Ingestion selection

Variable Fresh-environment default Description
DEPLOY_INGESTION_CONTAINER_APP false Selects optional Agent App Ingestion independently of native host, application mode and product metadata.

The boolean is persisted by pre-provision and published under label agent-lz. Existing environments retain their selection rather than silently adopting the fresh default. Custom definitions retain only their declared components and resource requirements; this reference selector does not add ingestion to them.

Selection Effect
false Omits the optional component from subsequent composition, deployment and reconciliation. Existing resources and grants are not deleted.
true Selects the component and its infrastructure requirements. It does not grant users upload permission.

The source/index arrangement must support omission. See Ingestion for supported source combinations and the native private-input boundary.

Model deployments and external AI Gateway

Variable Default Description
DEPLOY_MODEL_DEPLOYMENTS true Maps to deployModelDeployments across Bicep and Terraform. Set false when routing all model inference through an external AI Gateway with zero local Foundry model deployments.

When DEPLOY_MODEL_DEPLOYMENTS=false (deployModelDeployments = false), neither Bicep nor Terraform provisions local chat or embedding deployments, and an empty native modelDeploymentList = [] does not fall back to default deployments. Regional model quota preflight checks are skipped. config.aifoundry.setup still configures account-level Responsible AI (RAI) blocklists and policies while skipping local model deployment RAI attachment.

Features that require a local Foundry planning or embedding deployment (such as Foundry IQ MCP planning models or NL2SQL vector embeddings unless externally satisfied) retain their validation guards.

Search region and quota

AZURE_SEARCH_LOCATION resolves the effective Bicep searchServiceLocation. An unset or empty value falls back to AZURE_LOCATION. Both newly created Search services use this effective region. Provider availability and Search quota checks use that same region, not the primary region when an override is set.

Search quota must cover the complete enabled service count: the selected Agent Application Search service plus a separate Foundry backing Search service when the selected component requires Foundry Agent Service and no existing backing Search resource is supplied. Host-specific provider flags are derived, not additional public native selectors.

When both creation paths are enabled, the check requires quota for two services. Reusing a Foundry Search resource does not request a new service for that path. Bypassing preflight does not resolve region mismatches or insufficient quota. See Search preflight region and quota.

Retrieval

These inputs select and name the knowledge objects configured during provisioning. Foundry IQ explains sources, retrieval and user authorization. Creating an object does not populate an existing index or grant document access.

Variable Default Description
RETRIEVAL_BACKEND foundry_iq Selects the retrieval arrangement for service configuration. The runtime default of a standalone component can differ.
FOUNDRY_IQ_PATTERN azureBlob Native Blob source processing and knowledge-base setup.
FOUNDRY_IQ_KNOWLEDGE_SOURCE_KIND azureBlob Blob connector for the knowledge source.
FOUNDRY_IQ_API_VERSION 2026-05-01-preview Azure AI Search API version used for Foundry IQ objects.
FOUNDRY_IQ_IS_ADLS_GEN2 false Identifies Azure Data Lake Storage (ADLS) Gen2: Blob storage with a hierarchical directory namespace. true when the source account uses that namespace.
KNOWLEDGE_BASE_NAME knowledge-base Knowledge base name.
KNOWLEDGE_BASE_CONNECTION_NAME knowledge-base-connection Foundry project connection to the knowledge base.
FOUNDRY_IQ_KNOWLEDGE_SOURCE_NAME knowledge-base-blob-ks Knowledge source name.
FOUNDRY_IQ_SEARCH_INDEX_NAME agent-lz-index Search index name.

Other provisioned defaults are billing plan free, semantic configuration default, storage container documents and content extraction mode standard. The legacy security-field default is metadata_security_id with its add-on disabled. Native permission filtering instead uses userIds, groupIds and rbacScope annotations. Provisioning preserves documents and custom schema on compatible indexes and rejects incompatible annotations. Do not disable permission checks to force an update.

Additional native source identities

Enable each source with its compatible API contract, name and bindings. Incomplete enabled sources fail before resource changes instead of disappearing from a mixed knowledge base. The functional source guides own those compatibility requirements.

These optional identity inputs are nonsecret UUIDs. Explicit deployment environment values are published under agent-lz; omission invents no identity and an explicit empty value clears that setting.

Setting Meaning
WORK_IQ_APPLICATION_ID Work IQ app's application/client ID.
WORK_IQ_FEDERATED_CREDENTIAL_ID Object ID of the credential that trusts the Search principal, not the principal ID.
WORK_IQ_TENANT_ID App tenant ID for cross-tenant Work IQ configuration.
SHAREPOINT_INDEXED_APPLICATION_ID SharePoint ingestion app's application/client ID.
SHAREPOINT_INDEXED_FEDERATED_CREDENTIAL_APPLICATION_ID Application/client ID of the federated Search managed identity, not a credential object ID.

These settings do not register Entra apps, grant tenant consent or remove source licensing/billing requirements. See Work IQ and SharePoint for administrator setup.

Explicit shared-source permission options

FOUNDRY_IQ_INGESTION_PERMISSION_OPTIONS defaults to ["rbacScope"] when omitted or actually null. An explicit JSON [] has a different meaning: it can opt a supported active non-ADLS native Blob source into shared-source metadata. Invalid input and unsupported active combinations fail closed.

This is not a permission grant or a repair for authentication/private-link failures. Follow the shared-source permission contract for source constraints, audience review, allow/deny acceptance and recovery.

Protected download configuration

Downloads reuse provisioned storage and Search bindings. There is no separate permission-bypass input. Use protected citation downloads for runtime settings, consent and source-access requirements.

Network and security

These parameters apply mainly when NETWORK_ISOLATION=true. Network design explains connectivity and DNS requirements.

Additional runtime destinations belong in the application's components[].egress, not a blanket network exception or App Configuration key. Review the component plan before provisioning; external firewall policies remain report-only.

Variable Default Description
DEPLOY_AZURE_FIREWALL true Deploys Azure Firewall for egress control.
AZURE_FIREWALL_SKU Basic Selects matching firewall and policy SKU. Basic is supported for isolated standalone deployments; select Standard explicitly when its capabilities are required. External hub firewalls retain their own SKU and ownership.
ENABLE_FIREWALL_DNS_PROXY false Requires an isolated local Standard firewall. Basic with proxy enabled is rejected. Does not modify VNet or VPN DNS settings.
DEPLOY_ACR_TASK_AGENT_POOL true Deploys an Azure Container Registry agent pool inside the virtual network so images can be built without a local Docker host. The pool is created only when NETWORK_ISOLATION=true.
DEPLOY_JUMPBOX Same as NETWORK_ISOLATION Deploys a Windows jumpbox virtual machine.
DEPLOY_BASTION Enabled with network isolation and jumpbox deployment Deploys Azure Bastion unless an existing Bastion is selected.
BASTION_SKU_NAME Standard Bastion SKU.
DEPLOY_NAT_GATEWAY Enabled with network isolation and jumpbox deployment Deploys a NAT gateway unless an existing gateway is selected.
ENABLE_ACS_MEDIA_EGRESS false Opens firewall egress for Azure Communication Services media.
DEPLOY_GROUNDING_WITH_BING false Deploys Grounding with Bing Search.
DEPLOY_KEY_VAULT true Deploys the Agent Application Key Vault.
DEPLOY_VM_KEY_VAULT false Deploys a separate Key Vault for the jumpbox.
DEPLOY_LOG_ANALYTICS true Deploys a Log Analytics workspace unless an existing workspace is selected.
ENABLE_PRIVATE_LOG_ANALYTICS true Configures Azure Monitor Private Link when network isolation is enabled and a central workspace is not being reused.
ALLOW_MIXED_OBSERVABILITY_WORKSPACES false Allows Application Insights and Log Analytics from different sources.
DEPLOY_SEARCH_SERVICE true Deploys the Agent Application Search service.
DEPLOY_SPEECH_SERVICE false Deploys Azure AI Speech (SKU S0).
DEPLOY_STORAGE_ACCOUNT true Deploys the document storage account.

Bastion tunneling is disabled by default.

Firewall SKU and management networking

New isolated standalone deployments select AZURE_FIREWALL_SKU=Basic. Select Standard explicitly when DNS proxy, network-rule FQDN filtering or greater capacity is required. Basic supports application HTTP(S) FQDN rules and IP/service-tag network rules; assess its approximately 250 Mbps capacity class against build, image-download and ingestion peaks.

Topology Local firewall data subnet/IP Local management subnet/IP GatewaySubnet
Standalone Basic Required Required Explicit reservation only
Standalone Standard Required None Explicit reservation only
External hub, with or without gateway No IP; data subnet only if explicitly reserved None Explicit local reservation only
Public/non-isolated None None None

Both local SKUs use AzureFirewallSubnet. Basic additionally needs the exact name AzureFirewallManagementSubnet, a /26-or-larger range and a separate Standard/static public IP and management NIC configuration. Keep management networking free of generic NSGs, workload default routes, NAT, delegations and service endpoints. Validate externally managed subnet routing with the network owner. Workload routes use the data-plane private IP.

For external hub egress, explicitly disable local firewall deployment and configure the approved external next hop or route table. A deployment-mode label alone does not configure egress or change hub resources.

Opt-in firewall DNS proxy

ENABLE_FIREWALL_DNS_PROXY defaults to false and maps to the Bicep boolean enableFirewallDnsProxy (also default false), which sets dnsSettings.enableProxy on a Standard firewall. Basic with proxy enabled is rejected; its policy omits DNS settings. It applies only when the deployAzureFirewall and networkIsolation gates enable firewall deployment.

It is intended for a topology that deliberately uses the firewall as its DNS forwarding path. The matching deployment guide applies the selection through normal provisioning.

Enabling the proxy does not redirect VNet or VPN clients to the firewall or rewrite their DNS configuration. It is independent of the build-feed egress allowlist.

Client DNS routing and private-zone resolution remain separate requirements. A proxy cannot repair missing zone links, VPN routes or application authentication. Disabling it requires confirmation that the deployed DNS path does not depend on it before reprovisioning.

Subnet creation and addressing

Choose subnet ownership first. The global DEPLOY_SUBNETS switch defaults to true. Firewall data and management switches default to null (auto): data follows the local isolated firewall requirement, while management is used only by standalone Basic.

DEPLOY_GATEWAY_SUBNET defaults to false; explicitly enable it to reserve a subnet for a separately configured local gateway. Other individual subnet switches default to true.

Creation also requires network isolation and the global switch; management additionally requires an active standalone Basic firewall, even when its creation switch is explicitly true.

Native root parameter Environment input Subnet purpose
deploySubnets DEPLOY_SUBNETS Global creation switch for new and existing VNets
deployAgentSubnet DEPLOY_AGENT_SUBNET Foundry Agent Service
deployAcaEnvironmentSubnet DEPLOY_ACA_ENVIRONMENT_SUBNET Container Apps environment
deployPeSubnet DEPLOY_PE_SUBNET Foundry/grounding private endpoints
deployAzureBastionSubnet DEPLOY_AZURE_BASTION_SUBNET Bastion
deployAzureFirewallSubnet DEPLOY_AZURE_FIREWALL_SUBNET Firewall
deployAzureFirewallManagementSubnet DEPLOY_AZURE_FIREWALL_MANAGEMENT_SUBNET Basic firewall management
deployGatewaySubnet DEPLOY_GATEWAY_SUBNET VPN/ExpressRoute reservation
deployAppGatewaySubnet DEPLOY_APP_GATEWAY_SUBNET Application Gateway
deployJumpboxSubnet DEPLOY_JUMPBOX_SUBNET Jumpbox
deployDevopsBuildAgentsSubnet DEPLOY_DEVOPS_BUILD_AGENTS_SUBNET Build agents
deployApplicationPeSubnet DEPLOY_APPLICATION_PE_SUBNET Application private endpoints
deployPowerPlatformSubnet DEPLOY_POWER_PLATFORM_SUBNET Power Platform
deployAiGatewaySubnet DEPLOY_AI_GATEWAY_SUBNET AI Gateway

A false creation flag means do not create/manage that subnet; it does not disable its consumer. Every enabled consumer must have an existing, valid subnet in the selected VNet, or be explicitly disabled. No consumer is silently disabled or redirected to another subnet.

For a fresh deployment without Power Platform integration, omit its optional reservation with azd env set DEPLOY_POWER_PLATFORM_SUBNET false. In contrast, disabling application PE subnet creation still requires an existing application PE subnet when application private endpoints are enabled.

An isolated new VNet is still created when subnet creation is disabled, but configuration fails if an enabled workload requires a subnet that is absent. For an existing VNet, only selected subnets are created/updated, through serialized child deployments; its entire subnet collection is not replaced.

Managed BYO subnet writes require deployNsgs=true; opting out of a subnet's creation does not remove its existing NSG association.

Creation flags are not deletion commands or a guarantee of preserving every previously submitted subnet in a deployment-owned VNet; Azure can reject removal of occupied subnets.

deployAiFoundrySubnet controls the Foundry Agent Service subnet association, not subnet creation. Use deployAgentSubnet for creation ownership.

Network selection examples

For a new isolated environment, set azd env set NETWORK_ISOLATION true, then apply the matching selection.

For a new VNet, keep the default names and address plan unless your network owner requires different ranges:

azd env set USE_EXISTING_VNET false
azd env set DEPLOY_SUBNETS true

For an existing VNet with template-managed subnets, replace the placeholder with its full ARM resource ID and match the subnet inputs to the approved plan:

azd env set USE_EXISTING_VNET true
azd env set EXISTING_VNET_RESOURCE_ID <existing-vnet-resource-id>
azd env set DEPLOY_SUBNETS true

For externally managed subnets, use the same existing-VNet inputs but set azd env set DEPLOY_SUBNETS false. Confirm all required subnets already exist with the configured names, prefixes, delegations and NSG requirements. Then continue with the selected deployment guide; these inputs do not configure peering, DNS forwarding or runner connectivity.

Default subnets

The new VNet's default address space is 192.168.0.0/21. Names and ranges can be overridden using the subnet inputs.

Purpose Default name Default CIDR
Foundry Agent Service agent-subnet 192.168.0.0/24
Container Apps environment aca-environment-subnet 192.168.1.0/24
Foundry/grounding private endpoints pe-subnet 192.168.2.0/26
Bastion AzureBastionSubnet 192.168.2.64/26
Firewall AzureFirewallSubnet 192.168.2.128/26
VPN/ExpressRoute reservation GatewaySubnet 192.168.2.192/26
Application Gateway AppGatewaySubnet 192.168.3.0/27
Jumpbox jumpbox-subnet 192.168.3.64/27
Build agents devops-build-agents-subnet 192.168.3.96/27
Application private endpoints application-pe-subnet 192.168.3.128/26
Basic firewall management AzureFirewallManagementSubnet 192.168.3.192/26
Power Platform powerplatform-subnet 192.168.4.0/24
AI Gateway ai-gateway-subnet 192.168.5.0/24
Subnet delegations
  • Foundry Agent Service and Container Apps environment: Microsoft.App/environments.
  • Power Platform: Microsoft.PowerPlatform/enterprisePolicies.
  • AI Gateway: Microsoft.Web/serverFarms.
  • All other subnets in this plan: no delegation.

Firewall data subnet creation defaults to the local firewall requirement. The management subnet is used only by a standalone Basic firewall. GatewaySubnet is opt-in. The table is an address plan, not an unconditional resource inventory; shared-hub services do not require these reservations in the spoke.

With isolation off, no VNet or subnets are provisioned.

Prepared subnets are not deployed services. These reservations do not deploy APIM or VPN/ExpressRoute gateways, create a Power Platform enterprise policy, or associate a Power Platform environment. Those integrations need separate setup.

See the application private endpoint subnet for its consumers and required separation from Foundry/grounding endpoints.

Keep the reserved name GatewaySubnet; do not attach an NSG, default-route UDR or delegation to it.

AI Gateway uses APIM Standard v2/Premium v2 outbound VNet integration, with a subnet of /27 or larger, delegated to Microsoft.Web/serverFarms and associated with an NSG. Preserve an outbound HTTPS path to Azure Key Vault. No reserved subnet name is required for APIM; do not place APIM private endpoints in its delegated integration subnet.

The Power Platform /24 is a capacity default, not a platform minimum. Size for environment demand: approximately 25–30 IPs per production environment or 6–10 per nonproduction environment, plus five subnet-reserved IPs. See Power Platform subnet sizing.

Names and address ranges

Subnet name and prefix parameters can be overridden in root main.parameters.json or through the environment bindings below. Explicit operator values are preserved through composition; the allocation table lists defaults, not mandatory ranges. Reserved service names must retain their required spellings.

Subnet names
Native name parameter Name environment input
agentSubnetName AZURE_AGENT_SUBNET_NAME
acaEnvironmentSubnetName AZURE_ACA_ENVIRONMENT_SUBNET_NAME
peSubnetName AZURE_PE_SUBNET_NAME
azureBastionSubnetName AZURE_BASTION_SUBNET_NAME
azureFirewallSubnetName AZURE_FIREWALL_SUBNET_NAME
azureFirewallManagementSubnetName AZURE_FIREWALL_MANAGEMENT_SUBNET_NAME
gatewaySubnetName AZURE_GATEWAY_SUBNET_NAME
azureAppGatewaySubnetName AZURE_APP_GATEWAY_SUBNET_NAME
jumpboxSubnetName AZURE_JUMPBOX_SUBNET_NAME
devopsBuildAgentsSubnetName AZURE_DEVOPS_BUILD_AGENTS_SUBNET_NAME
applicationPeSubnetName AZURE_APPLICATION_PE_SUBNET_NAME
powerPlatformSubnetName AZURE_POWER_PLATFORM_SUBNET_NAME
aiGatewaySubnetName AZURE_AI_GATEWAY_SUBNET_NAME
Subnet address prefixes
Native prefix parameter Prefix environment input
agentSubnetPrefix AZURE_AGENT_SUBNET_PREFIX
acaEnvironmentSubnetPrefix AZURE_ACA_ENVIRONMENT_SUBNET_PREFIX
peSubnetPrefix AZURE_PE_SUBNET_PREFIX
azureBastionSubnetPrefix AZURE_BASTION_SUBNET_PREFIX
azureFirewallSubnetPrefix AZURE_FIREWALL_SUBNET_PREFIX
azureFirewallManagementSubnetPrefix AZURE_FIREWALL_MANAGEMENT_SUBNET_PREFIX
gatewaySubnetPrefix AZURE_GATEWAY_SUBNET_PREFIX
azureAppGatewaySubnetPrefix AZURE_APP_GATEWAY_SUBNET_PREFIX
jumpboxSubnetPrefix AZURE_JUMPBOX_SUBNET_PREFIX
devopsBuildAgentsSubnetPrefix AZURE_DEVOPS_BUILD_AGENTS_SUBNET_PREFIX
applicationPeSubnetPrefix AZURE_APPLICATION_PE_SUBNET_PREFIX
powerPlatformSubnetPrefix AZURE_POWER_PLATFORM_SUBNET_PREFIX
aiGatewaySubnetPrefix AZURE_AI_GATEWAY_SUBNET_PREFIX

Set vnetAddressPrefixes.value as an explicit array in root main.parameters.json (default ["192.168.0.0/21"]); there is no VNET_ADDRESS_PREFIXES environment mapping. For example, merge this complete address plan into the root file's parameters object before first provision, if 10.20.0.0/21 is approved and does not overlap connected networks:

{
  "vnetAddressPrefixes": {"value": ["10.20.0.0/21"]},
  "agentSubnetPrefix": {"value": "10.20.0.0/24"},
  "acaEnvironmentSubnetPrefix": {"value": "10.20.1.0/24"},
  "peSubnetPrefix": {"value": "10.20.2.0/26"},
  "azureBastionSubnetPrefix": {"value": "10.20.2.64/26"},
  "azureFirewallSubnetPrefix": {"value": "10.20.2.128/26"},
  "azureFirewallManagementSubnetPrefix": {"value": "10.20.3.192/26"},
  "gatewaySubnetPrefix": {"value": "10.20.2.192/26"},
  "azureAppGatewaySubnetPrefix": {"value": "10.20.3.0/27"},
  "jumpboxSubnetPrefix": {"value": "10.20.3.64/27"},
  "devopsBuildAgentsSubnetPrefix": {"value": "10.20.3.96/27"},
  "applicationPeSubnetPrefix": {"value": "10.20.3.128/26"},
  "powerPlatformSubnetPrefix": {"value": "10.20.4.0/24"},
  "aiGatewaySubnetPrefix": {"value": "10.20.5.0/24"}
}

A subnet override does not resize the VNet; a reused VNet's actual address space is authoritative. Names must be unique and required names/prefixes cannot be empty.

CIDRs must be aligned IPv4 ranges, contained in the VNet and nonoverlapping with other requested or existing subnets. The same managed subnet's current range is not counted twice.

Invalid ranges fail rather than being replaced with defaults. Reserved names and service-specific size, delegation and NSG requirements still apply.

Application private endpoint subnet

Application private endpoints use their own configured subnet, independently of resource group count.

AZURE_APPLICATION_PE_SUBNET_NAME

Native root parameter: applicationPeSubnetName

Default: application-pe-subnet

Dedicated application private endpoint subnet name.

AZURE_APPLICATION_PE_SUBNET_PREFIX

Native root parameter: applicationPeSubnetPrefix

Default: 192.168.3.128/26

Aligned IPv4 CIDR for the application private endpoint subnet.

Enabled application Cosmos DB, Key Vault, App Configuration, Container Apps, ACR and Azure Monitor Private Link Scope private endpoints use the application subnet. Foundry/grounding private endpoints use peSubnetName/peSubnetPrefix, defaulting to pe-subnet at 192.168.2.0/26.

Customize the name and prefix before first provision, using your approved address plan:

azd env set AZURE_APPLICATION_PE_SUBNET_NAME snet-app-pe
azd env set AZURE_APPLICATION_PE_SUBNET_PREFIX <approved-ipv4-subnet-cidr>

The application subnet needs a distinct name and an aligned IPv4 CIDR of /29 or shorter. Empty required names/prefixes fail explicitly; there is no shared Foundry PE fallback. With DEPLOY_APPLICATION_PE_SUBNET=false or DEPLOY_SUBNETS=false, application endpoints still select this configured subnet. It must already exist and satisfy the enabled consumers' requirements.

Hub integration

These parameters describe spoke integration with an existing hub. Hub integration explains the network design.

Variable Default Description
HUB_INTEGRATION_HUB_VNET_RESOURCE_ID None Resource ID of the hub virtual network.
HUB_INTEGRATION_CREATE_HUB_PEERING true Creates spoke-to-hub peering for a newly created spoke VNet. The hub owner supplies reverse peering. With an existing VNet, both directions are externally managed.
HUB_INTEGRATION_PEERING_ALLOW_GATEWAY_TRANSIT false Allows gateway transit on the peering.
HUB_INTEGRATION_PEERING_USE_REMOTE_GATEWAYS false Uses the hub gateways from the spoke.
HUB_INTEGRATION_EGRESS_NEXT_HOP_IP None Private IP of the hub firewall used as the default route.
HUB_INTEGRATION_EXISTING_ROUTE_TABLE_RESOURCE_ID None Route table to attach instead of creating one.

The external next hop and existing route table are mutually exclusive. Agree return routes and gateway-transit settings with the hub owner. Disable local firewall, Bastion or NAT creation explicitly when the hub supplies those services. DEPLOYMENT_MODE=ailz-integrated does not do this or change hub resources automatically.

Existing resources

Supported resource-ID inputs select reuse instead of creation:

  • EXISTING_VNET_RESOURCE_ID
  • EXISTING_JUMPBOX_RESOURCE_ID
  • EXISTING_BASTION_RESOURCE_ID
  • EXISTING_NAT_GATEWAY_RESOURCE_ID
  • EXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID
  • EXISTING_APPLICATION_INSIGHTS_RESOURCE_ID

Existing private DNS zones, such as hub-owned zones, use EXISTING_PRIVATE_DNS_ZONE_<ZONE>_RESOURCE_ID, where <ZONE> is one of:

COGSVCS, OPENAI, AISERVICES, SEARCH, COSMOS, BLOB, KEYVAULT, APPCONFIG, CONTAINERAPPS, ACR, AZUREMONITOR, OMSOPSINSIGHTS, ODSOPSINSIGHTS, AZUREAUTOMATION, APPINSIGHTS.

Their owner must provide the required VNet links or resolver forwarding separately from network peering. See the BYO hub Private DNS checklist for AMPLS zone mapping (privatelink.monitor.azure.com rather than privatelink.applicationinsights.io, plus privatelink.agentsvc.azure-automation.net), Foundry backing Cosmos DB (privatelink.documents.azure.com), internal APIM (privatelink.azure-api.net) and internal Container Apps <defaultDomain> static A records. With POLICY_MANAGED_PRIVATE_DNS=true, Azure Policy manages DNS records instead of the template. Policy coverage and links need agreement with the DNS owner. Policy-managed DNS and explicit existing-zone IDs are mutually exclusive DNS arrangements.

Foundry backing resources

Foundry Agent Service can create a separate Search, Storage and Cosmos DB set, independently of application Search, document storage and conversation storage. Turning off application Cosmos DB does not remove Foundry backing needs.

The following are native root parameters, not mapped environment variables. Use them only for a compatible, dedicated backing set for the same Foundry instance, not arbitrary shared application stores.

Native parameter Resource to reuse
aiSearchResourceId Foundry backing Search service.
aiFoundryStorageAccountResourceId Foundry backing Storage account.
aiFoundryCosmosDBAccountResourceId Foundry backing Cosmos DB account.

Review the resolved resources and complete Search quota before provisioning. A name override or disabled creation flag does not establish supported reuse.

Outbound access

Running components declare destinations through components[].egress. The selected workloads determine the plan, including optional and additive components. Build-package access is separate. Neither replaces private endpoints, DNS, routes or authorization.

For example, the supplied orchestrator and ingestion declare openaipublic.blob.core.windows.net over HTTPS/443 for cold-cache tokenizer initialization. The UI has no additional fixed destination. Configured SharePoint, SQL, MCP and other custom destinations need their own review.

Policy ownership

Deployment Behavior
NETWORK_ISOLATION=false No component firewall reads or writes; declarations do not create a firewall
Isolated with a deployment-managed firewall Reconciles only marked application rules in AgentLzComponentEgress, priority 400
Isolated with an external firewall Reports required rules and components without egress declarations; never reads or mutates the external policy

For managed policies, the runner needs management-plane subnet reads and Microsoft.Network/firewallPolicies/ruleCollectionGroups/read and write on the deployment policy. The reconciler does not write the parent policy. For external policies, the network owner compares the report with their own policy and applies approved changes. Reporting does not prove that egress is allowed.

Shared destination/protocol/port tuples produce one rule, with sources and ownership combined across components. Removing one owner narrows sources where possible; the rule remains until its final declared owner disappears.

Enabled components without declarations retain their owned requirements. Other rules and collections, including unmarked entries inside the component group, are preserved. Ownership collisions, malformed marked rules, conflicting priorities or concurrent changes fail rather than being silently adopted or overwritten.

Source scope and saved plans

Rules use actual provisioned Container Apps or Foundry agent subnet prefixes, including existing-VNet selections, not the whole VNet or *. Every workload sharing a source subnet can use its union of destinations. Existing platform rules can also permit traffic. Subnet scope is not component isolation.

Preprovision saves the reviewed declaration plan at .azure/<environment-name>/component-egress-plan.json. Postprovision and predeploy resolve actual prefixes and print the plan before managed reconciliation. Deferring postprovision defers its reconciliation, not the predeploy connectivity and plan checks.

A missing or stale saved plan stops apply before Azure access. Do not copy plans or outputs between environments. Use the review procedure for local and resolved read-only reports, and rollback for rule removal before reverting hooks.

Native execution selection

The application separates behavior from hosting and retrieval:

Canonical setting Values or requirement
APPLICATION_MODE conversational (default), workflow or both
ORCHESTRATION_HOST hosted (default) or container_apps; selects native execution host
HOSTED_AGENT_BASE_URL Actual Hosted conversational publication endpoint, when selected
HOSTED_WORKFLOW_BASE_URL Actual separate Hosted workflow publication endpoint, when selected
DURABLE_TASK_SCHEDULER_CONNECTION_STRING Official nonsecret managed-identity backend binding for the durable client/worker

The only public native deployment selectors are ORCHESTRATION_HOST and APPLICATION_MODE. Set them before provision; the UI is included automatically. History, feedback and private attachments independently default to off. Hosted does not enable history; workflow or both always selects UI metadata.

Endpoint/binding rows are actual generated application contracts, not extra host choices. Do not construct scheduler endpoints or set internal host flags.

Set ENABLE_CHAT_HISTORY, ENABLE_USER_FEEDBACK and ENABLE_PRIVATE_ATTACHMENTS with azd env set before provision, then deploy. The lifecycle selects their metadata dependencies and publishes the values under agent-lz; these are not new same-named Bicep or Terraform parameters. Use Enable a product feature for the ordered procedure and keep functional capability declarations separate.

On Hosted, select APPLICATION_MODE=both; the lifecycle prepares a conversational publication with derived process mode conversational and a separate workflow publication with derived process mode workflow, then passes both endpoints to the UI. These process inputs are not extra public deployment selectors.

Each publication's single-mode process input must take precedence over the shared composition value. A common App Configuration store does not turn Hosted both into a single publication.

If attachments are enabled, retain the shared/UI and conversational ENABLE_PRIVATE_ATTACHMENTS=true; only the workflow publication gets false. Workflow-only composition rejects an enabled attachment flag.

On Container Apps, use the official standalone Durable Extension worker and DTS with stable native registration names agent-lz-conversation and agent-lz-research-review. Azure Functions, Dapr and public worker HTTP ingress are not required. Use the actual provisioned nonsecret managed-identity scheduler binding: Endpoint=<actual provisioned output>;TaskHub=agent-lz;Authentication=ManagedIdentity.

Keep the same binding compatible with the native worker and UI client. Do not construct the endpoint from a guessed hostname or change authentication on one side only.

MCP, Foundry IQ and Search are tools/capabilities, not application modes or competing strategy names. Graph, host, identity, persistence and publication changes require compatible deployment; functional parameters follow scoped App Configuration refresh and per-run snapshots. See Agent hosting, Workflows & human input and Application settings.

ENABLE_CHAT_HISTORY and ENABLE_USER_FEEDBACK default to false; workflow mode, both or enabled history, feedback or attachments declares UI metadata storage directly.

DEPLOY_AGENT_APP_MCP=false keeps the optional MCP server unselected. Selecting it derives the consuming MCP connection and registration, not SQL. Explicit MCP_TOOLSETS=["nl2sql"] requires the application catalog. Catalog and SQL access belong to the MCP identity, not the native execution host.

Declare actual tool secret names through NATIVE_TOOL_SECRET_NAMES (default []), a JSON array of names rather than values, and grant only the consuming component. This is a platform grant declaration; the native runtime does not consume NATIVE_TOOL_SECRET_NAMES as a secret-loading or tool-enabling setting.

ENABLE_PRIVATE_ATTACHMENTS=false is the default. Enabling it selects owner-bound inline conversational input and UI metadata, not ingestion or corporate publication. Workflow attachments are unsupported. Admission allows at most three files, 64 KiB per file and 256 KiB for the serialized inline turn. See Private attachments for the MIME, encoding and owner contract.

Native Search, Foundry IQ, MCP and multimodal registration default to off; the integrated MCP lifecycle coordinates registration when selected. Configured infrastructure alone does not onboard SQL or populate its catalog.

Container Apps workload profiles

Container Apps profile_name resolves dynamically against effective workloadProfiles (WORKLOAD_PROFILES or native workloadProfiles) across Bicep and Terraform:

  • "main" when "main" is present in effective workloadProfiles (the default dedicated profile).
  • "Consumption" when overridden to Consumption-only ([] or [{"name": "Consumption", "workloadProfileType": "Consumption"}]).
  • Single custom dedicated profile when both "main" and "Consumption" are omitted and exactly one custom profile is declared.

Explicit per-application profile_name selections are preserved when they match an effective profile. Unknown profile_name values or ambiguous multi-profile configurations without "main" or "Consumption" fail fast before deployment.

Hosted foundation and publication inputs

These inputs prepare hosting resources and metadata. The default application layout and Hosted agents explain the application capabilities.

Variable Default Description
HOSTED_AGENT_NAME agent-app-orchestrator Name of the hosted agent in the Foundry project.
HOSTED_AGENT_IMAGE agent-app-orchestrator Repository name of the agent image in Container Registry.
HOSTED_AGENT_CONTAINER_CPU 2 CPU recorded in provisioning metadata. See the literal-definition constraint below.
HOSTED_AGENT_CONTAINER_MEMORY 4Gi Memory recorded in provisioning metadata. See the same constraint.
GRANT_PROJECT_TRACE_EVALUATION_READER false Opt-in (grantProjectTraceEvaluationReader): grants the Foundry project managed identity Reader on Application Insights and Log Analytics Data Reader on the linked Log Analytics workspace for scheduled trace evaluations (azure_ai_traces).
GRANT_PROJECT_PROTECTED_TRACE_CONTENT_READER false Strictly opt-in (grantProjectProtectedTraceContentReader): grants Privileged Monitoring Data Reader to the Foundry project managed identity with an Azure ABAC v2.0 condition restricting workspace table reads to AppGenAIContent when Protected.

Use the generated compatible host-specific application definitions for registration names, CPU, memory, entrypoints and protocols. Provisioning metadata alone does not resize or republish a running application. A change requires a reviewed definition and compatible publication. See host capacity requirements.

Native package/publication constraints belong in Agent hosting. Owner-bound discovery and product metadata belong in Conversations & files. Process bootstrap values are distinct from dynamically refreshed functional parameters in Application settings.

Deployment controls

Hook execution and application selection use the variables below. The selected application also affects the resource footprint.

Variable Description
BUILD_MODE local uses Docker on the deployment host. acr-task uses Azure Container Registry. Unset values select a mode as described below.
RUN_FROM_JUMPBOX false, 0, no or skip defers isolated post-provision. A truthy value requests private connectivity checks, even when the warning flag is set. It does not provide connectivity.
AZURE_SKIP_NETWORK_ISOLATION_WARNING true defers isolated post-provision configuration unless RUN_FROM_JUMPBOX explicitly requests a connectivity check.
PREFLIGHT_SKIP true skips regional and infrastructure preflight checks, not application-definition or topology validation.
AGENTLZ_REGIONAL_PREFLIGHT_SKIP true skips only the regional quota and availability check.
AGENTLZ_APP_DEFINITION Path to a custom application definition. See Custom applications.

Preflight skip flags are diagnostic controls, not a supported fix for quota, region, permission or network failures.

An explicit BUILD_MODE takes precedence. When it is unset, component scripts first apply recognized USE_DOCKER values: true, 1 or yes select local; false, 0 or no select ACR Tasks. Without either override, network isolation or a configured task pool selects ACR Tasks. Otherwise, usable Docker selects local and unavailable Docker selects ACR Tasks. Explicit local fails if Docker is unusable rather than falling back silently.

Private image builds

The isolated remote build path requires a VNet ACR Task agent pool. DEPLOY_ACR_TASK_AGENT_POOL creates that pool only with isolation enabled. It does not connect the deployment host or grant it build permissions.

Hosted orchestrator image preparation always uses ACR Tasks. BUILD_MODE=local does not change that preparation path or the isolated custom source-build path. See Hosted agents and Custom applications.

For components that support local Docker, a VNet-connected Docker host is an alternative. Hosted image preparation and isolated custom source builds still need the private pool unless an already-built immutable digest avoids the build. Without a pool, the root predeploy guard additionally requires BUILD_MODE=local, and every remaining service must support that choice. See pool diagnostics.

Application-specific package feeds

The root deployment defaults include dependency-verified package feed destinations alongside common language and OS package registries, through the scoped infrastructure build-egress configuration. This is a build-only allowlist, not a runtime or general Internet exception. It does not allow every mirror recorded in a custom application's lockfile.

The exact component commit's resolved URLs and download redirects determine its build needs.

Additional dependencies are declared in parameters.additionalAcrTaskBuildFqdns.value in the root main.parameters.json. This is an explicit array, not an azd environment variable. Provisioning applies it; the connected runner needs the same reviewed parameter file to preserve the setting on later provisions.

The Agent Application orchestrator frontend lockfile uses ms-feed-2.pkgs.visualstudio.com, ms-feed-12.pkgs.visualstudio.com, ms-feed-17.pkgs.visualstudio.com, and ms-feed-25.pkgs.visualstudio.com. Their public package downloads redirect to *.vsblob.vsassets.io. These four exact feeds and the redirect content delivery network (CDN) are included in the Agent Landing Zone default build allowlist. packages.microsoft.com is already included in the OS-package rule and does not need an additional entry.

With extendFirewallForAcrTaskBuilds=true (the default) and an effective ACR Task agent pool, the feeds, redirect CDN, and additional hosts are allowed only from the build-agent subnet over HTTPS on port 443. They are not added to jumpbox, application, or agent-subnet rules. The additional-host array defaults to empty.

Disabling the build-egress extension removes these package rules. Re-enabling it restores them. This egress rule has no DNS-proxy dependency and does not change client DNS.

Do not enable public registry access, allow all Internet egress, disable TLS verification, or change dependency integrity hashes to work around a failed build.

See Package installation fails inside the build pool for diagnosis.

Generated values and script state

These are not freely editable provisioning controls.

Value or record Owner and use
DEPLOYMENT_METADATA Versioned native Bicep/Terraform output for deployment discovery. Contains context, resource states, model/app/identity mappings and named data children, not runtime settings or secret values.
Generated Hosted preparation/deployment state Script-managed handoff, not a public host boolean. Do not set internal flags to bypass missing foundation or image prerequisites.
RETRIEVAL_AUTH_MODE Platform-published native_search authorization contract, not an operator permission bypass. See delegated retrieval.
KEY_VAULT_URI Infrastructure output for the deployed vault, empty when absent. Use the actual URI for bootstrap rather than constructing a cloud DNS suffix.
Local binding records Preserve the original application, provider, group and backend bindings for updates, recovery and removal. Refreshing outputs does not recreate immutable bindings.
COSMOS_VECTOR_SEARCH_ENABLED Application-layer vector capability/retention state, not a new foundation output. Custom applications can explicitly select generic vector capability independently of the reference catalog. The lifecycle preserves the marker for retained NL2SQL catalogs.

For isolated native Blob setup, infrastructure publishes SEARCH_SHARED_PRIVATE_LINKS as a JSON array under agent-lz. Each entry records the owned name, groupId and privateLinkResourceId. It is generated metadata, not an operator override or runtime retrieval setting.

Configuration verifies the exact Search links, target IDs and groups before dependent mutation and native source creation. The gate applies to isolated foundry_iq native azureBlob sources, not searchIndex or inactive native ingestion. It covers the application Search links to document Blob storage (blob) and the deployment Foundry account (openai_account, foundry_account, cognitiveservices_account), not the separate Foundry Search service or unrelated links.

The source-side GET must match the declared name, target and group, and its resource ID when present. Each link must be Approved and Succeeded. Target private endpoint connection requests need an authorized administrator's approval. The workflow never approves them automatically.

Target requests can have opaque or paginated identifiers. Administrators must identify the correct request using the shared-link approval procedure. The runner reuses its existing Azure credential and needs Search shared-link read access, not target connection write access or a new secret. Source readiness does not require the runner to read opaque target requests. See private-link diagnostics for pending approval, propagation, timeouts and retry.

Configuration publication

Use Application settings for runtime configuration tasks and effective-value checks. Conversations & files covers native-state and product-metadata ownership. The declarations below describe how deployment publishes and owns those values.

In appConfig mode, post-provision publishes runtime settings to Azure App Configuration with the label agent-lz. That is the label for platform-owned settings. Reprovisioning is not application publication and must preserve the images and revisions managed by the application deployment workflow.

Deployment tooling reads DEPLOYMENT_METADATA from the selected successful Bicep deployment or the original initialized Terraform backend. It verifies the environment, application, declared inputs, destinations and live resource bindings before dependent changes. Preserve read access to deployment outputs, selected ARM resources and identities, in addition to the configuration permissions required by each selected operation. Terraform also needs its existing Entra-authenticated backend access.

AGENTLZ_PLATFORM_OUTPUTS remains a separate runtime-v1 document published under agent-lz only in appConfig mode. It is not the deployment metadata contract. Hosted preparation/publication handoffs also remain separate.

Configuration ownership and declarations

Terraform manages foundation connections, model metadata and input-driven settings. Shared postprovision queries existing key names, not values, and seeds only missing defaults, preserving existing values, content types and Key Vault-reference metadata.

config.deployment.appconfig updates runtime-owned keys according to the product's single ownership inventory. Its intent comes from the declared parameter document and selected azd environment. Declare additional entries through root parameters.additionalAppConfigurationSettings.value, using name and string value, plus optional label and contentType. Declared labels, content types and literal values are preserved.

Keep the exact reviewed declaration, including required private inputs, on every runner. A missing required declaration fails; outputs and Terraform state are not substitutes. The publisher's optional --input <path> selects that exact parameter document. Do not create per-key azd variables to transport it.

Routing, identity and other authority-controlled conflicts are rejected. Unsupported runtime Key Vault-reference overrides fail explicitly; use the declared secret consumer and provisioning owner for those references.

Effective settings

Change foundation-owned settings in their declared inputs and runtime-owned settings through their publisher; a missing-only default seed does not make every key operator-owned. Custom application definitions validate settings but do not publish them; the application must publish its own runtime settings.

An accepted write is not evidence that a running process loaded the value. Use effective-value checks for precedence and reload behavior.

The Deploy full stack guide provides commands, including secret rotation for versioned versus unversioned Key Vault references. Changing deployment selection, RBAC or infrastructure requires the matching full workflow, not just a key edit.

© 2026 Azure AI Landing Zones