تكوين صورة الحاوية لتنفيذ عمليات التوزيع باستخدام ARM وBicep

في هذه المقالة، ستتعلم كيفية إنشاء صور حاوية مخصصة ل Azure Resource Manager (ARM) وBicep لنشر تعريفات البيئة الخاصة بك في بيئات نشر Azure (ADE).

يتضمن تعريف البيئة ملفين على الأقل: ملف قالب، مثل azuredeploy.json أو main.bicep، وملف بيان يسمى environment.yaml. يستخدم ADE حاويات لنشر تعريفات البيئة، ويدعم في الأصل أطر عمل ARM وBicep IaC.

يتيح لك نموذج قابلية توسعة ADE إنشاء صور حاوية مخصصة لاستخدامها مع تعريفات البيئة الخاصة بك. باستخدام نموذج القابلية للتوسعة، يمكنك إنشاء صور الحاوية المخصصة الخاصة بك وتخزينها في سجل حاوية مثل DockerHub. يمكنك بعد ذلك الرجوع إلى هذه الصور في تعريفات البيئة الخاصة بك لنشر بيئاتك.

يوفر فريق ADE مجموعة مختارة من الصور للبدء، بما في ذلك صورة أساسية، وصورة Azure Resource Manager (ARM)/Bicep. يمكنك الوصول إلى هذه الصور النموذجية في مجلد الصور المشغلة.

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

• حساب Azure مع اشتراك نشط. أنشئ حساباً مجاناً.
• تم إعداد Azure Deployment Environments في اشتراك Azure الخاص بك.
  • لإعداد ADE، اتبع التشغيل السريع: تكوين بيئات نشر Azure.

استخدام صور الحاوية مع ADE

يمكنك اتباع أحد الأساليب التالية لاستخدام صور الحاوية مع ADE:

• استخدم صورة الحاوية القياسية: للسيناريوهات البسيطة، استخدم صورة حاوية Bicep القياسية التي يوفرها ADE.
• إنشاء صورة حاوية مخصصة: للحصول على سيناريوهات أكثر تعقيدا، قم بإنشاء صورة حاوية مخصصة تفي بمتطلباتك المحددة.

بغض النظر عن الأسلوب الذي تختاره، يجب تحديد صورة الحاوية في تعريف البيئة لنشر موارد Azure.

استخدام صورة حاوية Bicep القياسية

يدعم ADE Bicep أصلا، بحيث يمكنك تكوين تعريف بيئة ينشر موارد Azure لبيئة نشر عن طريق إضافة ملفات القالب (azuredeploy.json و environment.yaml) إلى الكتالوج الخاص بك. ثم يستخدم ADE صورة حاوية Bicep القياسية لإنشاء بيئة التوزيع.

في ملف environment.yaml، تحدد خاصية المشغل موقع صورة الحاوية التي تريد استخدامها. لاستخدام نموذج الصورة المنشورة على Microsoft Artifact Registry، استخدم مشغل المعرفات المعنية، كما هو موضح في الجدول التالي.

يوضح المثال التالي مشغلا يشير إلى نموذج صورة حاوية Bicep:

    name: WebApp
    version: 1.0.0
    summary: Azure Web App Environment
    description: Deploys a web app in Azure without a datastore
    runner: Bicep
    templatePath: azuredeploy.json

يمكنك مشاهدة صورة حاوية Bicep القياسية في مستودع عينة ADE ضمن مجلد Runner-Images لصورة ARM-Bicep .

لمزيد من المعلومات حول كيفية إنشاء تعريفات البيئة التي تستخدم صور حاوية ADE لنشر موارد Azure، راجع إضافة تعريف بيئة وتكوينه.

إنشاء صورة حاوية Bicep مخصصة

يتيح لك إنشاء صورة حاوية مخصصة تخصيص عمليات النشر الخاصة بك لتناسب متطلباتك. يمكنك إنشاء صور مخصصة استنادا إلى صور حاوية ADE القياسية.

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

إنشاء صورة حاوية وتخصيصها باستخدام Docker

في هذا المثال، ستتعلم كيفية إنشاء صورة Docker للاستفادة من عمليات نشر ADE والوصول إلى CLI ADE، ما يؤدي إلى إسناد صورتك إلى إحدى الصور المؤلفة من ADE.

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

لإنشاء صورة تم تكوينها ل ADE، اتبع الخطوات التالية:

1. قم بإسناد صورتك إلى صورة عينة مؤلفة من ADE أو الصورة التي تختارها باستخدام عبارة FROM.
2. قم بتثبيت أي حزم ضرورية لصورتك باستخدام عبارة RUN.
3. أنشئ مجلد البرامج النصية في نفس مستوى Dockerfile الخاص بك، وقم بتخزين deploy.sh وملفات delete.sh داخله، وتأكد من أن هذه البرامج النصية قابلة للاكتشاف والتنفيذ داخل الحاوية التي تم إنشاؤها. هذه الخطوة ضرورية للنشر الخاص بك للعمل باستخدام الصورة الأساسية ADE.

حدد نموذج صورة حاوية باستخدام عبارة FROM

قم بتضمين عبارة FROM داخل DockerFile تم إنشاؤه لصورتك الجديدة التي تشير إلى نموذج صورة مستضاف على Microsoft Artifact Registry.

فيما يلي مثال على عبارة FROM، التي تشير إلى نموذج الصورة الأساسية:

FROM mcr.microsoft.com/deployment-environments/runners/core:latest

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

تثبيت Bicep في Dockerfile

يمكنك تثبيت حزمة Bicep مع Azure CLI باستخدام عبارة RUN، كما هو موضح في المثال التالي:

RUN az bicep install

تستند صور عينة ADE إلى صورة Azure CLI، ويتم تثبيت حزم ADE CLI وJQ مسبقا. يمكنك معرفة المزيد حول Azure CLI وحزمة JQ.

لتثبيت أي حزم أخرى تحتاج إليها داخل صورتك، استخدم عبارة RUN.

تنفيذ البرامج النصية ل shell العملية

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

لإعداد صورتك المخصصة لاستخدام هذه البنية، حدد مجلدا على مستوى Dockerfile المسمى البرامج النصية، وحدد ملفين، deploy.sh، delete.sh. يتم تشغيل البرنامج النصي deploy shell عند إنشاء بيئتك أو إعادة توزيعها، ويتم تشغيل البرنامج النصي delete shell عند حذف البيئة الخاصة بك. يمكنك مشاهدة أمثلة على البرامج النصية shell في المستودع ضمن مجلد Runner-Images لصورة ARM-Bicep .

للتأكد من أن هذه البرامج النصية shell قابلة للتنفيذ، أضف الأسطر التالية إلى Dockerfile الخاص بك:

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

تأليف البرامج النصية shell لعملية توزيع قوالب ARM أو Bicep

للتأكد من أنه يمكنك نشر البنية الأساسية ل ARM أو Bicep بنجاح من خلال ADE، يجب عليك:

• تحويل معلمات ADE إلى معلمات مقبولة من ARM
• حل القوالب المرتبطة إذا تم استخدامها في النشر
• استخدام الهوية المدارة المتميزة لتنفيذ التوزيع

أثناء نقطة إدخال الصورة الأساسية، يتم تخزين أي معلمات تم تعيينها للبيئة الحالية ضمن المتغير $ADE_OPERATION_PARAMETERS. لتحويلها إلى معلمات مقبولة من ARM، يمكنك تشغيل الأمر التالي باستخدام JQ:

# format the parameters as arm parameters
deploymentParameters=$(echo "$ADE_OPERATION_PARAMETERS" | jq --compact-output '{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": (to_entries | if length == 0 then {} else (map( { (.key): { "value": .value } } ) | add) end) }' )

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

