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=trueadditionally needsMicrosoft.Resources/subscriptions/resourceGroups/writeat 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/writeat 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:
applicationPeSubnetNameDefault:
application-pe-subnetDedicated application private endpoint subnet name.
AZURE_APPLICATION_PE_SUBNET_PREFIX-
Native root parameter:
applicationPeSubnetPrefixDefault:
192.168.3.128/26Aligned 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_IDEXISTING_JUMPBOX_RESOURCE_IDEXISTING_BASTION_RESOURCE_IDEXISTING_NAT_GATEWAY_RESOURCE_IDEXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_IDEXISTING_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 effectiveworkloadProfiles(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. |
Search shared private links
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.