Bagikan melalui

Menggunakan referensi App Configuration untuk App Service dan Azure Functions

  • Artikel

Topik ini memperlihatkan cara bekerja dengan data konfigurasi di aplikasi Azure App Service atau Azure Functions tanpa perlu mengubah kode apa pun. Azure App Configuration adalah layanan untuk mengelola konfigurasi aplikasi secara terpusat. Selain itu, ini adalah alat audit yang efektif untuk nilai konfigurasi Anda dari waktu ke waktu atau rilis.

Memberikan aplikasi Anda akses ke Azure App Configuration

Untuk mulai menggunakan referensi App Configuration di App Service, pertama Anda memerlukan penyimpanan App Configuration, dan memberikan izin pada aplikasi Anda untuk mengakses nilai kunci konfigurasi di penyimpanan.

  1. Buat penyimpanan App Configuration dengan mengikuti Mulai cepat App Configuration.

  2. Buat identitas terkelola untuk aplikasi Anda.

    Referensi Azure App Configuration secara default akan menggunakan identitas yang ditetapkan oleh sistem aplikasi, tetapi Anda dapat menentukan identitas yang ditetapkan oleh pengguna.

  3. Aktifkan identitas yang baru dibuat agar memiliki set izin akses yang tepat di penyimpanan App Configuration. Perbarui penetapan peran untuk penyimpanan Anda. Anda akan menetapkan peran App Configuration Data Reader ke identitas ini, yang tercakup atas sumber daya.

Akses Penyimpanan App Configuration dengan identitas yang ditetapkan pengguna

Beberapa aplikasi perlu merujuk konfigurasi pada saat waktu pembuatan, ketika identitas yang ditetapkan sistem masih belum tersedia. Dalam kasus ini, identitas yang ditetapkan pengguna dapat dibuat dan diberikan akses ke penyimpanan App Configuration terlebih dahulu. Ikuti langkah-langkah ini untuk membuat identitas yang ditetapkan pengguna untuk penyimpanan App Configuration.

Setelah Anda memberikan izin ke identitas yang ditetapkan oleh pengguna, ikuti langkah-langkah berikut:

  1. Tetapkan identitas ke aplikasi Anda, jika Anda belum melakukannya.

  2. Konfigurasikan aplikasi untuk menggunakan identitas ini untuk operasi referensi App Configuration dengan mengatur properti keyVaultReferenceIdentity ke ID sumber daya identitas yang ditetapkan oleh pengguna. Meskipun properti memiliki keyVault dalam namanya, identitas juga akan berlaku untuk referensi 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}'}}"

Konfigurasi ini akan berlaku untuk semua referensi dari aplikasi ini.

Memberikan akses aplikasi Anda ke brankas kunci yang dirujuk

Selain menyimpan nilai konfigurasi mentah, Azure App Configuration memiliki formatnya sendiri untuk menyimpan referensi Key Vault. Jika nilai referensi App Configuration adalah referensi Key Vault di penyimpanan App Configuration, aplikasi Anda juga harus memiliki izin untuk mengakses brankas kunci yang ditentukan.

Catatan

Konsep referensi Azure App Configuration Key Vault tidak boleh dikacaukan dengan konsep referensi App Service dan Azure Functions Key Vault. Aplikasi Anda mungkin menggunakan kombinasi ini, tetapi ada beberapa perbedaan penting yang perlu diperhatikan. Jika vault Anda perlu dibatasi jaringan atau Anda memerlukan aplikasi untuk memperbarui secara berkala ke versi terbaru, pertimbangkan untuk menggunakan pendekatan langsung App Service dan Azure Functions alih-alih menggunakan referensi App Configuration.

  1. Identifikasi identitas yang Anda gunakan untuk referensi App Configuration. Akses ke vault harus diberikan ke identitas yang sama.

  2. Buat kebijakan akses di Key Vault untuk identitas tersebut. Aktifkan izin rahasia "Get" pada kebijakan ini. Jangan konfigurasi "aplikasi resmi" atau pengaturan applicationId, karena tidak kompatibel dengan identitas terkelola.

Sintaks referensi

Referensi App Configuration adalah formulir @Microsoft.AppConfiguration({referenceString}), di mana {referenceString} digantikan oleh yang di bawah ini:

Bagian string referensi Deskripsi
Titik akhir=endpoint; Titik akhir adalah bagian yang diperlukan dari string referensi. Nilai untuk Titik Akhir harus memiliki url sumber daya App Configuration Anda.
Kunci=keyName; Kunci membentuk bagian yang diperlukan dari string referensi. Nilai untuk Kunci harus merupakan nama Kunci yang ingin Anda tetapkan ke pengaturan Aplikasi.
Label=label Bagian Label bersifat opsional dalam string referensi. Label harus berupa nilai Label untuk Kunci yang ditentukan dalam Kunci

Misalnya, referensi lengkap dengan Label akan terlihat seperti berikut,

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

Atau tanpa Label:

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

Setiap perubahan konfigurasi pada aplikasi yang menghasilkan hidupkan ulang situs menyebabkan pengambilan ulang segera dari semua nilai kunci yang direferensikan dari penyimpanan App Configuration.

Catatan

Refresh/pengambilan ulang otomatis nilai-nilai ini ketika nilai kunci telah diperbarui di App Configuration, saat ini tidak didukung.

Pengaturan Aplikasi Sumber dari App Configuration

