مشاركة عبر


التشغيل السريع: استخدام تكوين تطبيق Azure في خدمة Azure Kubernetes

في Kubernetes، يمكنك إعداد pods لاستهلاك بيانات التكوين من ConfigMaps. تعمل هذه الممارسة على تحسين قابلية نقل تطبيقاتك، لأنه يمكنك فصل بيانات التكوين عن صور الحاوية.

يوفر Azure App Configuration Kubernetes Provider طريقة لإنشاء Kubernetes ConfigMaps وSecrets من القيم الرئيسية ومراجع Azure Key Vault المخزنة في تكوين التطبيق. عند استخدام هذا الموفر، يمكنك استخدام "تكوين التطبيق" لتخزين بيانات التكوين وإدارتها مركزيا دون إجراء تغييرات على التعليمات البرمجية للتطبيق.

يمكن استهلاك ConfigMap كمتغيرات بيئة أو ملف مثبت. في هذا التشغيل السريع، يمكنك دمج موفر Kubernetes لتكوين تطبيقات Azure في حمل عمل AKS. يقوم الموفر بإنشاء ConfigMap من البيانات الموجودة في متجر App Configuration الخاص بك. في حمل العمل، يمكنك تشغيل تطبيق ASP.NET Core أساسي في جراب يستهلك ConfigMap كملف JSON تم تحميله في وحدة تخزين بيانات.

تلميح

للحصول على طرق أخرى للوصول إلى تكوين التطبيق من حمل عمل مستضاف في Kubernetes، راجع وصول خدمة Azure Kubernetes إلى تكوين التطبيق.

إشعار

يرشدك هذا التشغيل السريع خلال إعداد موفر Kubernetes لتكوين تطبيق Azure. اختياريا، يمكنك استخدام أوامر Azure Developer CLI التالية لتوفير موارد Azure ونشر نموذج التطبيق الذي يستخدمه هذا التشغيل السريع. تستخدم هذه الأوامر القالب azure-appconfig-aks لهذا الغرض. لمزيد من المعلومات حول هذا القالب، راجع مستودع Azure -appconfig-aks GitHub.

azd init -t azure-appconfig-aks
azd up

المتطلبات الأساسية

إنشاء تطبيق يعمل في AKS

في هذا القسم، يمكنك إنشاء تطبيق ويب أساسي ASP.NET Core يتم تشغيله في AKS. يقرأ التطبيق بيانات التكوين من ملف JSON محلي. في القسم التالي، يمكنك تمكين التطبيق من استهلاك بيانات التكوين من تكوين التطبيق دون تغيير التعليمات البرمجية للتطبيق.

إذا كان لديك بالفعل تطبيق AKS يقرأ التكوين من ملف، فيمكنك تخطي هذا القسم والانتقال إلى استخدام موفر Kubernetes لتكوين تطبيق Azure. إذا تخطيت هذا القسم، فتأكد من أن ملف التكوين الذي يقوم الموفر بإنشائه يطابق مسار الملف الذي يستخدمه تطبيقك.

إنشاء تطبيق

  1. استخدم واجهة سطر الأوامر (CLI) .NET لتشغيل الأمر التالي. يقوم بإنشاء مشروع تطبيق ويب ASP.NET Core في دليل MyWebApp جديد.

    dotnet new webapp --output MyWebApp --framework net8.0
    
  2. في دليل MyWebApp ، انتقل إلى دليل الصفحات ، ثم افتح Index.cshtml. استبدل المحتوى بالتعليمات البرمجية التالية:

    @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. قم بإنشاء دليل تكوين في جذر مشروعك. في دليل التكوين ، أضف ملف mysettings.json يحتوي على المحتوى التالي:

    {
      "Settings": {
        "FontColor": "Black",
        "Message": "Message from the local configuration"
      }
    }
    
  4. في الدليل الجذر للمشروع، افتح Program.cs، ثم أضف ملف JSON إلى مصدر التكوين عن طريق استدعاء الطريقة AddJsonFile .

    // 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
    // ... ...
    

