Bagikan melalui

Mulai cepat: Menggunakan Azure App Configuration di Azure Kubernetes Service

Di Kubernetes, Anda dapat mengatur pod untuk mengonsumsi data konfigurasi dari ConfigMaps. Praktik ini meningkatkan portabilitas aplikasi Anda, karena Anda dapat memisahkan data konfigurasi dari gambar kontainer Anda.

Penyedia Kubernetes Azure App Configuration menawarkan cara untuk membuat Kubernetes ConfigMaps dan Secrets dari nilai kunci dan referensi Azure Key Vault yang disimpan dalam App Configuration. Saat menggunakan penyedia ini, Anda dapat menggunakan App Configuration untuk menyimpan dan mengelola data konfigurasi secara terpusat tanpa membuat perubahan pada kode aplikasi Anda.

ConfigMap dapat digunakan sebagai variabel lingkungan atau file yang dipasang. Dalam mulai cepat ini, Anda menggabungkan Penyedia Kubernetes Azure App Configuration dalam beban kerja AKS Anda. Penyedia membuat ConfigMap dari data di penyimpanan App Configuration Anda. Dalam beban kerja, Anda menjalankan aplikasi dasar ASP.NET Core dalam pod yang menggunakan ConfigMap sebagai file JSON yang dipasang dalam volume data.

Petunjuk / Saran

Untuk cara lain mengakses App Configuration dari beban kerja yang dihosting di Kubernetes, lihat Akses Azure Kubernetes Service ke App Configuration.

Catatan

Mulai cepat ini memancang Anda menyiapkan Penyedia Kubernetes Azure App Configuration. Secara opsional, Anda dapat menggunakan perintah Azure Developer CLI berikut untuk memprovisikan sumber daya Azure dan menyebarkan aplikasi sampel yang digunakan mulai cepat ini. Perintah ini menggunakan azure-appconfig-aks templat untuk tujuan ini. Untuk informasi selengkapnya tentang templat ini, lihat repositori GitHub azure-appconfig-aks .

azd init -t azure-appconfig-aks
azd up

Prasyarat

Membuat aplikasi yang berjalan di AKS

Di bagian ini, Anda membuat aplikasi web dasar ASP.NET Core yang berjalan di AKS. Aplikasi membaca data konfigurasi dari file JSON lokal. Di bagian berikutnya, Anda mengaktifkan aplikasi untuk menggunakan data konfigurasi dari App Configuration tanpa mengubah kode aplikasi.

Jika Anda sudah memiliki aplikasi AKS yang membaca konfigurasi dari file, Anda dapat melewati bagian ini dan membuka Menggunakan Penyedia Kubernetes Azure App Configuration. Jika Anda melewati bagian ini, pastikan file konfigurasi yang dihasilkan penyedia cocok dengan jalur file yang digunakan aplikasi Anda.

Membuat aplikasi

  1. Gunakan antarmuka baris perintah .NET (CLI) untuk menjalankan perintah berikut. Ini membuat proyek aplikasi web ASP.NET Core di direktori MyWebApp baru.

    dotnet new webapp --output MyWebApp --framework net8.0

  2. Di direktori MyWebApp , buka direktori Pages , lalu buka Index.cshtml. Ganti konten dengan kode berikut:

    @page
@model IndexModel
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
@{
    ViewData["Title"] = "Home page";
}

<style>
    h1 {
        color: @Configuration["Settings:FontColor"];
    }
</style>

<div class="text-center">
    <h1>@Configuration["Settings:Message"]</h1>
</div>

  3. Buat direktori konfigurasi di akar proyek Anda. Di direktori konfigurasi , tambahkan file mysettings.json yang berisi konten berikut:

    {
  "Settings": {
    "FontColor": "Black",
    "Message": "Message from the local configuration"
  }
}

  4. Di direktori akar proyek Anda, buka Program.cs, lalu tambahkan file JSON ke sumber konfigurasi dengan memanggil AddJsonFile metode .

    // Existing code in Program.cs
// ... ...

// Add a JSON configuration source.
builder.Configuration.AddJsonFile("config/mysettings.json", reloadOnChange: true, optional: false);

var app = builder.Build();

// The rest of the existing code in Program.cs
// ... ...

