| name | azd-hooks |
| description | azd フック（pre/postprovision）の作成・編集と azure.yaml のフック設定。PostgreSQL Entra ID ユーザー作成の運用パターンを含む。WHEN: hooks/, preprovision, postprovision, azure.yaml, azd provision, azd up, azd deploy, pgaadauth, PostgreSQL user creation, hook script |
azd Hooks
azd フックの実装ルールとテンプレートを扱う。Bicep パラメータ設計・ネットワーク構成は azd-infra-rules を先に参照すること。フックが参照する環境変数は main.bicep の output から受け取る。
フックスクリプトの規約
- hooks は Python +
uv run 前提。.sh/.ps1 を新設しない
- 単一ファイルスクリプトには PEP 723 インラインメタデータ（
# /// script）で依存を宣言する
azure.yaml は posix / windows 両セクションを指定し、run の値を同一の uv run コマンドにする
デプロイ時の注意（azd up / provision）
-
--no-prompt は使わない — preprovision フックがパラメータを自動設定する設計のため、--no-prompt ではパラメータ検証がフック実行前に走り失敗する（azure-dev#3920）
-
認証情報をユーザーに質問しない — pgAdminObjectId / pgAdminLoginName は preprovision フックが az login 済みの認証情報から自動取得する
-
デプロイ前に azd env get-values で未設定パラメータがないか確認する（pgAdminObjectId / pgAdminLoginName は初回実行前に未設定でも想定内 — preprovision が補完する）
-
Azure CLI の rdbms-connect 拡張を事前にインストールしておく — postprovision.py は az postgres flexible-server execute を常に最初に試行する実装になっており、この CLI が使えない場合は即失敗する（NetworkReachabilityError ではなく CalledProcessError として伝播するため、psql フォールバックにも入らない）。初回デプロイ前に以下を実行しておくこと:
az extension add --name rdbms-connect --yes
az extension show --name rdbms-connect --query version -o tsv # インストール確認
rdbms-connect は psycopg2-binary / jsonschema / rpds-py などを含み、Azure CLI の Python 環境に依存モジュールをインストールする。Homebrew 版 Azure CLI など一部環境で No module named 'rpds' 等の依存不足が発生した場合は、Azure CLI の Python で rpds-py を手動インストール（$(dirname "$(readlink -f "$(command -v az)")")/../libexec/bin/python -m pip install rpds-py 相当）して復旧する
postprovision フックの不変条件
hooks/postprovision.py を新規作成・修正する場合は references/postprovision-template.md を先に読むこと。以下の条件を必ず守る:
pgaadauth_create_principal は postgres DB で実行 — ユーザー DB には存在しない（references/postgresql-entra-id-provisioning.md）az postgres flexible-server execute を優先 — psql 未インストール環境でも動作させる。失敗時のみ psql フォールバックresolve_command() でコマンドパスを解決 — Windows で PATH が通っていない環境への対応- IPv4 を強制 — PostgreSQL ファイアウォールは IPv4 のみ。
api.ipify.org で取得
try/finally でファイアウォール規則を確実に削除- SQL 識別子をエスケープ —
replace('"', '""') で " に対応
- private-only 構成では失敗時にスキップ — まず CLI 実行を試み、失敗した場合のみ警告して正常終了（
SystemExit で異常終了させない）
- CLI パス (
execute_sql_via_cli) でも一時ファイアウォール規則を追加する — az postgres flexible-server execute は実行ホストの IP を自動許可しない。enableDatabasePublicAccess=true でも CLI 実行元から PostgreSQL へ到達できず接続タイムアウトする。psql フォールバックと同様、try/finally で firewall-rule create --start-ip-address / firewall-rule delete を囲むこと
preprovision フックの不変条件
hooks/preprovision.py を扱う場合は references/preprovision-template.md を先に読むこと。
azure-identity の AzureCliCredential で Microsoft Graph /me を呼び出し、pgAdminObjectId / pgAdminLoginName を自動取得して azd env set で永続化するsubprocess で az を直接呼ばず Python SDK を使う（Windows での az.cmd パス問題の回避）
azure.yaml のフック設定
hooks:
preprovision:
posix:
shell: sh
run: uv run hooks/preprovision.py
windows:
shell: pwsh
run: uv run hooks/preprovision.py
postprovision:
posix:
shell: sh
run: uv run hooks/postprovision.py
windows:
shell: pwsh
run: uv run hooks/postprovision.py
