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.

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.