azd deployでApp Service設定が上書きされる問題の修正方法【1.29.0】

azd deployでコンテナーベースのAzure App Serviceを更新した後、ACR認証やマネージドIDなど、コンテナーイメージとは無関係な設定が消えてしまう場合があります。この問題はAzure Developer CLI 1.29.0で修正されました。次回のデプロイ前に、ローカル環境とCI/CD環境のazdを1.29.0以上へ更新してください。

ただし、azdを更新しても、過去のデプロイですでに消えた設定は自動復元されません。azd 1.27.0から1.28.1でコンテナーベースのApp Serviceへデプロイした場合は、acrUseManagedIdentityCredsやacrUserManagedIdentityIDを含むサイト構成を確認し、必要に応じてBicep、Terraform、Azure CLIなどで復元する必要があります。2026年7月のazdロールアップと1.29.0のリリースノートでは、この修正がPR #9281として案内されています。(Microsoft for Developers)

azd deployで無関係なApp Service設定がリセットされる問題

Azure Developer CLI 1.27.0では、azure.yamlでApp Serviceをコンテナーデプロイ先として指定できる機能が追加されました。

代表的な構成は次のようなものです。

services:
  web:
    host: appservice
    language: docker
    project: ./src

この機能では、azdがコンテナーイメージをAzure Container Registryへプッシュし、App ServiceのlinuxFxVersionを新しいイメージへ更新します。

本来、azd deployが変更すべきなのは、実行するコンテナーイメージの参照だけです。しかし修正前の実装では、イメージと無関係なApp Serviceのサイト構成まで消える可能性がありました。

コンテナーデプロイ機能は1.27.0で追加され、上書き問題は1.29.0で修正されています。公式の安定版リリース履歴から判断すると、主に次のバージョンが確認対象です。(GitHub)

azdのバージョン	判定
1.27.0	影響を受ける可能性あり
1.27.1	影響を受ける可能性あり
1.28.0	影響を受ける可能性あり
1.28.1	影響を受ける可能性あり
1.29.0以降	PR #9281による修正を含む

すべてのApp Serviceデプロイが影響を受けるわけではありません。特に確認が必要なのは、次の条件に当てはまる環境です。

host: appserviceを使用している
language: dockerまたはdocker.pathでコンテナーをビルドしている
LinuxベースのApp Serviceへデプロイしている
App Serviceの構成をBicep、Terraform、Azure CLI、Azure Portalなどで別途設定している
azd 1.27.0から1.28.1でazd deployを実行した
運用スロットまたはデプロイスロットを使用している

ZIPデプロイのApp Serviceは、この修正の対象ではありません。また、PR #9281では運用スロットだけでなくデプロイスロットの処理も修正されています。(GitHub)

発生する症状

この問題で特に影響が大きいのは、Azure Container Registryからコンテナーを取得するためのマネージドID設定です。

代表的なサイト構成には次のものがあります。

プロパティ	役割	本来のデプロイ時の扱い
`linuxFxVersion`	実行するコンテナーイメージを指定する	新しいイメージへ更新する
`acrUseManagedIdentityCreds`	ACRからのイメージ取得にマネージドIDを使う	変更しない
`acrUserManagedIdentityID`	ACRアクセスに使うユーザー割り当てマネージドIDを指定する	変更しない
その他の`siteConfig`	Always On、TLS、ネットワーク、ランタイムなどの構成	変更しない

修正前のazdでは、acrUseManagedIdentityCredsやacrUserManagedIdentityIDなど、azdが送信していないプロパティが消える場合がありました。

その結果、次のような流れで障害が発生します。

azd deploy自体は完了する
App Serviceに設定していたACR用マネージドIDの指定が消える
App Serviceが別のID、または存在しないシステム割り当てIDでACRへ接続しようとする
ACRから新しいイメージを取得できなくなる
コンテナー起動失敗やHTTP 503が発生する

実際の問題報告でも、acrUserManagedIdentityIDがクリアされた後、次のイメージ取得に失敗して503になる流れが示されています。つまり、デプロイコマンドが成功しただけでは、設定が保持されたとは判断できません。 再起動、スケールアウト、インスタンス移動など、次にコンテナーイメージを取得するタイミングで障害が表面化する可能性があります。(GitHub)

App settingsがすべて消える問題とは限らない

ここでいう「サイト設定」は、App ServiceリソースのsiteConfigを指します。

Azure Portalの「環境変数」に表示されるApp settingsとは、管理されるエンドポイントやプロパティが異なります。そのため、今回の問題を「すべての環境変数が削除される不具合」と考えるのは正確ではありません。