Menerapkan kontainer pada aplikasi

  1. Untuk membuat aplikasi dalam mode rilis dan membuat aset di direktori yang diterbitkan, jalankan perintah terbitkan dotnet .

    dotnet publish -c Release -o published

  2. Buat file bernama Dockerfile di akar direktori proyek Anda, buka di editor teks, dan masukkan konten berikut. Dockerfile adalah file teks yang tidak memiliki ekstensi. Anda menggunakannya untuk membuat gambar kontainer.

    FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
COPY published/ ./
ENTRYPOINT ["dotnet", "MyWebApp.dll"]

  3. Buat gambar kontainer bernama aspnetapp dengan menjalankan perintah berikut:

    docker build --tag aspnetapp .

Dorong gambar ke Container Registry

  1. Untuk masuk ke registri kontainer Anda, jalankan perintah az acr login . Kode berikut masuk ke registri bernama myregistry. Ganti nama registri tersebut dengan nama registri Anda.

    az acr login --name myregistry

    Perintah akan kembali Login Succeeded jika Anda berhasil masuk.

  2. Untuk membuat tag yang dipanggil myregistry.azurecr.io/aspnetapp:v1aspnetapp untuk gambar, gunakan perintah tag docker . Ganti myregistry dengan nama registri Anda.

    docker tag aspnetapp myregistry.azurecr.io/aspnetapp:v1

    Petunjuk / Saran

    Untuk meninjau daftar gambar dan tag Docker yang ada, jalankan docker image ls. Dalam skenario ini, output harus mencantumkan setidaknya dua gambar: aspnetapp dan myregistry.azurecr.io/aspnetapp.

  3. Untuk mengunggah gambar ke registri kontainer, gunakan perintah docker push . Misalnya, perintah berikut mendorong gambar ke repositori bernama aspnetapp dengan tag v1 di bawah registri myregistry:

    docker push myregistry.azurecr.io/aspnetapp:v1

Menyebarkan aplikasi

  1. Buat direktori Penyebaran di direktori akar proyek Anda.

  2. Untuk menentukan penyebaran, tambahkan file deployment.yaml dengan konten berikut ke direktori Penyebaran . Ganti nilai template.spec.containers.image dengan tag yang Anda buat di bagian sebelumnya.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80

  3. Untuk menentukan LoadBalancer layanan, tambahkan file service.yaml dengan konten berikut ke direktori Penyebaran :

    apiVersion: v1
kind: Service
metadata:
  name: aspnetapp-demo-service
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: aspnetapp-demo

  4. Untuk memungkinkan kubectl terhubung ke kluster AKS Anda, jalankan perintah berikut. Ini mengunduh kredensial untuk kluster AKS Anda dan menggabungkannya ke dalam konteks untuk kluster Anda.

    az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>

  5. Untuk menyebarkan aplikasi ke kluster AKS dan membuat sumber daya, jalankan perintah berikut:

    kubectl create namespace appconfig-demo
kubectl apply -f ./Deployment -n appconfig-demo

  6. Untuk mendapatkan alamat IP eksternal yang diekspos oleh LoadBalancer layanan, jalankan perintah berikut:

    kubectl get service aspnetapp-demo-service -n appconfig-demo

  7. Di jendela browser, buka alamat IP yang Anda peroleh di langkah sebelumnya. Halaman web akan terlihat mirip dengan cuplikan layar berikut:

    Cuplikan layar browser yang memperlihatkan halaman web aplikasi. Halaman berisi teks yang menyatakan Pesan dari konfigurasi lokal.

Menggunakan Penyedia Kubernetes Azure App Configuration

Sekarang setelah Anda memiliki aplikasi yang berjalan di AKS, langkah selanjutnya adalah menyebarkan Penyedia Kubernetes Azure App Configuration ke kluster AKS Anda untuk berjalan sebagai pengontrol Kubernetes. Penyedia mengambil data dari penyimpanan App Configuration Anda dan membuat ConfigMap, yang dapat dikonsumsi sebagai file JSON yang dipasang dalam volume data.

Menyiapkan penyimpanan App Configuration

Tambahkan kunci dan nilai berikut ke penyimpanan App Configuration. Untuk masing-masing nilai, gunakan nilai default untuk Label dan Tipe Konten. Untuk informasi selengkapnya tentang cara menambahkan nilai kunci ke penyimpanan dengan menggunakan portal Microsoft Azure atau Azure CLI, lihat Membuat nilai kunci.

Kunci Nilai
Pengaturan:FontColor Hijau
Pengaturan:Pesan Halo dari Azure App Configuration