ضع التطبيق في حاوية

  1. لإنشاء التطبيق في وضع الإصدار وإنشاء الأصول في الدليل المنشور ، قم بتشغيل الأمر dotnet publish .

    dotnet publish -c Release -o published
    
  2. أنشئ ملفا باسم Dockerfile في جذر دليل المشروع، وافتحه في محرر نص، وأدخل المحتوى التالي. Dockerfile هو ملف نصي ليس له امتداد. يمكنك استخدامه لإنشاء صورة حاوية.

    FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
    WORKDIR /app
    COPY published/ ./
    ENTRYPOINT ["dotnet", "MyWebApp.dll"]
    
  3. إنشاء صورة حاوية مسماة aspnetapp عن طريق تشغيل الأمر التالي:

    docker build --tag aspnetapp .
    

دفع الصورة إلى "سجل الحاوية"

  1. لتسجيل الدخول إلى سجل الحاوية الخاص بك، قم بتشغيل الأمر az acr login . تقوم التعليمات البرمجية التالية بتسجيل الدخول إلى سجل باسم myregistry. استبدل اسم السجل هذا باسم السجل الخاص بك.

    az acr login --name myregistry
    

    يعود Login Succeeded الأمر إذا قمت بتسجيل الدخول بنجاح.

  2. لإنشاء علامة تسمى myregistry.azurecr.io/aspnetapp:v1 للصورة aspnetapp ، استخدم الأمر docker tag . استبدل myregistry باسم السجل الخاص بك.

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

    تلميح

    لمراجعة قائمة صور وعلامات Docker الموجودة لديك ، قم بتشغيل docker image ls. في هذا السيناريو، يجب أن يسرد الإخراج صورتين على الأقل: aspnetapp و myregistry.azurecr.io/aspnetapp.

  3. لتحميل الصورة إلى سجل الحاوية، استخدم الأمر docker push . على سبيل المثال ، يدفع الأمر التالي الصورة إلى مستودع يسمى aspnetapp بعلامة v1 ضمن السجل myregistry:

    docker push myregistry.azurecr.io/aspnetapp:v1
    

قم بنشر التطبيق

  1. إنشاء دليل نشر في الدليل الجذر لمشروعك.

  2. لتحديد توزيع، أضف ملف deployment.yaml بالمحتوى التالي إلى دليل النشر . استبدل قيمة العلامة template.spec.containers.image التي قمت بإنشائها في القسم السابق.

    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. لتحديد خدمة LoadBalancer ، أضف ملف service.yaml يحتوي على المحتوى التالي إلى دليل النشر :

    apiVersion: v1
    kind: Service
    metadata:
      name: aspnetapp-demo-service
    spec:
      type: LoadBalancer
      ports:
      - port: 80
      selector:
        app: aspnetapp-demo
    
  4. لتمكين kubectl من الاتصال بنظام مجموعة AKS الخاص بك، قم بتشغيل الأمر التالي. يقوم بتنزيل بيانات الاعتماد لمجموعة AKS الخاصة بك ودمجها في سياق نظام المجموعة الخاص بك.

    az aks get-credentials --name <your-AKS-instance-name> --resource-group <your-AKS-resource-group>
    
  5. لنشر التطبيق إلى نظام مجموعة AKS وإنشاء الموارد، قم بتشغيل الأوامر التالية:

    kubectl create namespace appconfig-demo
    kubectl apply -f ./Deployment -n appconfig-demo
    
  6. للحصول على عنوان IP الخارجي الذي تعرضه بواسطة LoadBalancer الخدمة، قم بتشغيل الأمر التالي:

    kubectl get service aspnetapp-demo-service -n appconfig-demo
    
  7. في نافذة المتصفح، انتقل إلى عنوان IP الذي حصلت عليه في الخطوة السابقة. يجب أن تبدو صفحة الويب مشابهة لقطة الشاشة التالية:

    لقطة شاشة لمتصفح يعرض صفحة الويب الخاصة بأحد التطبيقات. تحتوي الصفحة على نص يوضح رسالة من التكوين المحلي.

استخدام موفر تكوين تطبيق Azure Kubernetes

الآن بعد أن أصبح لديك تطبيق قيد التشغيل في AKS، فإن الخطوة التالية هي نشر موفر تكوين تطبيقات Azure Kubernetes إلى نظام مجموعة AKS لتشغيله كوحدة تحكم Kubernetes. يسترد الموفر البيانات من متجر App Configuration الخاص بك وينشئ ConfigMap، والذي يمكن استهلاكه كملف JSON مثبت في وحدة تخزين بيانات.