まず確認すべきなのは、次のようなApp Service本体の構成です。

ACR認証方式
ACRで使用するマネージドID
コンテナーイメージの参照
ネットワーク関連設定
Always On
TLSやHTTPの設定
デプロイスロット固有の構成

App Service設定が上書きされた原因

修正前のazdは、linuxFxVersionだけを変更する意図で、App Service本体に対するPATCHリクエストを送信していました。

ところが、リクエストには部分的なsiteConfigオブジェクトが入っていました。App Service側でこのネストされたオブジェクトが「既存設定への追記」ではなく「置き換え」として扱われると、リクエストに含まれていないプロパティがクリアされます。

処理の違いを整理すると、次のとおりです。

項目	修正前	azd 1.29.0以降
更新先	App Service本体のサイトレベルPATCH	App Service専用構成エンドポイント
エンドポイント	サイトリソース	`/config/web`
送信内容	部分的な`siteConfig`	`properties.linuxFxVersion`のみ
ACR認証設定	消える可能性あり	保持される
マネージドID設定	消える可能性あり	保持される
デプロイスロット	同じ問題が発生する可能性あり	専用構成エンドポイントで更新
ZIPデプロイ	変更なし	変更なし

PR #9281では、運用環境とデプロイスロットの両方について、/config/webへlinuxFxVersionだけを送信する方式に変更されました。

既存設定を一度取得してから書き戻す方式も採用されていません。取得後に別の処理が設定を変更する競合や、azdが使用するSDKでは認識できない新しいプロパティを失う危険があるためです。(GitHub)

azd deployによるApp Service設定上書きの修正方法

azdのバージョンを確認する

最初に、実際にデプロイを実行する環境でバージョンを確認します。

azd version

次のように1.29.0以上が表示されることを確認してください。

azd version 1.29.0

1.27.0から1.28.1が表示された場合は、コンテナーベースのApp Serviceへ次のデプロイを行う前に更新します。

ローカルPCだけでなく、次の環境も個別に確認する必要があります。

GitHub Actionsの実行環境
Azure Pipelinesのエージェント
セルフホストランナー
開発コンテナー
チームメンバーの開発PC
リリース用の管理端末

ローカルPCのazdを更新しても、CI/CDパイプラインが古いazdをダウンロードしていれば問題は解消しません。

azdを1.29.0以上へ更新する

組み込みの更新コマンドを利用する場合は、次を実行します。

azd update
azd version

azd updateは、winget、Chocolatey、Homebrew、インストールスクリプトなど、最初にazdをインストールした方法を検出して更新処理を呼び分けます。現在、このコマンド自体はベータ扱いです。利用できない場合は、最初にインストールしたパッケージマネージャーやインストールスクリプトで更新してください。(Microsoft Learn)

重要なのは、更新後の出力が次の条件を満たすことです。

azd version 1.29.0

または、1.29.0より新しいバージョンであれば、この回帰修正を含みます。

CI/CDで古いazdの実行を防ぐ

パイプラインでは、デプロイ前に最低バージョンを検査すると再発防止になります。

PowerShellでは、次のようなチェックを追加できます。

$requiredVersion = [version]"1.29.0"
$versionOutput = azd version

if ($versionOutput -notmatch "azd version\s+(\d+\.\d+\.\d+)") {
    throw "azdのバージョンを取得できませんでした: $versionOutput"
}

$currentVersion = [version]$Matches[1]

if ($currentVersion -lt $requiredVersion) {
    throw "azd $currentVersion は使用できません。1.29.0以上へ更新してください。"
}

Write-Host "azd $currentVersion を使用します。"

パイプラインのログにもazd versionを残しておけば、問題が発生したデプロイでどのバージョンが使われたかを後から追跡できます。

すでに上書きされたApp Service設定を確認する

azdの更新は、今後の上書きを防ぐ修正です。すでに削除された設定を自動的に復元する処理ではありません。

過去に影響バージョンでデプロイしている場合は、現在のApp Service構成を確認します。

ACR関連の主要プロパティだけを確認するには、Azure CLIで次を実行します。

az webapp config show -g <resource-group> -n <app-name> --query "{linuxFxVersion:linuxFxVersion,acrUseManagedIdentityCreds:acrUseManagedIdentityCreds,acrUserManagedIdentityID:acrUserManagedIdentityID}" -o yaml

デプロイスロットを確認する場合は、--slotを追加します。

az webapp config show -g <resource-group> -n <app-name> --slot <slot-name> --query "{linuxFxVersion:linuxFxVersion,acrUseManagedIdentityCreds:acrUseManagedIdentityCreds,acrUserManagedIdentityID:acrUserManagedIdentityID}" -o yaml