Menyiapkan Penyedia Kubernetes Azure App Configuration

  1. Instal Penyedia Kubernetes Azure App Configuration di kluster AKS Anda. Anda dapat menginstal penyedia baik sebagai ekstensi AKS atau dengan menggunakan bagan Helm. Ekstensi AKS menyediakan penginstalan dan manajemen yang mulus melalui Azure CLI, templat Azure Resource Manager (templat ARM), atau file Bicep. Selain itu, menggunakan ekstensi AKS memfasilitasi pembaruan versi minor dan patch otomatis, membantu memastikan sistem Anda tetap terbarui.

    Tambahkan ke k8s-extension ekstensi Azure CLI Anda.

    az extension add --name k8s-extension

    Daftarkan KubernetesConfiguration penyedia sumber daya.

    az provider register --namespace Microsoft.KubernetesConfiguration

    Instal ekstensi AKS untuk App Configuration. cluster-name Ganti nilai parameter dan resource-group dengan nilai yang sesuai dari instans AKS Anda. Secara default, penyedia diinstal di azappconfig-system namespace layanan.

    az k8s-extension create --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider \
    --extension-type Microsoft.AppConfiguration

    Untuk informasi selengkapnya, lihat Menginstal ekstensi AKS Azure App Configuration.

  2. Untuk menentukan AzureAppConfigurationProvider sumber daya, tambahkan file appConfigurationProvider.yaml dengan konten berikut ke direktori Penyebaran . AzureAppConfigurationProvider adalah sumber daya kustom. Ini mendefinisikan data yang akan diunduh dari penyimpanan App Configuration. Ini juga membuat ConfigMap.

    apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
metadata:
  name: appconfigurationprovider-sample
spec:
  endpoint: <your-app-configuration-store-endpoint>
  target:
    configMapName: configmap-created-by-appconfig-provider
    configMapData: 
      type: json
      key: mysettings.json
  auth:
    workloadIdentity:
      serviceAccountName: <your-service-account-name>

    Ganti nilai bidang endpoint dengan titik akhir dari store Azure App Configuration Anda. Lanjutkan ke langkah berikutnya untuk memperbarui bagian auth dengan informasi autentikasi Anda.

    Catatan

    AzureAppConfigurationProvider adalah objek API deklaratif. Ini mendefinisikan status ConfigMap yang diinginkan yang dibuat dari data di penyimpanan App Configuration Anda. Definisi status yang diinginkan menentukan perilaku berikut:

    • Pembuatan ConfigMap gagal jika ConfigMap dengan nama yang sama sudah ada di namespace yang sama.
    • ConfigMap diatur ulang berdasarkan data yang ada di penyimpanan App Configuration Anda jika dihapus atau dimodifikasi dengan cara lain.
    • ConfigMap dihapus jika Penyedia Kubernetes Azure App Configuration dihapus instalasinya.

  3. Untuk mengautentikasi dengan penyimpanan App Configuration Anda, ikuti instruksi untuk menggunakan identitas beban kerja. Perbarui file appConfigurationProvider.yaml dengan mengganti serviceAccountName bidang dengan nama akun layanan yang Anda buat saat mengikuti instruksi. Untuk informasi selengkapnya tentang metode autentikasi lainnya, lihat contoh dalam Autentikasi.

  4. Seperti yang ditunjukkan dalam kode berikut, perbarui file deployment.yaml di direktori Penyebaran untuk menggunakan ConfigMap configmap-created-by-appconfig-provider sebagai volume data yang dipasang. Penting bahwa nilai cocok dengan WORKDIR nilai yang ditentukan dalam Dockerfile Anda dan direktori konfigurasi yang volumeMounts.mountPath Anda buat sebelumnya. Selain itu, pastikan bahwa nilai template.spec.containers.image cocok dengan nama gambar yang Anda buat sebelumnya.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: aspnetapp-demo
  labels:
    app: aspnetapp-demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: aspnetapp-demo
  template:
    metadata:
      labels:
        app: aspnetapp-demo
    spec:
      containers:
      - name: aspnetapp
        image: myregistry.azurecr.io/aspnetapp:v1
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /app/config
      volumes:
      - name: config-volume 
        configMap: 
          name: configmap-created-by-appconfig-provider

  5. Untuk menyebarkan perubahan, jalankan perintah berikut. Perbarui namespace jika Anda menggunakan aplikasi AKS yang sudah ada.

    kubectl apply -f ./Deployment -n appconfig-demo

  6. Segarkan browser. Halaman ini memperlihatkan konten yang diperbarui.

    Cuplikan layar browser yang memperlihatkan halaman web aplikasi. Halaman berisi teks hijau yang menyatakan Halo dari Azure App Configuration.

