bicep-ptn-aiml-landing-zone Agent工作流

Prerequisites

Required Permissions:

• Azure subscription with Contributor and User Access Admin roles
• Agreement to Responsible AI terms for Azure AI Services

Required Tools:

• Azure CLI
• Azure Developer CLI
• Git

Azure CLI is included as a prerequisite for future pre/post provisioning hooks that may depend on it.

How to Deploy

Choose your preferred deployment method based on project requirements and environment constraints.

Basic Deployment

Quick setup for demos without network isolation.

Initialize the project

azd init -t azure/bicep-ptn-aiml-landing-zone

Sign in to Azure

az login
azd auth login

Add --tenant for az or --tenant-id for azd if you want a specific tenant.

Provision Infrastructure

azd provision

Zero Trust Deployment

For deployments that require network isolation.

Before Provisioning

Enable network isolation in your environment:

azd env set NETWORK_ISOLATION true

Optional: Update other parameters in main.parameters.json or via azd env set before provisioning.

Make sure you're signed in with your Azure user account:

az login
azd auth login

Add --tenant for az or --tenant-id for azd if you want a specific tenant.

Provision Infrastructure

azd provision

Using the Jumpbox VM

1. Reset the VM password in the Azure Portal (required on first access if not set in deployment parameters):

• Go to your VM resource → Support + troubleshooting → Reset password → Set new credentials
• Default username is testvmuser

1. Connect via Azure Bastion

Cloning extra repositories onto the jumpbox

The default install.ps1 bootstrap clones this repository to C:\github\ai-lz and walks manifest.json#components for additional repos. Downstream solution accelerators that consume this landing zone as a Bicep module / git submodule and need their own application repository present on the jumpbox (for private-network data-plane post-provisioning — Cosmos seeding, AI Search index creation, sample data loading, etc.) declare those repos in their overlay manifest.json:

{
  "tag": "v1.0.0",
  "ailz_tag": "v1.1.1",
  "components": [
    {
      "name": "voice-app",
      "repo": "https://github.com/Contoso/voice-app.git",
      "tag": "v0.3.0"
    }
  ]
}

main.bicep derives the URLs/tags/names from _manifest.components at compile time and forwards them to install.ps1 over the CSE commandToExecute. Each entry is cloned into C:\github\<name> on the jumpbox. tag defaults to main; name defaults to the repo URL basename without .git. There are no per-deployment Bicep parameters to wire — manifest.json is the single source of truth, the same one consumers already use to pin their ailz_tag release.

Building and pushing images with network isolation