إعداد مخزن "تكوين التطبيقات"

أضف المفاتيح والقيم التالية إلى متجر App Configuration. لكل منها، استخدم القيم الافتراضية ل التسميةونوع المحتوى. لمزيد من المعلومات حول كيفية إضافة قيم رئيسية إلى متجر باستخدام مدخل Microsoft Azure أو Azure CLI، راجع إنشاء قيمة مفتاح.

المفتاح القيمة
الإعدادات:لون الخط أخضر
الإعدادات:رسالة مرحبا من تكوين تطبيق Azure

إعداد موفر Kubernetes لتكوين تطبيق Azure

  1. قم بتثبيت موفر Kubernetes لتكوين تطبيقات Azure على نظام مجموعة AKS الخاص بك. يمكنك تثبيت الموفر إما كملحق AKS أو باستخدام مخطط Helm. يوفر ملحق AKS تثبيتا وإدارة سلسة عبر Azure CLI أو قوالب Azure Resource Manager (قوالب ARM) أو ملفات Bicep. أيضا ، يسهل استخدام ملحق AKS التحديثات التلقائية للإصدارات الثانوية والتصحيح ، مما يساعد على ضمان بقاء نظامك محدثا.

    أضف إلى k8s-extension ملحقات Azure CLI.

    az extension add --name k8s-extension
    

    تسجيل موفر الموارد KubernetesConfiguration .

    az provider register --namespace Microsoft.KubernetesConfiguration
    

    تثبيت ملحق AKS لتكوين التطبيق. استبدل cluster-name قيم المعلمة والمعلمة resource-group بالقيم المقابلة من مثيل AKS. بشكل افتراضي، يتم تثبيت الموفر في مساحة الاسم azappconfig-system .

    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
    

    لمزيد من المعلومات، راجع تثبيت ملحق AKS لتكوين تطبيق Azure.

  2. لتحديد مورد AzureAppConfigurationProvider ، أضف ملف appConfigurationProvider.yaml بالمحتوى التالي إلى دليل النشر . AzureAppConfigurationProvider هو مورد مخصص. يحدد البيانات المراد تنزيلها من متجر تكوين التطبيق. كما أنه ينشئ 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>
    

    استبدل قيمة endpoint الحقل بنقطة نهاية مخزن Azure App Configuration. انتقل إلى الخطوة التالية لتحديث auth القسم بمعلومات المصادقة الخاصة بك.

    إشعار

    AzureAppConfigurationProvider هو كائن واجهة برمجة تطبيقات تعريفي. يحدد الحالة المطلوبة ل ConfigMap التي تم إنشاؤها من البيانات الموجودة في متجر App Configuration الخاص بك. يحدد تعريف الحالة المطلوبة السلوك التالي:

    • يفشل إنشاء ConfigMap إذا كان ConfigMap بنفس الاسم موجودا بالفعل في نفس مساحة الاسم.
    • تتم إعادة تعيين ConfigMap استنادا إلى البيانات الحالية في متجر App Configuration إذا تم حذفها أو تعديلها بأي وسيلة أخرى.
    • يتم حذف ConfigMap إذا تم إلغاء تثبيت موفر Kubernetes لتكوين تطبيق Azure.
  3. للمصادقة مع متجر App Configuration الخاص بك، اتبع الإرشادات الخاصة باستخدام هوية حمل العمل. قم بتحديث ملف appConfigurationProvider.yaml عن طريق استبدال الحقل serviceAccountName باسم حساب الخدمة الذي تقوم بإنشائه عند اتباع الإرشادات. لمزيد من المعلومات حول طرق المصادقة الأخرى، راجع الأمثلة في المصادقة.

  4. كما هو موضح في التعليمات البرمجية التالية، قم بتحديث ملف deployment.yaml في دليل النشر لاستخدام ConfigMap configmap-created-by-appconfig-provider كوحدة تخزين بيانات محملة. من المهم أن تتطابق القيمة volumeMounts.mountPath مع WORKDIR القيمة المحددة في Dockerfile ودليل التكوين الذي قمت بإنشائه سابقا. تأكد أيضا من أن قيمة template.spec.containers.image تتطابق مع اسم الصورة التي قمت بإنشائها سابقا.

    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. لنشر التغييرات، قم بتشغيل الأمر التالي. قم بتحديث مساحة الاسم إذا كنت تستخدم تطبيق AKS الحالي.

    kubectl apply -f ./Deployment -n appconfig-demo
    
  6. حدّث المستعرض. تعرض الصفحة محتوى محدثا.

    لقطة شاشة لمتصفح يعرض صفحة الويب الخاصة بأحد التطبيقات. تحتوي الصفحة على نص أخضر يوضح مرحبا من تكوين تطبيق Azure.