App Serviceの構成全体を退避する場合は、JSONファイルへ出力します。

az webapp config show -g <resource-group> -n <app-name> -o json > appservice-config.json

az webapp config showは運用スロットとデプロイスロットの両方に対応しています。(Microsoft Learn)

確認結果が次のようになっている場合は注意が必要です。

acrUseManagedIdentityCreds: null
acrUserManagedIdentityID: null
linuxFxVersion: DOCKER|example.azurecr.io/web:latest

もともとユーザー割り当てマネージドIDでACRへアクセスする設計だったにもかかわらず、ACR関連の値だけがnullになっている場合は、今回の上書きが原因である可能性があります。

消えたACRマネージドID設定を復元する

BicepやTerraformを再適用する方法を優先する

App Serviceの構成をBicepやTerraformで管理している場合は、インフラストラクチャコードを正として復元するのが基本です。

Bicepでは、既存のApp Serviceリソース内に次のような設定が定義されているか確認します。

siteConfig: {
  acrUseManagedIdentityCreds: true
  acrUserManagedIdentityID: acrPullIdentity.properties.clientId
}

定義が正しいことを確認したうえで、プロジェクトの通常のプロビジョニング処理を実行します。

azd provision

Terraformを使用している場合は、実行前にプランを確認し、App Service以外に意図しない変更が含まれていないか確認してください。

IaCを再適用する利点は、ACR関連の2項目だけでなく、今回のデプロイで消えた可能性がある他のサイト構成も、定義済みの状態へ戻せることです。

Azure CLIで緊急復旧する

すぐにコンテナーを起動する必要がある場合は、Azure CLIでACR用マネージドIDを再設定できます。

システム割り当てマネージドIDを使う場合は、次のように設定します。

az webapp config set -g <resource-group> -n <app-name> --acr-use-identity true --acr-identity "[system]"

ユーザー割り当てマネージドIDを使う場合は、そのリソースIDを指定します。

az webapp config set -g <resource-group> -n <app-name> --acr-use-identity true --acr-identity <user-assigned-identity-resource-id>

デプロイスロットの場合は、同じコマンドに--slot <slot-name>を追加します。

--acr-use-identityはACRからのイメージ取得にマネージドIDを使う設定です。--acr-identityには、システム割り当てIDを表す[system]またはユーザー割り当てマネージドIDのリソースIDを指定できます。(Microsoft Learn)

ただし、このコマンドだけでは次の設定までは自動修復されません。

App ServiceへのマネージドIDの割り当て
ACRに対するAcrPullロール
プライベートエンドポイントやVNet経由のイメージ取得設定
その他のサイト構成
BicepやTerraformとの設定差分

ユーザー割り当てマネージドIDを使用する場合は、App Serviceに対象IDが割り当てられていること、ACRに対する取得権限があることも確認してください。MicrosoftのApp Serviceドキュメントでは、acrUseManagedIdentityCredsを有効にし、ユーザー割り当てIDの場合はacrUserManagedIdentityIDへクライアントIDを設定する構成が案内されています。(Microsoft Learn)

修正版azdで設定が保持されることを確認する

修復後は、ステージング環境またはデプロイスロットで再デプロイを実施し、前後の構成を比較します。

デプロイ前の構成を保存します。

az webapp config show -g <resource-group> -n <app-name> -o json > before.json

修正版のazdでデプロイします。

azd deploy <service-name>

デプロイ後の構成を保存します。

az webapp config show -g <resource-group> -n <app-name> -o json > after.json

差分を確認します。

git diff --no-index before.json after.json

修正版では、コンテナーの更新に伴ってlinuxFxVersionのイメージ参照が変わる一方、少なくとも次の値は保持される必要があります。

acrUseManagedIdentityCreds
acrUserManagedIdentityID

併せて、次の動作も確認してください。

App Serviceが新しいコンテナーイメージを取得できる
再起動後も正常に起動する
デプロイスロットで正常に起動する
ACRの認証エラーが発生していない
HTTP 503になっていない
BicepやTerraformとの差分が残っていない

応急処置と恒久対応の違い

対応	効果	注意点
azdを1.29.0以上へ更新	今後の上書きを防止する	すでに消えた設定は戻らない
BicepやTerraformを再適用	定義済みの構成を復元する	実行前に変更内容を確認する
Azure CLIでACR設定を再設定	障害を早く復旧できる	IaCとの設定差分が残る可能性がある
postdeployフックで毎回再設定	古いazdでも一時回避できる	修正版導入後は不要な上書き処理になり得る
デプロイスロットで事前検証	本番障害の可能性を下げる	スロット側の設定も個別に確認する

