| name | azd-infra-rules |
| description | azd 前提の IaC ルール。Bicep、azure.yaml、hooks をまたぐ repo 固有ルールを扱う。WHEN: infra/, .bicep, azure.yaml, hooks/, preprovision, postprovision, targetScope, main.parameters.json, enableDatabasePublicAccess |
azd Infra Rules
このスキルの役割
このファイルにはリポジトリ固有の設計判断だけを書く。汎用的な Bicep / Azure の推奨事項は外部ソースに委譲する。
- Azure 系プラグイン — Azure 全般の構成判断、リソース選定、サービス固有の定番構成
- AVM の WAF-aligned 例 — リソースごとの実装パターン
- GitHub MCP Server で
repo:Azure/bicep-registry-modules WAF-aligned {resource type} を検索
- Microsoft Learn — Bicep の一般論とリソース スキーマ
microsoft_docs_fetch(url="https://learn.microsoft.com/azure/azure-resource-manager/bicep/best-practices")microsoft_docs_search(query="{resource type} bicep template")
このリポジトリ固有のルール
詳細な背景は references/azd-infra-rules.md を参照。
- azd 前提のテンプレートにする —
targetScope = 'subscription' とし、リソース グループ作成をテンプレートに含める
- azd 標準パラメータを省略しない —
environmentName と location を必須で受け取る
environmentName は用途を示す短い名前にする — poc、dev、prod など。リソース名が {prefix}-${workloadName}-${environmentName}（例: app-myproj-poc）で構成されるため、ディレクトリ名のデフォルトではなく azd init -e poc のように明示的に指定する- グローバル一意が必要なリソースには
resourceToken サフィックスを付ける — uniqueString(subscription().subscriptionId, environmentName, location) の先頭5文字を App Service・PostgreSQL などホスト名がグローバル一意なリソースに付与する。RG・Log Analytics など一意性が不要なリソースには付けない
- パラメータ ファイルは
main.parameters.json を優先 — この repo では azd テンプレートとの一貫性と @minLength との相性を優先する
azd env set で制御するパラメータは main.parameters.json にマッピング必須 — Bicep パラメータにデフォルト値があっても、main.parameters.json に "${VAR_NAME=default}" エントリがなければ azd env set の値は Bicep に渡らない。azd env set での上書きを想定するパラメータは必ずマッピングを追加すること- Bicep outputs を hooks /
azure.yaml の契約として扱う — フックが参照する値は main.bicep の output に明示する
- VNet・App Service VNet 統合・PostgreSQL PE は常に作成する — PoC でも本番でもネットワーク構成は同じ。App Service → PostgreSQL は常に PE 経由のプライベート接続とする。PoC で性能基礎値を測るには本番と同じ通信経路が必要なため
- PostgreSQL の DB パブリックアクセスは
enableDatabasePublicAccess の単一 bool で制御 — true（PoC）: PE に加えてパブリックアクセスも有効にし、開発者が psql で直接接続できるようにする。false（本番）: パブリックアクセス無効、PE のみ。enableVnetIntegration と postgresPublicAccess を独立パラメータにしない。デフォルト値は false（Secure-by-default） — PoC では azd env set enableDatabasePublicAccess true で明示的に有効化する
- Azure Policy が管理するリソース構成と競合させない — サブスクリプションやマネジメントグループの Azure Policy がリソース構成（診断設定、タグ、ネットワーク制限など）を強制している場合、Bicep の定義を Policy に合わせる。Policy と矛盾するテンプレートはデプロイ失敗または意図しないドリフトを引き起こす
- Bicep でリソースを追加したら診断設定を必ず作成する — 対象リソースごとに
Microsoft.Insights/diagnosticSettings を作成し、ログとメトリクス（AllMetrics）を Log Analytics ワークスペースに送信する。ログカテゴリは対象リソースの Microsoft Learn ドキュメントで確認すること。ただし Bicep ビルドでは親 RP の適合性を検知できないため、診断設定を追加する前に Supported categories for Azure Monitor resource logs で対象リソース種別の掲載を必ず確認する — 非対応例: Microsoft.Network/privateEndpoints、Microsoft.Network/privateDnsZones、Microsoft.Storage/storageAccounts 本体（サブリソース側で設定）。詳細は references/azd-infra-rules.md の「診断設定を追加する前の事前確認」を参照
- ログの取り込みコスト削減が求められる場合は Basic テーブルプランと診断設定のカテゴリ絞り込みを検討する — 詳細は references/azd-infra-rules.md の「ログ取り込みコストの最適化」セクションを参照
- App Service は Premium プランを原則とする — リモートビルドのタイムアウト回避と本番同等の性能基礎値取得のため。Basic / Standard は使わない
- DB パブリックアクセス無効の構成ではフック到達性に注意する —
enableDatabasePublicAccess: false でも、azd を実行する端末が VNet にアクセスできていれば postprovision フックは成功する。到達できない場合はフックが警告を出して正常終了し、VNet 内から別途プリンシパルを作成する。実際の作成手順は azd-hooks スキル を参照
PostgreSQL Flexible Server の repo 固有メモ
汎用的な Bicep パターン（authConfig、administrators、認証方式の選択など）は AVM と Microsoft Learn を参照すること。ここにはこの repo で繰り返し踏みやすい点だけ残す。
- Entra 管理者設定は
dependsOn を明示する — 開発者 IP 用ファイアウォール規則と postgresDatabase の後でないと accessible にならず失敗することがある
0.0.0.0 ファイアウォール規則（AllowAllAzureServicesAndResourcesWithinAzureIps）は使わない — この規則は他テナントの Azure リソースからも接続を許可してしまう。開発者が psql で直接接続するには、開発者の IP アドレスをパラメータ（例: developerIpAddress）で受け取り、明示的なファイアウォール規則を作成する。postprovision フックの一時ファイアウォール規則と役割を混同しないこと
App Service Python の可観測性
ApplicationInsightsAgent_EXTENSION_VERSION: ~3 を appSettings に含める — Python on Linux App Service では APPLICATIONINSIGHTS_CONNECTION_STRING だけではテレメトリが収集されない。ApplicationInsightsAgent_EXTENSION_VERSION を ~3 に設定して初めて自動計装エージェントが有効になる- psycopg (v3) の DB 依存関係テレメトリには OTel パッケージが必要 — 自動計装が自動検出するのは
psycopg2 のみ。psycopg v3 を使う場合は opentelemetry-instrumentation-psycopg を pyproject.toml の依存に追加すること。App Service はインストール済みの OTel インストルメンテーションを自動検出する
詳細は references/azd-infra-rules.md の「App Service Python の可観測性」セクションを参照。
App Service で FastAPI を起動する (gunicorn + uvicorn worker)
- uvicorn worker は
uvicorn-worker パッケージを使う — uvicorn 0.30+ で uvicorn.workers モジュールが削除済。appCommandLine は -k uvicorn_worker.UvicornWorker（アンダースコア区切り）とし、pyproject.toml の依存に uvicorn-worker>=0.2 を追加する。古い uvicorn.workers.UvicornWorker を指定すると class uri ... invalid or not found で起動失敗する
詳細と python -m uvicorn 代替案は references/azd-infra-rules.md の「起動コマンド (appCommandLine)」セクションを参照。
App Service のセキュリティ必須設定
- SCM / FTP 基本認証を無効化する — azd は Entra ID 認証でデプロイするため、発行資格情報（基本認証）は不要。
basicPublishingCredentialsPolicies で scm と ftp の両方を allow: false に設定すること。ftpsState: 'Disabled' だけでは SCM 基本認証は無効にならない（独立した制御）
App Service Python デプロイの必須チェック
アプリコード生成・Bicep 変更時は references/azd-infra-rules.md の「App Service Python アプリのデプロイ」セクションを確認すること。
Validation
Bicep ファイルを追加・変更したら、少なくともビルド検証を実行すること。
az bicep build --file <file>