When networkIsolation=true, the Container Registry is deployed as Premium with publicNetworkAccess=Disabled and is only reachable via its private endpoint. az acr build against the shared Microsoft-managed builder will fail. This landing zone therefore provisions an ACR Tasks agent pool attached to the devops-build-agents-subnet so image builds run inside the VNet and push to the registry over its private endpoint. No Docker client is required (and the jumpbox has no Docker installed by design — see issue #14).

Build and push from the jumpbox (or any client that can reach ARM):

$acr  = (azd env get-values | Select-String '^AZURE_CONTAINER_REGISTRY_ENDPOINT').Line.Split('=')[1].Trim('"').Split('.')[0]
$pool = (azd env get-values | Select-String '^ACR_TASK_AGENT_POOL').Line.Split('=')[1].Trim('"')

az acr build `
  -r $acr `
  --agent-pool $pool `
  -t myapp:latest `
  -f Dockerfile `
  .

Pause billing between builds (default tier S1 is billed per hour whether idle or not):

az acr agentpool update -r <acr> -n <pool> --count 0

Resume before the next build:

az acr agentpool update -r <acr> -n <pool> --count 1

The agent pool can be disabled entirely with deployAcrTaskAgentPool=false if builds are handled by a central CI/CD runner that already reaches the registry's private endpoint.

Firewall egress allow-list (network isolation)

When networkIsolation=true, egress from the jumpbox and workload subnets is forced through the default Azure Firewall. The landing zone codifies the FQDNs required by the default install.ps1 bootstrap and by the ACR Tasks agent pool. The set is split by purpose so you can audit or trim it:

• ACR Tasks control plane and registry: *.azurecr.io, *.data.azurecr.io, and Azure Storage queue/blob/table FQDNs.
• Language/runtime feeds: Python.org, PyPI, npm.
• OS package feeds: Debian, Ubuntu, Yarn, and packages.microsoft.com for Microsoft-supported Linux packages such as msodbcsql18.

If your application build needs additional HTTPS endpoints, add them to the additionalAcrTaskBuildFqdns array parameter. The values are appended to the ACR Tasks HTTPS runtime rule only when networkIsolation, deployAzureFirewall, deployAcrTaskAgentPool, and extendFirewallForAcrTaskBuilds are all enabled, and are scoped to the devops-build-agents-subnet.

Set extendFirewallForJumpboxBootstrap=false to skip the jumpbox-scoped rules when egress is managed centrally by another policy.

ACR Task agent pool platform Network Rules

The table above lists Application (FQDN) rules. The dedicated ACR Tasks agent pool additionally requires unconditional outbound Network Rules (service tags, not FQDNs) for its own platform bootstrap traffic — this is a requirement of the agent pool control plane itself, independent of what a build script does. When networkIsolation, deployAzureFirewall, and deployAcrTaskAgentPool are all enabled, the landing zone adds a AllowAcrTaskAgentPoolPlatform Network Rule Collection scoped to devopsBuildAgentsSubnetPrefix, allowing outbound TCP 443 to AzureKeyVault, Storage, EventHub, and AzureActiveDirectory, and TCP 443/12000 to AzureMonitor, matching the documented ACR Tasks agent pool network requirements. Without these Network Rules the agent pool fails to provision when VNet-injected (see Azure/GPT-RAG#597).

Selecting components for deployment

The following flags support azd env set / ${VAR=default} overrides, in addition to editing main.parameters.json directly. All default to true (unchanged prior behavior):

azd env set DEPLOY_CONTAINER_APPS false

Use only true or false (case-insensitive). Container Apps require the Container Apps Environment; environment-only deployment is supported. Container App API keys additionally require Container Apps, Key Vault, App Configuration, and appRuntimeConfigurationMode=appConfig. In a network-isolated deployment that updates subnets in an existing VNet, NSGs cannot be disabled because doing so would detach existing subnet NSG associations.

These flags select resources for the next incremental deployment. Setting a flag to false does not delete an existing resource or stale App Configuration key created by an earlier deployment; remove decommissioned artifacts explicitly.

AI Foundry deployment modes

deployAiFoundry controls the base AI Foundry account, project, and model deployments. deployAAfAgentSvc controls the Agent Service Standard Setup and its associated AI Search, Storage, Cosmos DB, and Key Vault resources. deploySearchService controls only the workload/RAG Azure AI Search service used by applications.

Use DEPLOY_AAF_AGENT_SVC=false when an external app only needs hosted model inference from Foundry and does not need Agent Service capability hosts or their associated state resources.

aiFoundryDisableLocalAuth / AI_FOUNDRY_DISABLE_LOCAL_AUTH controls whether the AI Foundry account accepts API-key authentication. It defaults to true (local auth disabled, Azure AD-only), matching the account's prior inert default. Set AI_FOUNDRY_DISABLE_LOCAL_AUTH=false only if API-key auth is explicitly required.

Hosted-agent preparation and deployment

Hosted-agent infrastructure uses two additive, accelerator-neutral phases:

- prepareHostedAgent=true provisions the shared prerequisites and exposes the project, registry, network, and private-build handoff before an image or digest exists. It does not request agent deployment. - deployHostedAgent=true implies preparation and additionally enables the typed agent payload. It continues to require an immutable sha256:<64 lowercase hex characters> image digest.

Both flags default to false, so existing parameter files and deployments remain unchanged. The flags are not workload topology switches: they do not create an application UI or replacement workload, and they do not modify containerAppsList, Cosmos DB, Storage, Search, App Configuration, or any other existing workload resource.

When either flag is enabled, the landing zone adds only:

- Foundry Project Manager for the deployment principal on the Foundry project; - the registry-mode-compatible pull role for the Foundry project managed identity on the selected registry (AcrPull for RBAC-only registries or Container Registry Repository Reader for ABAC-enabled registries); and - a typed output handoff containing the project, registry, agent subnet, and private-build context. Image, startup command, runtime, and protocol values are added only when deployment is requested.

The downstream azure.ai.agent service remains responsible for azd deploy. That data-plane operation creates the immutable agent version, dedicated per-agent identity, invocation endpoint, and the agent identity's registry pull assignment. azure.ai.agent is an azd deployment contract rather than an ARM resource type, so this Bicep template intentionally does not fabricate an agent resource or deployment script. See the official hosted-agent azure.yaml reference and pre-built image workflow.

The typed hostedAgent object is sealed and deliberately has no roles field. Arbitrary role names are rejected by preflight rather than silently ignored. After azd deploy creates the dedicated agent identity, the accelerator must assign explicit least-privilege role definition IDs for any external resources that identity needs.

For a fresh deployment, provision the prerequisites first:

azd env set PREPARE_HOSTED_AGENT true
azd env set DEPLOY_HOSTED_AGENT false
azd provision

At this point HOSTED_AGENT_PREPARED=true, HOSTED_AGENT_DEPLOYMENT.enabled=false, and HOSTED_AGENT_DEPLOYMENT.agent=null. The exact Foundry and registry outputs are available so a separate pipeline or VNet-connected build path can build, scan, sign, push, and resolve the immutable digest.

After the image exists, enable deployment intent and pin that digest:

azd env set DEPLOY_HOSTED_AGENT true
azd env set HOSTED_AGENT_NAME sample-agent
azd env set HOSTED_AGENT_IMAGE agents/sample-agent
azd env set HOSTED_AGENT_IMAGE_VERSION sha256:<64-hex-digest>
azd env set HOSTED_AGENT_STARTUP_COMMAND "python main.py"
azd provision

PREPARE_HOSTED_AGENT may remain true or be reset to false; DEPLOY_HOSTED_AGENT=true is always a superset.

After provisioning, map HOSTED_AGENT_DEPLOYMENT (or the exact Foundry and ACR outputs) into the accelerator's azure.ai.agent service and run azd deploy from that accelerator. Preflight rejects mutable image tags and missing Foundry or registry prerequisites. It validates the canonical digest syntax but does not query the registry for manifest existence or signature authenticity; keep those checks in the image build, scan, signing, and promotion pipeline.

Private registry: the landing-zone ACR retains its existing Zero Trust behavior: Premium SKU, private endpoint and DNS integration, and disabled public network access when networkIsolation=true. Building or pushing an image in that mode must happen from a VNet-connected runner, build agent, or jumpbox. Set DEPLOY_ACR_TASK_AGENT_POOL=true when using the landing-zone VNet-injected ACR Tasks pool; its subnet, firewall, private endpoint, and DNS topology remain independently controlled by the existing registry/isolation/pool flags. For an existing ACR, set HOSTED_AGENT_CONTAINER_REGISTRY_ROLE_ASSIGNMENT_MODE=rbac-abac when its role assignment permissions mode is RBAC Registry + ABAC Repository Permissions; the default rbac mode is correct for RBAC Registry Permissions. Its private endpoint, DNS, authentication-as-ARM policy, and network reachability remain the consumer's responsibility. Microsoft currently documents private ACR support for Foundry projects created after June 25, 2026; projects created earlier require the registry to remain reachable over its public endpoint. Verify this platform limitation before a live deployment. See private ACR deployment and RBAC and hosted-agent permissions.

Workload App Configuration passthrough

The landing zone is workload-agnostic. When a solution accelerator needs its own runtime keys stamped into the App Configuration store, it should not require new typed parameters in this template. Use additionalAppConfigurationSettings to publish any number of extra key-values verbatim:

module ailz 'br/public:avm/ptn/aiml/ai-landing-zone:<version>' = {
  params: {
    // ...
    additionalAppConfigurationSettings: [
      { name: 'MY_WORKLOAD_FLAG', value: 'true' }
      { name: 'MY_WORKLOAD_MODE', value: 'hybrid', label: 'prod' }
    ]
  }
}

Each entry accepts name (required), value (required), label (optional, defaults to appConfigLabel), and contentType (optional, defaults to text/plain). Rules and limits:

- Values are stored in plaintext. Do not pass secrets, connection strings, or keys through this parameter. Use Key Vault references for sensitive data. - Each name + label pair must be unique. If an entry collides with a built-in setting the passthrough value wins (the built-in entry is dropped), so an accelerator can also override a stamped default when it needs to. - App Configuration is only populated on non-network-isolated deployments where the runtime config store is App Configuration. In isolated deployments the post-provision step running on the jumpbox is responsible for stamping config, so pass workload keys through that path instead. - When the consumer selects the containerEnv runtime mode (Issue #89) instead of App Configuration, the same entries are injected into every Container App as environment variables. Only name and value are used in that mode (label and contentType are ignored, since env vars have neither), and the same "passthrough wins on collision" precedence applies.

This is the forward-looking way to configure workload settings such as the GPT-RAG Foundry IQ keys below: accelerators publish their own keys through the passthrough instead of the landing zone growing workload-specific parameters.

Optional Public Ingress (Application Gateway WAF v2)

Issue #49. The landing zone provisions the Container Apps environment in internal mode under network isolation, so its apps are unreachable from the public Internet by default. Some workloads need a controlled, audited public entry point (a tester, a partner integration, a public demo). The optional publicIngress feature deploys an Application Gateway WAF v2 in front of the internal ACA environment without changing any of the existing internal topology.

⚠️ Cost warning. Enabling this feature deploys WAF_v2 + a Standard Public IP, which incur hourly charges even when idle (~USD 240/month for the gateway alone, region-dependent). Keep publicIngress.enabled = false unless actively needed and tear the stack down with azd down (or delete the resources manually) when the access window ends. Setting publicIngress.enabled back to false after a deploy will NOT delete the resources — azd/ARM incremental deployments only stop managing them.

Default state: disabled. No public-ingress resources are provisioned.

Parameter contract (publicIngressType exported from main.bicep):

publicIngress: {
  enabled: bool                              // master toggle, default false
  backendAppIndex: int?                      // index into containerAppsList; default 0
  frontendHostName: string?                  // e.g., 'app.contoso.com' — required to activate HTTPS
  sslCertSecretId: string?                   // versionless Key Vault secret URI — required to activate HTTPS
  allowedSourceAddressPrefixes: string[]?    // CIDRs allowed to reach :443; empty list = deny-all
  wafMode: ('Prevention' | 'Detection')?     // default 'Prevention'
  wafCustomRules: object[]?                  // merged with OWASP CRS 3.2 managed ruleset
  capacity: object?                          // default { minCapacity: 0, maxCapacity: 2 }
  sslPolicy: object?                         // default Azure baseline
}

Resources deployed when enabled = true (only effective with networkIsolation, deployContainerEnv, and at least one entry in containerAppsList):

Two operational states:

1. Skeleton mode (enabled=true and either sslCertSecretId or frontendHostName empty) - Gateway exists with a single HTTP:80 listener routed to the backend. - NSG denies all Internet inbound (port 80 is never opened by the NSG). - The skeleton is inert: no client can reach it from the Internet until the operator transitions to live mode.

2. Live mode (enabled=true with both sslCertSecretId and frontendHostName set, plus allowedSourceAddressPrefixes non-empty) - HTTPS:443 listener using the Key Vault certificate (the AGW UAI reads it via Key Vault Secrets User). - HTTP:80 becomes a permanent HTTP→HTTPS redirect. - NSG allows TCP/443 from the supplied source CIDRs only.

Post-deploy runbook (provider-agnostic DNS + jumpbox ACME):

1. Workstation (DNS provider side): choose your DNS provider/registrar and prepare your hostname (example: app.contoso.com). No provider-specific integration is required in this landing zone. 2. Jumpbox (certificate issuance/import side): use the built-in ACME client installed by install.ps1 at C:\tools\win-acme\wacs.exe (DNS-01 flow), then import the resulting certificate into the landing-zone Key Vault. The jumpbox MI has Key Vault Certificates Officer for this workflow. 3. Workstation (DNS provider side): create/update the public DNS A record for the hostname pointing at PUBLIC_INGRESS_PUBLIC_IP (deployment output). 4. Capture the versionless Key Vault secret URI for the certificate (https://<kv>.vault.azure.net/secrets/<name>), then set operator parameters in main.parameters.json (or via azd env set followed by an edit since publicIngress is an aggregate object):

   "publicIngress": {
      "value": {
       "enabled": true,
       "frontendHostName": "app.contoso.com",
       "sslCertSecretId": "https://<kv>.vault.azure.net/secrets/<name>",
        "allowedSourceAddressPrefixes": ["203.0.113.0/24"]
      }
    }
    

Teardown: run azd down to remove the entire deployment, or delete the gateway/PIP/WAF policy/NSG/UAI manually. As stated above, flipping enabled back to false and re-provisioning will not delete the resources due to ARM incremental deployment semantics.

Outputs surfaced by main.bicep:

In addition, the landing zone now surfaces a small set of outputs that consumers (and this module) depend on: APP_GATEWAY_SUBNET_RESOURCE_ID, VNET_RESOURCE_ID, KEY_VAULT_RESOURCE_ID, KEY_VAULT_NAME, LOG_ANALYTICS_RESOURCE_ID, and CONTAINER_APP_INTERNAL_FQDN.