استكشاف الأخطاء وإصلاحها

إذا لم يقرأ تطبيقك البيانات من متجر App Configuration، فقم بتشغيل الأمر التالي للتحقق من إنشاء ConfigMap بشكل صحيح:

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

إذا لم يتم إنشاء ConfigMap ، فقم بتشغيل الأمر التالي للحصول على حالة استرداد البيانات:

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

إذا قام موفر Azure App Configuration Kubernetes باسترداد البيانات من متجر App Configuration بنجاح، فيجب أن تكون Completeالخاصية phase الموجودة في status قسم الإخراج ، كما هو موضح في المثال التالي:

$ 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

إذا لم COMPLETEتكن خاصية المرحلة ، فلن يتم تنزيل البيانات من متجر App Configuration بشكل صحيح. للوصول إلى سجلات Azure App Configuration Kubernetes Provider، قم بتشغيل الأمر التالي:

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

استخدم السجلات لمزيد من استكشاف الأخطاء وإصلاحها. للحصول على حلول للمشكلات الشائعة، راجع الأسئلة الشائعة.

الأسئلة المتداولة

لماذا لا يتم إنشاء ConfigMap أو Secret؟

لتجميع السجلات التي تحتوي على معلومات مفصلة عن الخطأ، اتبع الخطوات الواردة في استكشاف الأخطاء وإصلاحها. فيما يلي بعض الأسباب الشائعة لهذه المشكلة:

  • الاستجابة 403: 403 ممنوع: الهوية المكونة تفتقر إلى الأذونات اللازمة للوصول إلى متجر App Configuration. للحصول على أمثلة تطابق الهوية التي تستخدمها، راجع المصادقة.
  • تم العثور على مرجع Key Vault في تكوين التطبيق، ولكن لم يتم تكوين "spec.secret": يتم تضمين مرجع Key Vault واحد أو أكثر في قيم المفاتيح المحددة، ولكن لا يتم توفير معلومات المصادقة ل Key Vault. للحفاظ على تكامل التكوين، يفشل التكوين بأكمله في التحميل. قم بتكوين spec.secret القسم لتوفير معلومات المصادقة الضرورية. للحصول على أمثلة ومزيد من المعلومات، راجع مراجع Key Vault .

لماذا لا يحتوي ConfigMap الذي تم إنشاؤه على البيانات المتوقعة؟

تأكد من تطابق محددات قيمة المفتاح التي تحددها مع البيانات المتوقعة. إذا لم تحدد أي محددات، تنزيل جميع القيم الرئيسية التي لا تحتوي على تصنيف من متجر App Configuration. عند استخدام عامل تصفية مفاتيح، تحقق من تطابقه مع بادئة قيم المفاتيح المتوقعة. إذا كانت قيم المفاتيح تحتوي على تسميات، فتأكد من تحديد عامل تصفية التسمية في المحددات. لمزيد من الأمثلة، راجع تحديد قيمة المفتاح.

كيف يمكنني تخصيص تثبيت موفر Kubernetes لتكوين تطبيقات Azure؟

يمكنك تخصيص التثبيت عن طريق توفير قيم Helm إضافية عند تثبيت Azure App Configuration Kubernetes Provider. على سبيل المثال، يمكنك تعيين مستوى السجل أو تكوين الموفر للتشغيل على عقدة معينة أو تعطيل هوية حمل العمل. لمزيد من المعلومات، راجع التثبيت.

كيف يمكنني تشغيل تحديث عند الطلب ل ConfigMap و Secret؟

يمكنك تكوين البيانات للتحديث تلقائيا. ولكن هناك أوقات قد ترغب فيها في تشغيل تحديث عند الطلب للحصول على أحدث البيانات من App Configuration و Key Vault. لتشغيل تحديث، يمكنك تعديل metadata.annotations قسم AzureAppConfigurationProvider. يقوم موفر Kubernetes بعد ذلك بتحديث ConfigMap والسر بأحدث البيانات من متجر App Configuration وKey Vault. على سبيل المثال، راجع التحديث عند الطلب.

