App Service と Azure Functions の App Configuration 参照を使用する

[アーティクル]
03/30/2023

このトピックでは、コードを変更せずに App Service または Azure Functions アプリケーションの構成データを使用する方法を紹介します。 Azure App Configuration は、アプリケーション構成を一元的に管理するサービスです。さらに、これは、時間やリリースを超えた構成値のための効果的な監査ツールでもあります。

アプリに App Configuration へのアクセス権を付与する

App Service で App Configuration 参照の使用を開始するには、まず App Configuration ストアが必要になります。また、そのストア内の構成キー値にアクセスするためのアクセス許可をアプリに付与します。

App Configuration のクイックスタートに従って App Configuration ストアを作成します。
アプリケーション用のマネージド ID を作成します。

App Configuration 参照では、アプリのシステム割り当て ID が既定で使用されますが、ユーザー割り当て ID を指定できます。
新しく作成された ID に、App Configuration ストアに対する適切なアクセス許可セットを設定できるようにします。ストアのロールの割り当てを更新します。この ID に、リソースに対するスコープを設定して、App Configuration Data Reader ロールを割り当てます。

ユーザー割り当て ID を使用して App Configuration ストアにアクセスする

一部のアプリでは、作成時の、システム割り当て ID をまだ使用できないときに、構成の参照が必要になることがあります。このような場合は、ユーザー割り当て ID を作成し、App Configuration ストアへのアクセス権を事前に与えることができます。 App Configuration ストアのユーザー割り当て ID を作成するには、これらの手順に従います。

ユーザー割り当て ID にアクセス許可を付与した後、次の手順のようにします。

まだ行っていない場合は、アプリケーションに ID を割り当てます。

keyVaultReferenceIdentity プロパティにユーザー割り当て ID のリソース ID を設定することで、この ID を使用して App Configuration 参照操作を行うようにアプリを構成します。プロパティの名前には keyVault が含まれていますが、この ID は App Configuration 参照にも適用されます。

userAssignedIdentityResourceId=$(az identity show -g MyResourceGroupName -n MyUserAssignedIdentityName --query id -o tsv)
appResourceId=$(az webapp show -g MyResourceGroupName -n MyAppName --query id -o tsv)
az rest --method PATCH --uri "${appResourceId}?api-version=2021-01-01" --body "{'properties':{'keyVaultReferenceIdentity':'${userAssignedIdentityResourceId}'}}"

この構成は、このアプリのすべての参照に適用されます。

参照されるキーコンテナーへのアクセス許可をアプリに付与する

Azure App Configuration には、未加工の構成値を格納するだけでなく、Key Vault 参照を格納するための独自の形式があります。 App Configuration 参照の値が App Configuration ストア内の Key Vault 参照の場合は、指定されているキーコンテナーにアクセスするためのアクセス許可もアプリに必要になります。

注意

Azure App Configuration の Key Vault 参照の概念を、App Service や Azure Functions の Key Vault 参照の概念と混同しないでください。アプリでは任意の組み合わせでこれらを使用できますが、注意すべき重要な違いがいくつかあります。コンテナーをネットワーク制限する必要がある場合、またはアプリを定期的に最新バージョンに更新する必要がある場合は、App Configuration 参照を使用するのではなく、App Service や Azure Functions の直接的なアプローチを使用することを検討してください。

App Configuration 参照に使用した ID を特定します。コンテナーへのアクセス権は、その同じ ID に付与する必要があります。
その ID のアクセスポリシーを Key Vault に作成します。このポリシーで "Get" シークレットアクセス許可を有効にします。 "承認されているアプリケーション" または applicationId 設定を構成しないでください。これは、マネージド ID との互換性がないためです。

参照構文

App Configuration 参照の形式は @Microsoft.AppConfiguration({referenceString}) です。この {referenceString} は下記のように置き換えます。

参照文字列の各部分	説明
Endpoint=endpoint;	Endpoint は、参照文字列の必須部分です。 Endpoint の値には、App Configuration リソースの URL を含める必要があります。
Key=keyName;	Key は、参照文字列の必須部分を構成します。 Key の値は、アプリ設定に割り当てるキーの名前にする必要があります。
Label=label	Label 部分は、参照文字列では省略可能です。 Label は、Key に指定されたキーのラベルの値にする必要があります

