Azure AI Landing Zones

The template provisions a complete AI application environment. The following core services are included in a standard deployment:

• Microsoft Foundry: AI Foundry account and project with model deployments.
• Azure AI Search: Search service for retrieval-augmented generation (RAG).
• Azure Cosmos DB: Database for conversation history and application data.
• Azure Container Apps: Container runtime with managed environment and workload profiles.
• Azure Container Registry: Private registry for container images.
• Azure Key Vault: Secrets and certificate management.
• Azure App Configuration: Centralized application configuration.
• Azure Storage Account: Blob storage for documents and data.
• Azure Application Insights: Application monitoring and diagnostics.
• Azure Log Analytics: Centralized logging.

When network isolation is enabled, the deployment also provisions:

• Virtual network with private endpoints for all services.
• Network Security Groups (NSGs).
• Azure Bastion for secure VM access.
• Jumpbox VM with pre-installed development tools.
• Private DNS zones for name resolution.

Every service can be individually toggled on or off via deploy parameters.

If your accelerator parameterizes a boolean field that resides inside an AI Landing Zone object parameter, you must use nestedBooleanRewrites in your preProvision script.

Because environment variable substitution (e.g., ${VAR=false}) produces strings, the deployment might fail if the Bicep module expects a real JSON boolean. The preprovision hook uses these rewrites to normalize the value into a proper boolean before the preflight checks and deployment occur.

PowerShell Configuration

Use an array of objects containing Parameter, PropertyPath, EnvironmentVariable, and Default.

Shell (POSIX) Configuration

Use a JSON string assigned to the NESTED_BOOLEAN_REWRITES environment variable.

# PowerShell example
$nestedBooleanRewrites = @(
    @{
        Parameter = 'publicIngress'
        PropertyPath = @('enabled')
        EnvironmentVariable = 'PUBLIC_INGRESS_ENABLED'
        Default = $false
    }
)

# Shell example
NESTED_BOOLEAN_REWRITES='[
  {
    "parameter": "publicIngress",
    "propertyPath": ["enabled"],
    "environmentVariable": "PUBLIC_INGRESS_ENABLED",
    "default": false
  }
]'

When deployAiFoundry=true, deployAfProject=true, and deployAAfAgentSvc=true are all enabled, the landing zone provisions a dedicated set of supporting resources (Azure AI Search, Storage, Cosmos DB, and Key Vault) specifically for the AI Foundry Agent Service. This results in a second set of these resources being deployed alongside your workload's own data path.

To avoid this duplication and reduce costs, you have two primary options:

1. Bring Your Own (BYO) Foundry Data Plane: If you already have a dedicated trio of Search, Storage, and Cosmos DB resources provisioned for Foundry, you can reattach them by providing their resource IDs. This prevents the template from creating new ones.
2. Disable the Agent Service: If you only need model deployments and do not require Foundry agents, set deployAAfAgentSvc=false. This prevents the creation of the second set of Search, Storage, and Cosmos DB resources.

// Option 1: BYO existing Foundry resources
{
  "aiSearchResourceId": "/subscriptions/.../resourceGroups/.../providers/Microsoft.Search/searchServices/my-foundry-search",
  "aiFoundryStorageAccountResourceId": "/subscriptions/.../resourceGroups/.../providers/Microsoft.Storage/storageAccounts/my-foundry-storage",
  "aiFoundryCosmosDBAccountResourceId": "/subscriptions/.../resourceGroups/.../providers/Microsoft.DocumentDB/databaseAccounts/my-foundry-cosmos"
}

// Option 2: Disable Agent Service
{
  "deployAAfAgentSvc": false
}

In network-isolated deployments, Container Apps are private by default and only reachable from within the virtual network. Public Ingress provides a controlled public entry point by provisioning an Azure Application Gateway WAF v2 in front of the private Container Apps environment.

To prevent accidental exposure, Public Ingress uses a two-step workflow involving two distinct operating states:

1. Skeleton mode: Occurs when enabled=true but frontendHostName or sslCertSecretId are empty. In this state, the gateway resources exist, but the Network Security Group (NSG) keeps internet traffic blocked.
2. Live mode: Occurs when enabled=true, frontendHostName and sslCertSecretId are provided, and allowedSourceAddressPrefixes are configured. In this state, HTTPS is enabled on port 443, HTTP is redirected to HTTPS, and only the specified CIDRs can reach the gateway.

This approach ensures that connectivity configuration is managed via code (Bicep/parameters) rather than manual portal edits.

// Example of Skeleton Mode configuration
"publicIngress": {
  "value": {
    "enabled": true
  }
}

// Example of Live Mode configuration
"publicIngress": {
  "value": {
    "enabled": true,
    "frontendHostName": "app.contoso.com",
    "sslCertSecretId": "https://<key-vault-name>.vault.azure.net/secrets/<certificate-name>",
    "allowedSourceAddressPrefixes": ["203.0.113.0/24"]
  }
}

The Platform Landing Zone Integration toggle is the most significant architectural decision in the deployment. It determines if the environment is self-contained or integrated into existing enterprise infrastructure.

Mode: Platform Landing Zone = Yes

Use this when you want to integrate with centrally managed enterprise infrastructure. The following resources are skipped/hidden because they are managed by the platform team:

• Azure Firewall (Egress filtering is managed by the platform)
• Application Gateway (Ingress is managed centrally)
• API Management (AI Gateway is managed centrally)
• Bastion Host (Secure access is provided by the platform)
• WAF Policy
• Associated Public IPs and NSGs
• Private DNS Zone creation (You must select existing DNS zones for each service)

Mode: Platform Landing Zone = No (Default)

Use this for a self-contained environment. The deployment will automatically:

• Deploy all networking, security, and DNS resources.
• Deploy a Bastion Host for secure VM access.
• Create and link Private DNS Zones to the VNet.

The Bicep implementation supports three deployment topologies controlled by the deploymentMode parameter. You can select a mode based on your network requirements and existing infrastructure:

1. Standalone (standalone): The default mode. It creates a self-contained sandbox. It can optionally provision its own network isolation (Bastion, NAT Gateway, and Azure Firewall) if networkIsolation=true is set. Best for sandboxes or teams without a corporate hub.
2. Hub-and-Spoke (test): Achieved by setting deploymentMode to standalone and providing a value for hubIntegration.hubVnetResourceId. This creates a spoke that peers to an existing hub VNet hosting shared services like Bastion or Firewall.
3. AI LZ Integrated (ailz-integrated): Designed for production within an existing Azure Landing Zone. It enforces network isolation and requires an existing hub. The spoke reuses hub services (Firewall, Bastion, Private DNS, Log Analytics) instead of provisioning its own.

All topologies are deployed using the Azure Developer CLI (azd).

# Example concept of parameter selection (actual CLI usage depends on azd context)
# deploymentMode: 'standalone' | 'ailz-integrated'

The deployment process uses two distinct pipelines to ensure validated and gated deployments to Dev, Test, and Prod environments.

CI Pipeline (ci-pipeline.yml)

• Trigger: Pull requests or pushes to main affecting Bicep or pipeline files.
• Purpose: Validates templates without interacting with Azure.
• Actions: Installs Bicep CLI, runs az bicep build and az bicep lint, and publishes a pipeline artifact named bicep-templates.

CD Pipeline (cd-pipeline.yml)

• Trigger: Manual execution only (trigger: none).
• Purpose: Deploys the landing zone using the validated artifact from CI.
• Workflow: Promotes through environments (Dev $\rightarrow$ Test $\rightarrow$ Prod) based on manual parameters. It uses azd provision to handle resource creation and parameter resolution.

flowchart LR
  PR[PR or push to main] --> CI[CI pipeline\nbuild + lint]
  CI --> ART[(bicep-templates\nartifact)]
  ART --> CD[CD pipeline\non demand]
  CD --> Dev[DEV]
  Dev --> Test[TEST]
  Test --> Prod[PROD]