لا نوصي بحذف أو تعديل ConfigMap والسر اللذين تم إنشاؤهما بواسطة موفر Kubernetes. يتم إنشاء تطبيقات جديدة من أحدث البيانات ، ولكن هذا الموقف يمكن أن يتسبب في تعطل تطبيقاتك أثناء حالات الفشل.

لماذا لا يمكنني المصادقة باستخدام تكوين التطبيق باستخدام هوية حمل العمل بعد ترقية الموفر إلى الإصدار 2.0.0؟

بدءا من الإصدار 2.0.0، يلزم وجود حساب خدمة يوفره المستخدم للمصادقة باستخدام تكوين التطبيق باستخدام هوية حمل العمل. يعزز هذا التغيير الأمان من خلال عزل مساحة الاسم. في السابق ، تم استخدام حساب خدمة موفر Kubernetes لجميع مساحات الأسماء. للحصول على إرشادات محدثة، راجع الوثائق المتعلقة باستخدام هوية حمل العمل. إذا كنت بحاجة إلى وقت للترحيل عند الترقية إلى الإصدار 2.0.0، يمكنك استخدام الإعداد workloadIdentity.globalServiceAccountEnabled=true مؤقتا أثناء تثبيت الموفر. لاحظ أنه من المقرر إهمال دعم استخدام حساب خدمة الموفر في إصدار مستقبلي.

تنظيف الموارد

إذا كنت ترغب في إلغاء تثبيت Azure App Configuration Kubernetes Provider مع الاحتفاظ بنظام مجموعة AKS، فاستخدم الأمر التالي لإلغاء تثبيت الموفر:

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

إذا كنت لا تريد مواصلة استخدام الموارد التي تم إنشاؤها في هذه المقالة، يوصى بحذف مجموعة الموارد التي أنشأتها هنا لتجنب الرسوم.

هام

حذف مجموعة الموارد لا يمكن التراجع عنه. يتم حذف مجموعة الموارد وجميع الموارد المضمنة فيها نهائيًا. تأكد من عدم حذفك للموارد أو مجموعة المورد الخاطئة عن غير قصد. في حالة إنشاء الموارد لهذه المقالة داخل مجموعة موارد تشتمل على موارد أخرى تريد الاحتفاظ بها، احذف كل مورد على حدة من الجزء الخاص به بدلًا من حذف مجموعة الموارد.

  1. سجل الدخول إلى مدخل Microsoft Azure، وحدد Resource groups.
  2. في المربع تصفية حسب الاسم ، أدخل اسم مجموعة الموارد الخاصة بك.
  3. في قائمة النتائج، حدد اسم مجموعة الموارد لاستعراض نظرة عامة.
  4. حدد Delete resource group.
  5. يُطلب منك تأكيد حذف مجموعة الموارد. أدخل اسم مجموعة الموارد للتأكيد وحدد "Delete".

بعد بضع لحظات، يتم حذف مجموعة الموارد وكافة مواردها.

إشعار

إذا كنت تستخدم Azure Developer CLI لإعداد الموارد، يمكنك تشغيل azd down الأمر لحذف كافة الموارد التي تم إنشاؤها بواسطة القالب azure-appconfig-aks .

الخطوات التالية

في هذه البداية السريعة، قمت بـ:

  • إنشاء تطبيق يعمل في AKS.
  • قم بتوصيل نظام مجموعة AKS بمتجر تكوين التطبيقات باستخدام موفر Kubernetes لتكوين تطبيقات Azure.
  • إنشاء ConfigMap مع بيانات من متجر App Configuration.
  • قم بتشغيل التطبيق باستخدام بيانات التكوين من متجر App Configuration الخاص بك دون تغيير التعليمات البرمجية للتطبيق.

لمعرفة كيفية تحديث أحمال عمل AKS لتحديث بيانات التكوين ديناميكيا، تابع إلى البرنامج التعليمي التالي.

لمزيد من المعلومات حول موفر Kubernetes لتكوين تطبيقات Azure، راجع مرجع موفر Kubernetes لتكوين تطبيقات Azure.