if [[ $ADE_TEMPLATE_FILE == *.json ]]; then

    hasRelativePath=$( cat $ADE_TEMPLATE_FILE | jq '[.. | objects | select(has("templateLink") and (.templateLink | has("relativePath")))] | any' )

    if [ "$hasRelativePath" = "true" ]; then
        echo "Resolving linked ARM templates"

        bicepTemplate="${ADE_TEMPLATE_FILE/.json/.bicep}"
        generatedTemplate="${ADE_TEMPLATE_FILE/.json/.generated.json}"

        az bicep decompile --file "$ADE_TEMPLATE_FILE"
        az bicep build --file "$bicepTemplate" --outfile "$generatedTemplate"

        # Correctly reassign ADE_TEMPLATE_FILE without the $ prefix during assignment
        ADE_TEMPLATE_FILE="$generatedTemplate"
    fi
fi

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

echo "Signing into Azure using MSI"
while true; do
    # managed identity isn't available immediately
    # we need to do retry after a short nap
    az login --identity --allow-no-subscriptions --only-show-errors --output none && {
        echo "Successfully signed into Azure"
        break
    } || sleep 5
done

لبدء نشر قوالب ARM أو Bicep، قم بتشغيل az deployment group create الأمر . عند تشغيل هذا الأمر داخل الحاوية، اختر اسم نشر لا يتجاوز أي عمليات نشر سابقة، واستخدم --no-prompt true العلامات و --only-show-errors لضمان عدم فشل التوزيع في أي تحذيرات أو التوقف عند انتظار إدخال المستخدم، كما هو موضح في المثال التالي:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
    --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait \
    --template-file "$ADE_TEMPLATE_FILE" \
    --parameters "$deploymentParameters" \
    --only-show-errors

لحذف بيئة، قم بإجراء نشر الوضع الكامل وتوفير قالب ARM فارغ، والذي يزيل كافة الموارد داخل مجموعة موارد ADE المحددة، كما هو موضح في المثال التالي:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait --mode Complete \
    --only-show-errors \
    --template-file "$DIR/empty.json"

يمكنك التحقق من حالة التوفير والتفاصيل عن طريق تشغيل الأوامر أدناه. يستخدم ADE بعض الدالات الخاصة لقراءة وتوفير المزيد من السياق استنادا إلى تفاصيل التوفير، والتي يمكنك العثور عليها في مجلد Runner-Images . يمكن أن يكون التنفيذ البسيط كما يلي:

