كيفية استخدام قوالب توزيع Azure Resource Manager (ARM) مع Azure CLI

  • مقالة

توضح هذه المقالة كيفية استخدام Azure CLI مع قوالب Azure Resource Manager (قوالب ARM) لتوزيع الموارد الخاصة بك إلى Azure. إذا لم تكن على دراية بمفاهيم نشر حلول Azure وإدارتها، اطلع على نظرة عامة على نشر القوالب.

تغيير أوامر التوزيع في الإصدار 2.2.0 من Azure CLI. تتطلب الأمثلة في هذه المقالة إصدار Azure CLI 2.20.0 أو أحدث.

لتشغيل هذا النموذج، يرجى تثبيت أحدث إصدار من Azure CLI . للبدء، يرجى تشغيل az login لإنشاء اتصال مع Azure.

كُتبت نماذج Azure CLI للواجهة bash. لتشغيل هذا النموذج في Windows PowerShell أو موجه الأوامر، يلزم تغيير عناصر البرنامج النصي.

إذا لم يكن لديك Azure CLI مثبتاً، فيمكنك استخدام Azure Cloud Shell. لمزيد من المعلومات، راجع توزيع قوالب ARM من Azure Cloud Shell.

تلميح

نوصي باستخدام Bicep لأنها تقدم نفس الإمكانات التي توفرها نماذج ARM ولأن البنية أسهل في الاستخدام. لمعرفة المزيد، راجع كيفية توزيع الموارد باستخدام Bicep وAzure CLI.

الأذونات المطلوبة