過去の回避策として、azd deploy後にacrUseManagedIdentityCredsやacrUserManagedIdentityIDを再設定するpostdeployフックを追加している場合があります。

azd 1.29.0以上へ更新した後は、そのフックが本当に必要か見直してください。古い回避処理を残したままにすると、将来の構成変更をフック側が再び上書きする可能性があります。

修正時に失敗しやすいポイント

ローカルPCだけを更新する

実際の本番デプロイをCI/CDが行っている場合、開発PCのazdを更新しても効果はありません。パイプライン内でazd versionを実行し、実際のバージョンを確認してください。

azdの更新だけで復旧したと判断する

1.29.0への更新は再発防止です。すでにnullになったマネージドID設定やその他のサイト構成は、IaCまたはAzure CLIで復元する必要があります。

運用スロットだけを確認する

デプロイスロットにも独立した構成があります。ステージングスロットへコンテナーをデプロイしている場合は、--slotを付けてスロット側も確認してください。

App settingsだけを確認する

今回の主な問題はsiteConfigの上書きです。環境変数が残っていても、ACR用マネージドIDやコンテナー構成が消えている可能性があります。

デプロイ成功を正常性の根拠にする

デプロイ直後に既存コンテナーが動いていても、次回のイメージ取得、再起動、スケールアウトで問題が発生することがあります。修正後は、実際に新しいイメージを取得して起動できるところまで確認してください。

azdとApp Serviceの設定上書きを確実に解消する手順

今回の問題に対応する場合は、次の順序で進めると安全です。

azd versionでローカル環境とCI/CD環境のバージョンを確認する
azd 1.27.0から1.28.1を使用している場合は、コンテナーデプロイを一時停止する
すべての実行環境をazd 1.29.0以上へ更新する
App Serviceとデプロイスロットのサイト構成を取得する
acrUseManagedIdentityCredsやacrUserManagedIdentityIDが消えていないか確認する
消えた設定をBicep、Terraform、またはAzure CLIで復元する
修正版azdでテストデプロイを行う
デプロイ前後の構成差分とコンテナー起動を確認する
CI/CDにazdの最低バージョンチェックを追加する
古いpostdeploy回避処理が残っていないか見直す

最優先で行うべきなのは、実際にazd deployを実行する全環境を1.29.0以上へ更新することです。そのうえで、影響バージョンを使った過去のデプロイがあるApp Serviceについて、ACR認証とマネージドIDを中心にサイト構成を点検してください。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

azd deployでApp Service設定が上書きされる問題の修正方法【1.29.0】

azd deployで無関係なApp Service設定がリセットされる問題

発生する症状

App settingsがすべて消える問題とは限らない

App Service設定が上書きされた原因

azd deployによるApp Service設定上書きの修正方法

azdのバージョンを確認する

azdを1.29.0以上へ更新する

CI/CDで古いazdの実行を防ぐ

すでに上書きされたApp Service設定を確認する

消えたACRマネージドID設定を復元する

BicepやTerraformを再適用する方法を優先する

Azure CLIで緊急復旧する

修正版azdで設定が保持されることを確認する

応急処置と恒久対応の違い

修正時に失敗しやすいポイント

ローカルPCだけを更新する

azdの更新だけで復旧したと判断する

運用スロットだけを確認する

App settingsだけを確認する

デプロイ成功を正常性の根拠にする

azdとApp Serviceの設定上書きを確実に解消する手順

この記事を書いた人

コメント

コメントするコメントをキャンセル

azd deployでApp Service設定が上書きされる問題の修正方法【1.29.0】

azd deployで無関係なApp Service設定がリセットされる問題

発生する症状

App settingsがすべて消える問題とは限らない

App Service設定が上書きされた原因

azd deployによるApp Service設定上書きの修正方法

azdのバージョンを確認する

azdを1.29.0以上へ更新する

CI/CDで古いazdの実行を防ぐ

すでに上書きされたApp Service設定を確認する

消えたACRマネージドID設定を復元する

BicepやTerraformを再適用する方法を優先する

Azure CLIで緊急復旧する

修正版azdで設定が保持されることを確認する

応急処置と恒久対応の違い

修正時に失敗しやすいポイント

ローカルPCだけを更新する

azdの更新だけで復旧したと判断する

運用スロットだけを確認する

App settingsだけを確認する

デプロイ成功を正常性の根拠にする

azdとApp Serviceの設定上書きを確実に解消する手順

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル