نشر الموارد باستخدام قوالب ARM وAzure PowerShell

مقالة
06/14/2024

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

تلميح

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

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

تحتاج إلى قالب للتوزيع. إذا لم يكن لديك قالب بالفعل، فقم بتنزيل قالب مثال واحفظه من مستودع قوالب Azure Quickstart. اسم الملف المحلي المستخدم في هذه المقالة هو C:\MyTemplates\azuredeploy.json.

تحتاج إلى تثبيت Azure PowerShell والاتصال بـ Azure:

قم بتثبيت Azure PowerShell cmdlets على الكمبيوتر المحلي. لمزيد من المعلومات، راجع بدء استخدام Azure PowerShell.
قم بالاتصال بـ Azure باستخدام Connect-AZAccount. إذا كان لديك العديد من اشتراكات Azure، فقد تحتاج أيضًا إلى تشغيل Set-AzContext. لمزيد من المعلومات، راجع استخدام اشتراكات Azure المتعددة.

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

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

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

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

نطاق النشر

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

للنشر إلى مجموعة موارد، استخدم New-AzResourceGroupDeployment:

New-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -TemplateFile <path-to-template>

للنشر إلى اشتراك، استخدم New-AzSubscriptionDeployment وهو اسم مستعار لـ New-AzDeployment cmdlet:
```
New-AzSubscriptionDeployment -Location <location> -TemplateFile <path-to-template>
```
لمزيد من المعلومات عن النشر على مستوى الاشتراك، يُرجى الرجوع إلى إنشاء موارد ومجموعات موارد على مستوى الاشتراك.
للنشر في مجموعة إدارة، استخدم New-AzManagementGroupDeployment.
```
New-AzManagementGroupDeployment -Location <location> -TemplateFile <path-to-template>
```
لمزيد من المعلومات حول النشر على مستوى مجموعة الإدارة، راجع إنشاء موارد على مستوى مجموعة الإدارة.
للنشر إلى مستأجر، استخدم New-AzTenantDeployment.
```
New-AzTenantDeployment -Location <location> -TemplateFile <path-to-template>
```
لمزيد من المعلومات حول النشر على مستوى المستأجر، راجع إنشاء موارد على مستوى المستأجر.

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

اسم التوزيع

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

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

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

$suffix = Get-Random -Maximum 1000
$deploymentName = "ExampleDeployment" + $suffix

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

$today=Get-Date -Format "MM-dd-yyyy"
$deploymentName="ExampleDeployment"+"$today"

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

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

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

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

نشر قالب محلي

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

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

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

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

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile <path-to-template>

قد يستغرق النشر عدة دقائق حتى يكتمل.

نشر قالب بعيد

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

إشعار

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

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

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

New-AzResourceGroupDeployment `
  -Name remoteTemplateDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json

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

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

New-AzResourceGroupDeployment `
  -Name linkedTemplateWithRelativePath `
  -ResourceGroupName "myResourceGroup" `
  -TemplateUri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" `
  -QueryString "$sasToken"

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

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

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

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

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

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0 `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateJsonFile ./mainTemplate.json

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

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

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

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

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

تمرير قيم المعلمات

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

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

لتمرير معلمات مُضمنة، قم بتوفير أسماء المعلمة مع الأمر New-AzResourceGroupDeployment. على سبيل المثال، لتمرير سلسلة صفيف إلى قالب، استخدم:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString "inline string" `
  -exampleArray $arrayParam

يمكنك استخدام المعلمة TemplateParameterObject للتمرير عبر hashtable الذي يحتوي على معلمات القالب.

$params = @{
  exampleString = "inline string"
  exampleArray = "value1", "value2"
}

New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -TemplateParameterObject $params

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

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

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

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

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleArray $subnetArray

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

بدلاً من تمرير المعلمات كقيم مُضمنة في البرنامج النصي، قد تجد أنه من الأسهل استخدام ملف JSON الذي يحتوي على قيم المعلمة. يمكن أن يكون ملف المعلمة ملف محلي أو ملف خارجي مع عنوان URI يمكن الوصول إليها.

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

لتمرير ملف معلمة محلي، استخدم المعلمة TemplateParameterFile:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile <path-to-template> `
  -TemplateParameterFile c:\MyTemplates\storage.parameters.json

لتمرير ملف معلمة خارجي، استخدم المعلمة TemplateParameterUri:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json

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

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

باستخدام الإصدار 10.4.0 من Azure PowerShell أو أحدث، وإصدار Bicep CLI 0.22.6 أو أحدث، يمكنك نشر ملف قالب ARM باستخدام ملف معلمة Bicep. مع العبارة using داخل ملف معلمات Bicep، ليست هناك حاجة لتوفير -TemplateFile مفتاح التبديل عند تحديد ملف معلمة Bicep للتبديل -TemplateParameterFile .

يوضح المثال التالي ملف معلمات يسمى storage.bicepparam. الملف موجود في نفس الدليل حيث يتم تشغيل الأمر.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateParameterFile storage.bicepparam

لمزيد من المعلومات حول ملف معلمات Bicep، راجع ملف معلمات Bicep.

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

للرجوع إلى النشر الناجح عندما تحصل على خطأ، راجع التراجع عن الخطأ إلى نشر ناجح.
لتحديد كيفية معالجة الموارد الموجودة في مجموعة الموارد ولكن لم تُعرّف في القالب، راجع أوضاع نشر Azure Resource Manager.
لفهم كيفية تعريف المعلمات في القالب، راجع فهم بنية قوالب ARM وبناء الجملة لها.
للحصول على معلومات حول نشر قالب يتطلب رمز SAS المميز، راجع نشر قالب ARM خاص مع رمز SAS المميز.

مشاركة عبر