لتوزيع ملف Bicep أو قالب ARM، يلزم الوصول إلى الكتابة على الموارد التي تستخدمها والوصول إلى جميع العمليات على نوع المورد Microsoft.Resources/deployments. على سبيل المثال، لتوزيع جهاز ظاهري، تحتاج إلى أذونات Microsoft.Compute/virtualMachines/write وMicrosoft.Resources/deployments/*. عملية "ماذا لو" لها متطلبات الإذن نفسها.

للحصول على قائمة بالأدوار والأذونات، انظر أدوار Azure المضمنة.

نطاق النشر

يمكنك استهداف قالب توزيع Azure إلى مجموعة موارد أو اشتراك أو مجموعة إدارة أو مستأجر. اعتماداً على نطاق النشر، يمكنك استخدام أوامر مختلفة.

لكل نطاق، يجب أن يكون لدى المستخدم الذي يقوم بتوزيع القالب الأذونات المطلوبة لإنشاء الموارد.

نشر قالب محلي

يمكنك توزيع قالب ARM من الجهاز المحلي أو قالب مخزن خارجيًّا. يصف هذا القسم نشر قالب محلي.

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

az group create --name ExampleGroup --location "Central US"

لنشر قالب محلي، استخدم المعلمة --template-fileفي أمر النشر. يوضح المثال التالي أيضًا كيفية تعيين قيمة معلمة.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

يجب أن تكون قيمة المعلمة --template-file ملف Bicep أو ملف .json أو .jsonc. يشير ملحق الملف .jsonc إلى أن الملف يمكن أن يحتوي على تعليقات النمط //. يقبل نظام ARM التعليقات // في الملفات .json. لا يهتم بامتداد الملف. لمزيد من المعلومات حول التعليقات وبيانات التعريف، راجع فهم بناء جملة قوالب ARM وبنيتها.

قد يستغرق قالب توزيع Azure بضع دقائق للاكتمال. عند الانتهاء، سترى رسالة تتضمن النتيجة:

"provisioningState": "Succeeded",

نشر قالب بعيد

بدلا من تخزين قوالب ARM على جهازك المحلي، قد تفضل تخزينها في موقع خارجي. يمكنك تخزين القوالب في مستودع يتحكم بالمصادر (مثل GitHub). أو يمكنك تخزينها في حساب تخزين Azure للوصول المشترك إليها في مؤسستك.

إشعار

لتوزيع قالب أو الرجوع إلى قالب مرتبط مخزّن في مستودع GitHub خاص، راجع الحل المخصص الموثق في إنشاء عرض مدخل Microsoft Azure مخصص وآمن. يمكنك إنشاء Azure Function التي تسحب رمز GitHub المميز من Azure Key Vault.

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

az group create --name ExampleGroup --location "Central US"

لنشر قالب خارجي، استخدم المعلمة template-uri.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

يتطلب المثال السابق عنوان URI يمكن الوصول إليه بشكل عام للقالب، والذي يعمل لمعظم السيناريوهات لأنه لا يجب أن يتضمن القالب بيانات حساسة. إذا احتجت إلى تحديد بيانات حساسة (مثل كلمة مرور المسؤول)، قم بتمرير هذه القيمة كمعلمة آمنة. ومع ذلك، إن أردت إدارة الوصول إلى القالب، فضع في اعتبارك استخدام مواصفات القالب.

لتوزيع قوالب مرتبطة بعيدة ذات مسار نسبي مخزنة في حساب تخزين، استخدم query-string لتحديد رمز SAS المميز:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

لمزيد من المعلومات، راجع استخدام المسار النسبي للقوالب المرتبطة.

اسم قالب توزيع Azure

عند توزيع قالب ARM، يمكنك إعطاء قالب توزيع Azure اسمًا. يمكن أن يساعدك هذا الاسم في استرداد النشر من محفوظات النشر. إذا لم تُوفر اسمًا للنشر، يُستخدم اسم ملف القالب. على سبيل المثال، إذا قمت بتوزيع قالب مسمى azuredeploy.json ولم تحدد اسم توزيع، يُسمى التوزيع azuredeploy.

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

لإنشاء اسماً فريداً، يمكنك تعيين رقم عشوائي.

deploymentName='ExampleDeployment'$RANDOM

أو إضافة قيمة تاريخ.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

إذا قمت بتشغيل عمليات النشر المتزامنة إلى نفس مجموعة الموارد بنفس اسم النشر، فسيتم إكمال النشر الأخير فقط. تُستبدل أي عمليات نشر تحمل نفس الاسم، ولم تكتمل بعد، بعملية النشر الأخيرة. على سبيل المثال، إذا قمت بتشغيل نشر اسمه newStorage ينشر حساب تخزين مسمى storage1، وفي نفس الوقت قمت بتشغيل نشر آخر يسمى newStorage ينشر حساب تخزين مسمى storage2، فإنك تنشر حساب تخزين واحد فقط. يتم تسمية حساب التخزين الناتج بـ storage2.

ومع ذلك،، إذا قمت بتشغيل نشر اسمه newStorage ينشر حساب تخزين مسمى storage1، وبمجرد اكتماله قمت بتشغيل نشر آخر يسمى newStorage ينشر حساب تخزين مسمى storage2، فإنك تنشر حسابيّ تخزين. أحدهما يسمى storage1، والآخر يسمى storage2. ولكن لديك إدخال واحد فقط في محفوظات النشر.

عند تحديد اسم فريد لكل نشر، يمكنك تشغيلهم بشكل متزامن دون تعارض. إذا قمت بتشغيل نشر اسمه newStorage1 ينشر حساب تخزين مسمى storage1، وفي نفس الوقت قمت بتشغيل نشر آخر اسمه newStorage2 ينشر حساب تخزين مسمى storage2، فسيكون لديك حسابان للتخزين وإدخالان في محفوظات النشر.

لتجنب تعارض مع عمليات التوزيع المتزامنة ولضمان إدخالات فريدة في محفوظات التوزيع، قم بإعطاء كل توزيع اسمًا فريدًا.

مواصفات قالب التوزيع

بدلًا من نشر قالب محلي أو قالب بعيد، يمكنك إنشاء مواصفات قالب. مواصفات القالب هي مورد في اشتراك Azure الذي يحتوي على قالب ARM. فهو يسهل مشاركة القالب بأمان مع المستخدمين في مؤسستك. يمكنك استخدام التحكم في الوصول استنادًا إلى الدور (Azure RBAC) في Azure لمنح حق الوصول إلى مواصفات القالب. هذه الميزة قيد المعاينة حاليًّا.

توضح الأمثلة التالية كيفية إنشاء مواصفات قالب وتوزيعها.

أولًا، إنشاء مواصفات قالب عن طريق توفير قالب ARM.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

ثم، احصل على معرف مواصفات القالب وقم بتوزيعه.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

لمزيد من المعلومات، راجع مواصفات قالب Azure Resource Manager.

معاينة التغييرات

قبل نشر قالب ARM الخاص بك، يمكنك معاينة التغييرات التي يقوم بها القالب على بيئتك. استخدم عملية ماذا لو للتحقق من أن القالب يقوم بالتغييرات التي تتوقعها. عملية ماذا لو تقوم أيضًا بالتحقق من صحة القالب بحثًا عن الأخطاء.

المعلمات

لتمرير قيم المعلمات، يمكنك استخدام معلمات مضمنة أو ملف معلمات. يمكن أن يكون ملف المعلمة إما ملف معلمات Bicep أو ملف معلمات JSON.

المعلمات المُضمنة

لتمرير المعلمات المضمنة، يرجى توفير القيم في parameters. على سبيل المثال، لتمرير سلسلة وصفيف إلى قالب في Bash shell، استخدم:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

إذا كنت تستخدم Azure CLI مع Windows Command Prompt (CMD) أو PowerShell، قم بتمرير الصفيف بصيغة: exampleArray="['value1','value2']".

يمكنك أيضاً الحصول على محتويات الملف وتوفير هذا المحتوى كمعلمة مُضمنة.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

يُعد الحصول على قيمة معلمة من ملف مفيداً عندما تحتاج إلى توفير قيم التكوين. على سبيل المثال، يمكنك توفير قيم تهيئة السحابة لجهاز Linux ظاهري.

تنسيق arrayContent.json هو:

[
  "value1",
  "value2"
]

لتمرير كائن، على سبيل المثال، لتعيين علامات، استخدم JSON. على سبيل المثال، قد يتضمن القالب معلمة مثل هذه:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

في هذه الحالة، يمكنك تمرير سلسلة JSON لتعيين المعلمة كما هو موضح في البرنامج النصي Bash التالي:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

استخدام علامات الاقتباس المزدوجة حول JSON التي تريد تمريرها إلى الكائن.

يمكنك استخدام متغير لاحتواء قيم المعلمات. في Bash، قم بتعيين المتغير إلى كافة قيم المعلمة وإضافته إلى أمر النشر.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

ومع ذلك، إذا كنت تستخدم Azure CLI مع Windows Command Prompt (CMD) أو PowerShell، قم بتعيين المتغير إلى سلسلة JSON. الابتعاد عن علامات الاقتباس: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

ملفات معلمات JSON

بدلا من تمرير المعلمات كقيم مضمنة في البرنامج النصي الخاص بك، قد تجد أنه من الأسهل استخدام ملف معلمات، إما .bicepparam ملف أو ملف معلمات JSON، يحتوي على قيم المعلمات. يجب أن يكون ملف المعلمات ملفا محليا. ملفات المعلمات الخارجية غير مدعومة مع Azure CLI.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

لمزيد من المعلومات حول ملف المعلمة، راجع إنشاء ملف معلمة لمدير الموارد.

ملفات معلمات Bicep

باستخدام الإصدار 2.53.0 من Azure CLI أو أحدث، وإصدار Bicep CLI 0.22.6 أو أحدث، يمكنك نشر ملف Bicep باستخدام ملف معلمة Bicep. مع العبارة using داخل ملف معلمات Bicep، ليست هناك حاجة لتوفير --template-file مفتاح التبديل عند تحديد ملف معلمة Bicep للتبديل --parameters . يؤدي تضمين مفتاح التبديل إلى --template-file ظهور خطأ "يسمح فقط بقالب .bicep مع ملف .bicepparam".

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

يجب أن يكون ملف المعلمات ملفا محليا. ملفات المعلمات الخارجية غير مدعومة مع Azure CLI. لمزيد من المعلومات حول ملف المعلمات، راجع إنشاء ملف معلمات Resource Manager.

التعليقات وتنسيق JSON المُوسع

يمكنك تضمين تعليقات النمط // في ملف المعلمة، ولكن يجب تسمية الملف بملحق .jsonc.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

لمزيد من التفاصيل حول التعليقات وبيانات التعريف، راجع فهم بنية وبناء جملة قوالب ARM.

يمكنك توزيع قالب مع مجموعة سلاسل خطية أو تعليقات باستخدام التبديل --handle-extended-json-format إذا كنت تستخدم Azure CLI مع الإصدار 2.3.0 أو إصدار أقدم. على سبيل المثال:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

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