Pemecahan Masalah

Jika aplikasi Anda tidak membaca data dari penyimpanan App Configuration Anda, jalankan perintah berikut untuk memverifikasi bahwa ConfigMap dibuat dengan benar:

kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo

Jika ConfigMap tidak dibuat, jalankan perintah berikut untuk mendapatkan status pengambilan data:

kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

Jika Penyedia Kubernetes Azure App Configuration berhasil mengambil data dari penyimpanan App Configuration Anda, phase properti di status bagian output harus Complete, seperti yang ditunjukkan dalam contoh berikut:

$ kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml

apiVersion: azconfig.io/v1
kind: AzureAppConfigurationProvider
  ... ... ...
status:
  lastReconcileTime: "2025-08-04T13:58:02Z"
  lastSyncTime: "2025-08-04T13:58:02Z"
  message: Complete sync key-values from App Configuration to target ConfigMap or
    Secret.
  phase: Complete

Jika properti fase tidak COMPLETE, data tidak diunduh dari penyimpanan App Configuration Anda dengan benar. Untuk mengakses log Penyedia Kubernetes Azure App Configuration, jalankan perintah berikut:

kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system

Gunakan log untuk pemecahan masalah lebih lanjut. Untuk solusi untuk masalah umum, lihat FAQ.

FAQ

Mengapa ConfigMap atau Secret tidak dibuat?

Untuk mengumpulkan log yang berisi informasi kesalahan terperinci, ikuti langkah-langkah dalam Pemecahan Masalah. Berikut adalah beberapa penyebab umum masalah ini:

  • RESPONSE 403: 403 Forbidden: Identitas yang telah dikonfigurasi tidak memiliki izin yang diperlukan untuk mengakses penyimpanan App Configuration. Untuk contoh yang cocok dengan identitas yang Anda gunakan, lihat Autentikasi.
  • Referensi Key Vault ditemukan di App Configuration, tetapi 'spec.secret' tidak dikonfigurasi: Satu atau beberapa referensi Key Vault disertakan dalam nilai kunci yang dipilih, tetapi informasi autentikasi untuk Key Vault tidak disediakan. Untuk mempertahankan integritas konfigurasi, seluruh konfigurasi gagal dimuat. Konfigurasikan bagian spec.secret untuk memberikan informasi autentikasi yang diperlukan. Untuk contoh dan informasi selengkapnya, lihat Referensi Key Vault .

Mengapa ConfigMap yang dihasilkan tidak berisi data yang diharapkan?

Pastikan bahwa pemilih nilai kunci yang Anda tentukan cocok dengan data yang diharapkan. Jika Anda tidak menentukan pemilih apa pun, semua nilai kunci tanpa label diunduh dari penyimpanan App Configuration Anda. Saat Anda menggunakan filter kunci, verifikasi bahwa filter tersebut cocok dengan awalan nilai kunci yang diharapkan. Jika nilai kunci Anda memiliki label, pastikan untuk menentukan filter label di pemilih. Untuk contoh selengkapnya, lihat Pilihan nilai kunci.

Bagaimana cara menyesuaikan penginstalan Penyedia Kubernetes Azure App Configuration?

Anda dapat menyesuaikan penginstalan dengan menyediakan nilai Helm tambahan saat menginstal Penyedia Kubernetes Azure App Configuration. Misalnya, Anda dapat mengatur tingkat log, mengonfigurasi penyedia untuk berjalan pada simpul tertentu, atau menonaktifkan identitas beban kerja. Untuk informasi selengkapnya, lihat Penginstalan.

Bagaimana cara memicu refresh sesuai permintaan dari ConfigMap dan Secret?

Anda dapat mengonfigurasi data untuk di-refresh secara otomatis. Tetapi ada kalanya Anda mungkin ingin memicu refresh sesuai permintaan untuk mendapatkan data terbaru dari App Configuration dan Key Vault. Untuk memicu refresh, Anda dapat memodifikasi bagian metadata.annotations .AzureAppConfigurationProvider Penyedia Kubernetes kemudian memperbarui ConfigMap dan Secret dengan data terbaru dari penyimpanan App Configuration dan Key Vault Anda. Misalnya, lihat Refresh sesuai permintaan.