if [ $? -eq 0 ]; then # deployment successfully created
    while true; do

        sleep 1

        ProvisioningState=$(az deployment group show --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName" --query "properties.provisioningState" -o tsv)
        ProvisioningDetails=$(az deployment operation group list --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName")

        echo "$ProvisioningDetails"

        if [[ "CANCELED|FAILED|SUCCEEDED" == *"${ProvisioningState^^}"* ]]; then

            echo -e "\nDeployment $deploymentName: $ProvisioningState"

            if [[ "CANCELED|FAILED" == *"${ProvisioningState^^}"* ]]; then
                exit 11
            else
                break
            fi
        fi
    done
fi

وأخيرا، لعرض مخرجات التوزيع وتمريرها إلى ADE لتسهيل الوصول إليها عبر Azure CLI، يمكنك تشغيل الأوامر التالية:

deploymentOutput=$(az deployment group show -g "$ADE_RESOURCE_GROUP_NAME" -n "$deploymentName" --query properties.outputs)
if [ -z "$deploymentOutput" ]; then
    deploymentOutput="{}"
fi
echo "{\"outputs\": $deploymentOutput}" > $ADE_OUTPUTS

جعل الصورة المخصصة قابلة للوصول إلى ADE

يجب إنشاء صورة Docker ودفعها إلى سجل الحاوية لجعلها متاحة للاستخدام في ADE. يمكنك إنشاء صورتك باستخدام Docker CLI، أو باستخدام برنامج نصي يوفره ADE.

حدد علامة التبويب المناسبة لمعرفة المزيد حول كل نهج.

إنشاء الصورة باستخدام Docker CLI

قبل إنشاء الصورة التي سيتم دفعها إلى السجل الخاص بك، تأكد من تثبيت Docker Engine على جهاز الكمبيوتر الخاص بك. ثم انتقل إلى دليل Dockerfile الخاص بك، ثم قم بتشغيل الأمر التالي:

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

على سبيل المثال، إذا كنت تريد حفظ صورتك ضمن مستودع داخل السجل الخاص بك المسمى customImage، وتحميلها باستخدام إصدار العلامة من 1.0.0، يمكنك تشغيل:

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0

دفع صورة Docker إلى سجل

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

Azure Container Registry هو عرض Azure يخزن صور الحاوية والبيانات الاصطناعية المماثلة.

لإنشاء سجل، والذي يمكن القيام به من خلال Azure CLI ومدخل Azure والأوامر PowerShell والمزيد، اتبع إحدى عمليات التشغيل السريع.

لإعداد السجل الخاص بك لتمكين سحب الصور المجهولة، قم بتشغيل الأوامر التالية في Azure CLI:

az login
az acr login -n {YOUR_REGISTRY}
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true

عندما تكون مستعدا لدفع صورتك إلى السجل الخاص بك، قم بتشغيل الأمر التالي:

docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}

إنشاء صورة حاوية باستخدام برنامج نصي

توفر Microsoft برنامج نصي للتشغيل السريع لمساعدتك على البدء. يقوم البرنامج النصي بإنشاء صورتك ودفعها إلى Azure Container Registry (ACR) محدد ضمن المستودع ade والعلامة latest.

لاستخدام البرنامج النصي، يجب عليك:

1. إنشاء مجلد Dockerfile والبرامج النصية لدعم نموذج قابلية توسعة ADE.
2. قم بتوفير اسم سجل ودليل لصورتك المخصصة.
3. تثبيت Azure CLI وDocker Desktop وفي متغيرات PATH.
4. لديك أذونات للدفع إلى السجل المحدد.

يمكنك عرض البرنامج النصي هنا.

يمكنك استدعاء البرنامج النصي باستخدام الأمر التالي في PowerShell:

.\quickstart-image-build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}'

بالإضافة إلى ذلك، إذا كنت ترغب في الدفع إلى مستودع معين واسم العلامة، يمكنك تشغيل:

.\quickstart-image.build.ps1 -Registry '{YOUR_REGISTRY}' -Directory '{DIRECTORY_TO_YOUR_IMAGE}' -Repository '{YOUR_REPOSITORY}' -Tag '{YOUR_TAG}'

توصيل الصورة بتعريف البيئة

عند تأليف تعريفات البيئة لاستخدام صورتك المخصصة في توزيعها، قم بتحرير runner الخاصية على ملف البيان (environment.yaml أو manifest.yaml).

runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"

لمعرفة المزيد حول كيفية إنشاء تعريفات البيئة التي تستخدم صور حاوية ADE لنشر موارد Azure، راجع إضافة تعريف بيئة وتكوينه.

الوصول إلى سجلات العمليات وتفاصيل الخطأ

يخزن ADE تفاصيل الخطأ لتوزيع فاشل في ملف $ADE_ERROR_LOG داخل الحاوية.

لاستكشاف أخطاء التوزيع الفاشلة وإصلاحها:

1. سجل الدخول إلى مدخل المطور.

2. حدد البيئة التي فشلت في النشر، وحدد عرض التفاصيل.

   

3. راجع تفاصيل الخطأ في قسم تفاصيل الخطأ.

   

بالإضافة إلى ذلك، يمكنك استخدام Azure CLI لعرض تفاصيل خطأ البيئة باستخدام الأمر التالي:

az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}

لعرض سجلات العملية لنشر بيئة أو حذفها، استخدم Azure CLI لاسترداد أحدث عملية بيئة، ثم اعرض سجلات معرف العملية هذا.

# Get list of operations on the environment, choose the latest operation
az devcenter dev environment list-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
# Using the latest operation ID, view the operation logs
az devcenter dev environment show-logs-by-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME} --operation-id {LATEST_OPERATION_ID}

المحتوى ذو الصلة

• مرجع صورة مشغل مخصص ل ADE CLI
• مرجع متغيرات ADE CLI