Referensi App Configuration dapat digunakan sebagai nilai untuk Pengaturan Aplikasi, memungkinkan Anda menyimpan data konfigurasi dalam App Configuration alih-alih konfigurasi situs. Pengaturan nilai kunci Aplikasi dan App Configuration dienkripsi dengan aman saat tidak aktif. Jika Anda memerlukan kemampuan manajemen konfigurasi terpusat, maka data konfigurasi harus masuk ke App Configuration.

Untuk menggunakan referensi App Configuration untuk pengaturan aplikasi, atur referensi sebagai nilai pengaturan. Aplikasi Anda dapat mereferensikan nilai Konfigurasi melalui kuncinya seperti biasa. Tidak ada perubahan kode yang diperlukan.

Tip

Sebagian besar pengaturan aplikasi yang menggunakan referensi App Configuration harus ditandai sebagai pengaturan slot, karena Anda harus memiliki penyimpanan atau label terpisah untuk setiap lingkungan.

Pertimbangan untuk pemasangan Azure Files

Aplikasi dapat menggunakan pengaturan aplikasi WEBSITE_CONTENTAZUREFILECONNECTIONSTRING untuk memasang Azure Files sebagai sistem file. Pengaturan ini memiliki pemeriksaan validasi tambahan untuk memastikan aplikasi dapat dimulai dengan benar. Platform ini mengandalkan berbagi konten dalam Azure Files, dan menerima nama default kecuali satu yang ditentukan melalui pengaturan WEBSITE_CONTENTSHARE. Untuk permintaan apa pun yang mengubah pengaturan ini, platform akan mencoba memvalidasi apakah berbagi konten ini ada, dan platform akan mencoba untuk membuatnya jika tidak ada. Jika platform tidak dapat menemukan atau membuat berbagi konten, permintaan akan diblokir.

Ketika menggunakan referensi App Configuration untuk pengaturan ini, pemeriksaan validasi ini akan gagal secara default, karena koneksinya tidak bisa diselesaikan saat pemrosesan permintaan masuk. Untuk menghindari masalah ini, Anda dapat melompati validasi dengan mengatur WEBSITE_SKIP_CONTENTSHARE_VALIDATION ke "1". Pengaturan ini akan melewati semua pemeriksaan dan berbagi konten tidak akan dibuat untuk Anda. Anda harus memastikan berbagi konten sudah dibuat terlebih dahulu.

Perhatian

Jika Anda melompati validasi dan string koneksi atau berbagi konten tidak valid, aplikasi tidak akan dapat memulai dengan benar dan hanya akan menampilkan kesalahan HTTP 500.

Sebagai bagian dari pembuatan situs, memungkinkan juga bahwa upaya penginstalan berbagi konten gagal karena izin identitas terkelola tidak disebarkan atau integrasi jaringan virtual tidak disiapkan. Anda dapat menunda pengaturan Azure Files hingga nanti di templat penyebaran untuk mengakomodasi penyiapan yang diperlukan. Lihat Penyebaran Azure Resource Manager untuk mempelajari selengkapnya. App Service akan menggunakan sistem file default hingga Azure Files disiapkan, dan file tidak disalin, sehingga Anda harus memastikan tidak ada upaya penyebaran yang terjadi selama periode sementara sebelum Azure Files diinstal.

Penyebaran Azure Resource Manager

Saat mengotomatiskan penyebaran sumber daya melalui templat Azure Resource Manager, Anda mungkin perlu mengurutkan dependensi Anda dalam urutan tertentu agar fitur ini berfungsi. Sebagai catatan, Anda perlu mendefinisikan pengaturan aplikasi Anda sebagai sumber dayanya sendiri, daripada menggunakan properti siteConfig dalam definisi situs. Ini karena situs perlu didefinisikan terlebih dahulu sehingga identitas yang ditetapkan sistem dibuat dengannya dan dapat digunakan dalam kebijakan akses.

Di bawah ini adalah contoh templat semu untuk aplikasi fungsi dengan referensi 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"
            }
        }
    ]
}

Catatan

Dalam contoh ini, penyebaran kontrol sumber bergantung pada pengaturan aplikasi. Perilaku ini biasanya tidak aman, karena pembaruan pengaturan aplikasi berperilaku asinkron. Namun, karena kita sudah menyertakan pengaturan aplikasi WEBSITE_ENABLE_SYNC_UPDATE_SITE, pembaruannya sinkron. Artinya penyebaran kontrol sumber hanya akan dimulai setelah pengaturan aplikasi sudah diperbarui sepenuhnya. Untuk pengaturan aplikasi lainnya, lihat Variabel lingkungan dan pengaturan aplikasi di Azure App Service.

Pemecahan masalah Referensi App Configuration

Jika referensi tidak diselesaikan dengan benar, nilai referensi akan digunakan sebagai gantinya. Untuk pengaturan aplikasi, variabel lingkungan akan dibuat yang nilainya memiliki sintaks @Microsoft.AppConfiguration(...). Hal ini mungkin menyebabkan kesalahan, karena aplikasi mengharapkan nilai konfigurasi.

Umumnya, kesalahan ini dapat disebabkan kesalahan konfigurasi kebijakan akses App Configuration. Namun, kesalahan tersebut juga bisa disebabkan oleh kesalahan sintaks dalam referensi atau nilai kunci Konfigurasi yang tidak ada di penyimpanan.

Langkah berikutnya

Mereferensikan rahasia Brankas kunci dari App Service