Kami tidak menyarankan untuk menghapus atau memodifikasi ConfigMap dan Secret yang dihasilkan oleh penyedia Kubernetes. Yang baru dihasilkan dari data terbaru, tetapi situasi ini dapat menyebabkan waktu henti untuk aplikasi Anda selama kegagalan.

Mengapa saya tidak dapat mengautentikasi dengan App Configuration dengan menggunakan identitas beban kerja setelah meningkatkan penyedia ke versi 2.0.0?

Dimulai dengan versi 2.0.0, akun layanan yang disediakan pengguna diperlukan untuk mengautentikasi dengan App Configuration dengan menggunakan identitas beban kerja. Perubahan ini meningkatkan keamanan melalui isolasi namespace. Sebelumnya, akun layanan penyedia Kubernetes digunakan untuk semua namespace layanan. Untuk instruksi yang diperbarui, lihat dokumentasi tentang menggunakan identitas beban kerja. Jika Anda memerlukan waktu untuk bermigrasi saat meningkatkan ke versi 2.0.0, Anda dapat menggunakan workloadIdentity.globalServiceAccountEnabled=true pengaturan untuk sementara waktu selama penginstalan penyedia. Perhatikan bahwa dukungan untuk menggunakan akun layanan penyedia dijadwalkan untuk penghentian dalam rilis mendatang.

Membersihkan sumber daya

Jika Anda ingin menghapus instalan Penyedia Kubernetes Azure App Configuration tetapi pertahankan kluster AKS Anda, gunakan perintah berikut untuk menghapus instalan penyedia:

az k8s-extension delete --cluster-type managedClusters \
    --cluster-name <your-AKS-instance-name> \
    --resource-group <your-AKS-resource-group> \
    --name appconfigurationkubernetesprovider

Jika Anda tidak ingin terus menggunakan sumber daya yang dibuat dalam artikel ini, hapus grup sumber daya yang Anda buat di sini untuk menghindari biaya.

Penting

Penghapusan grup sumber daya tidak bisa dipulihkan. Grup sumber daya dan semua sumber daya yang ada di dalamnya akan dihapus secara permanen. Pastikan Anda tidak menghapus grup atau sumber daya yang salah secara tidak sengaja. Jika Anda membuat sumber daya untuk artikel ini dalam grup sumber daya yang ada yang berisi sumber daya lain yang ingin disimpan, hapus setiap sumber daya satu per satu dari panelnya masing-masing, bukan menghapus grup sumber daya.

  1. Masuk ke portal Azure, lalu pilih Grup sumber daya.
  2. Dalam kotak Filter menurut nama, masukkan nama grup sumber daya Anda.
  3. Dalam daftar hasil, pilih nama grup sumber daya untuk melihat gambaran umum.
  4. Pilih Hapus grup sumber daya.
  5. Anda akan diminta untuk mengonfirmasi penghapusan grup sumber daya. Masukkan nama grup sumber daya Anda untuk mengonfirmasi, dan pilih Hapus.

Setelah beberapa saat, grup sumber daya dan semua sumber dayanya akan dihapus.

Catatan

Jika Anda menggunakan Azure Developer CLI untuk menyiapkan sumber daya, Anda dapat menjalankan perintah azd down untuk menghapus semua sumber daya yang dibuat oleh templat azure-appconfig-aks.

Langkah berikutnya

Pada panduan cepat ini, Anda:

  • Membuat aplikasi yang berjalan di AKS.
  • Menghubungkan kluster AKS ke penyimpanan App Configuration dengan menggunakan Penyedia Kubernetes Azure App Configuration.
  • Membuat ConfigMap dengan data dari penyimpanan App Configuration Anda.
  • Menjalankan aplikasi dengan data konfigurasi dari penyimpanan App Configuration Anda tanpa mengubah kode aplikasi Anda.

Untuk mengetahui cara memperbarui beban kerja AKS Anda untuk menyegarkan data konfigurasi secara dinamis, lanjutkan ke tutorial berikutnya.

Menggunakan konfigurasi dinamis di Azure Kubernetes Service

Untuk informasi selengkapnya tentang Penyedia Kubernetes Azure App Configuration, lihat Referensi Penyedia Kubernetes Azure App Configuration.

  • Last updated on