たとえば、Label を含む完全な参照は次のようになります。

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)

または、Label を含まない場合は次のようになります。

@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)

アプリの構成を変更してサイトが再起動されると、参照されている、App Configuration ストアのキー値がすべて直ちに再フェッチされます。

Note

App Configuration でキー値が更新されている場合、これらの値の自動更新/再フェッチは現在サポートされていません。

App Configuration からのソースアプリケーション設定

App Configuration 参照はアプリケーション設定の値として使用できるため、構成データをサイト構成ではなく App Configuration に保持できます。アプリケーション設定と App Configuration のキー値はどちらも保存時に安全に暗号化されます。一元化された構成管理機能が必要な場合は、構成データを App Configuration に入れる必要があります。

アプリ設定に App Configuration 参照を使用するには、設定の値として参照を設定します。アプリでは、通常どおり、そのキーを使用して構成値を参照できます。コードに変更を加える必要はありません。

ヒント

App Configuration 参照を使用するほとんどのアプリケーション設定は、環境ごとに別個のストアまたはラベルを用意する必要があるため、スロット設定としてマークする必要があります。

Azure Files のマウントに関する考慮事項

アプリでは、WEBSITE_CONTENTAZUREFILECONNECTIONSTRING アプリケーション設定を使用して、Azure Files をファイルシステムとしてマウントできます。この設定には、アプリを正しく開始できることを確認するための追加の検証チェックがあります。プラットフォームでは、Azure Files 内にコンテンツ共有があることを前提としており、WEBSITE_CONTENTSHARE 設定で指定されていない場合は既定の名前を想定します。これらの設定を変更する要求がある場合、プラットフォームでは、このコンテンツ共有が存在するかどうかの検証を試み、存在しない場合は作成を試みます。コンテンツ共有が見つからないか、作成できない場合、要求はブロックされます。

この設定に対して App Configuration 参照を使用する場合、受信要求の処理中に接続自体を解決できないため、この検証チェックは既定で失敗します。この問題を回避するために、WEBSITE_SKIP_CONTENTSHARE_VALIDATION を "1" に設定して検証をスキップできます。この設定により、すべてのチェックがバイパスされ、コンテンツ共有は自動的に作成されなくなります。事前に作成されていることを確認する必要があります。

注意事項

検証をスキップし、接続文字列またはコンテンツ共有が無効である場合、アプリは正常に開始できず、HTTP 500 エラーのみを処理します。

サイト作成の途中で、マネージド ID のアクセス許可が伝達されていないか、仮想ネットワーク統合がセットアップされていないことが原因で、コンテンツ共有のマウント試行が失敗する可能性もあります。必要なセットアップに対応するために、デプロイテンプレートの後半まで Azure Files のセットアップを先送りすることができます。詳細については、「Azure Resource Manager デプロイ」を参照してください。 App Service では、Azure Files がセットアップされるまでは既定のファイルシステムを使用し、ファイルはコピーされないため、Azure Files がマウントされる前の一時的な期間中はデプロイ試行が発生しないようにしてください。

Azure Resource Manager デプロイ

Azure Resource Manager テンプレート経由でリソースデプロイを自動化するとき、この機能を動作させるには、場合によっては特定の順序で依存関係を並べる必要があります。注意すべきことですが、サイト定義の siteConfig プロパティを使用するのではなく、アプリケーション設定を独自のリソースとして定義する必要があります。これはサイトを最初に定義する必要があるからです。そうすることで、サイトと共にシステム割り当て ID が作成され、アクセスポリシーで使用できます。

App Configuration 参照を含む関数アプリの擬似テンプレートの例を以下に示します。

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        }
    },
    "variables": {
        "functionAppName": "DemoMBFunc",
        "appConfigStoreName": "DemoMBAppConfig",
        "resourcesRegion": "West US2",
        "appConfigSku": "standard",
        "FontNameKey": "FontName",
        "FontColorKey": "FontColor",
        "myLabel": "Test",
        "App Configuration Data Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '516239f1-63e1-4d78-a4de-a74fb236a071')]"
    },
    "resources": [
        {
            "type": "Microsoft.Web/sites",
            "name": "[variables('functionAppName')]",
            "apiVersion": "2021-03-01",
            "location": "[variables('resourcesRegion')]",
            "identity": {
                "type": "SystemAssigned"
            },
            //...
            "resources": [
                {
                    "type": "config",
                    "name": "appsettings",
                    "apiVersion": "2021-03-01",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
                    ],
                    "properties": {
                        "WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')')]",
                        "WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')')]",
                        "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                        //...
                    }
                },
                {
                    "type": "sourcecontrols",
                    "name": "web",
                    "apiVersion": "2021-03-01",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
                    ]
                }
            ]
        },
        {
            "type": "Microsoft.AppConfiguration/configurationStores",
            "name": "[variables('appConfigStoreName')]",
            "apiVersion": "2019-10-01",
            "location": "[variables('resourcesRegion')]",
            "sku": {
                "name": "[variables('appConfigSku')]"
            },
            //...
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
            ],
            "properties": {
            },
            "resources": [
                {
                    "type": "keyValues",
                    "name": "[variables('FontNameKey')]",
                    "apiVersion": "2021-10-01-preview",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"

                    ],
                    "properties": {
                        "value": "Calibri",
                        "contentType": "application/json"
                    }
                },
                {
                    "type": "keyValues",
                    "name": "[variables('FontColorKey')]",
                    "apiVersion": "2021-10-01-preview",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"

                    ],
                    "properties": {
                        "value": "Blue",
                        "contentType": "application/json"
                    }
                }
            ]
        },
        {
            "scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]",
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2020-04-01-preview",
            "name": "[parameters('roleNameGuid')]",
            "properties": {
                "roleDefinitionId": "[variables('App Configuration Data Reader')]",
                "principalId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.principalId]",
                "principalType": "ServicePrincipal"
            }
        }
    ]
}

Note

この例では、ソース管理デプロイはアプリケーション設定に依存します。アプリ設定は非同期で更新されるため、通常、これは安全ではありません。ただし、WEBSITE_ENABLE_SYNC_UPDATE_SITE アプリケーション設定を含めているため、同期で更新されます。つまり、ソース管理デプロイは、アプリケーションが完全に更新されたときにのみ開始されます。他のアプリの設定については、「Azure App Service の環境変数とアプリ設定」を参照してください。

App Configuration 参照のトラブルシューティング

参照が正しく解決されない場合は、代わりに参照値が使用されます。アプリケーションの設定では、値の構文が @Microsoft.AppConfiguration(...) である環境変数が作成されます。アプリケーションでは代わりに構成値を想定していたため、これによってエラーが発生するおそれがあります。

通常、このエラーは App Configuration アクセスポリシーの構成が正しくないために発生すると考えられます。ただし、参照内の構文エラーや、ストア内に構成キー値が存在しないことが原因で起こる場合もあります。

次の手順

App Service から Key Vault シークレットを参照する

次の方法で共有

App Service と Azure Functions の App Configuration 参照を使用する

アプリに App Configuration へのアクセス権を付与する

ユーザー割り当て ID を使用して App Configuration ストアにアクセスする

参照されるキーコンテナーへのアクセス許可をアプリに付与する

参照構文

App Configuration からのソースアプリケーション設定

Azure Files のマウントに関する考慮事項

Azure Resource Manager デプロイ

App Configuration 参照のトラブルシューティング

次の手順

フィードバック

その他のリソース

次の方法で共有

App Service と Azure Functions の App Configuration 参照を使用する

アプリに App Configuration へのアクセス権を付与する

ユーザー割り当て ID を使用して App Configuration ストアにアクセスする

参照されるキー コンテナーへのアクセス許可をアプリに付与する

参照構文

App Configuration からのソース アプリケーション設定

Azure Files のマウントに関する考慮事項

Azure Resource Manager デプロイ

App Configuration 参照のトラブルシューティング

次の手順

フィードバック

その他のリソース

参照されるキーコンテナーへのアクセス許可をアプリに付与する

App Configuration からのソースアプリケーション設定