مشاركة عبر

إنشاء قالب Azure Image Builder Bicep أو قالب ARM JSON

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets

يستخدم Azure Image Builder ملف Bicep أو ملف قالب JSON لقالب ARM لتمرير المعلومات إلى خدمة Image Builder. في هذه المقالة، نستعرض أقسام الملفات، حتى تتمكن من إنشاء ملفاتك الخاصة. For latest API versions, see template reference. للاطلاع على أمثلة لملفات .json الكاملة، راجع Azure Image Builder GitHub.

التنسيق الأساسي هو:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "customize": [],
    "errorHandling":[],
    "distribute": [],
    "optimize": [],
    "source": {},
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "validate": {},
    "vmProfile": {
      "vmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
        "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
        "proxyVmSize": "<vmSize>"
      },
      "userAssignedIdentities": [
              "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName1>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName2>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName3>",
        ...
      ]
    }
  }
}

Follow all Best Practices while creating image templates.

API version

سيتغير إصدار واجهة برمجة التطبيقات بمرور الوقت مع تغير واجهة برمجة التطبيقات. راجع أحدث الميزات في Azure VM Image Builder لجميع تغييرات واجهة برمجة التطبيقات الرئيسية وتحديثات الميزات لخدمة Azure VM Image Builder.

Type

يُعد type نوع المورد، والذي يجب أن يكون Microsoft.VirtualMachineImages/imageTemplates.

"type": "Microsoft.VirtualMachineImages/imageTemplates",

Location

خدمة VM Image Builder متاحة في المناطق التالية:

Note

لا يزال بإمكانك توزيع الصور خارج هذه المناطق.

  • East US
  • شرق الولايات المتحدة 2
  • غرب وسط الولايات المتحدة
  • West US
  • غرب الولايات المتحدة 2
  • غرب الولايات المتحدة الأمريكية 3
  • جنوب وسط الولايات المتحدة
  • North Europe
  • West Europe
  • جنوب شرق آسيا
  • Australia Southeast
  • Australia East
  • UK South
  • UK West
  • Brazil South
  • Canada Central
  • Central India
  • Central US
  • France Central
  • وسط غرب ألمانيا
  • Japan East
  • وسط شمال الولايات المتحدة
  • Norway East
  • Switzerland North
  • جيو الهند الغربية
  • UAE North
  • East Asia
  • Korea Central
  • جنوب أفريقيا
  • Qatar Central
  • USGov أريزونا (إصدار أولي للاستخدام العام)
  • USGov فرجينيا (إصدار أولي للاستخدام العام)
  • شمال الصين 3 (معاينة عامة)
  • Sweden Central
  • Poland Central
  • Italy North
  • Israel Central
  • شمال نيوزيلندا
  • Taiwan Northwest

Important

قم بتسجيل الميزة Microsoft.VirtualMachineImages/FairfaxPublicPreview للوصول إلى المعاينة العامة لـ Azure Image Builder في مناطق Azure Government (USGov Arizona و USGov Virginia).

Important

سجل الميزة Microsoft.VirtualMachineImages/MooncakePublicPreview للوصول إلى المعاينة العامة ل Azure Image Builder في منطقة شمال الصين 3.

To access the Azure VM Image Builder public preview in the Azure Government regions (USGov Arizona and USGov Virginia), you must register the Microsoft.VirtualMachineImages/FairfaxPublicPreview feature. للقيام بذلك، قم بتشغيل الأمر التالي إما في PowerShell أو Azure CLI:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

To access the Azure VM Image Builder public preview in the China North 3 region, you must register the Microsoft.VirtualMachineImages/MooncakePublicPreview feature. للقيام بذلك، قم بتشغيل الأمر التالي إما في PowerShell أو Azure CLI:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Data residency

تحتفظ خدمة Azure VM Image Builder ببيانات العملاء داخل المناطق التي لديها قواعد موقع بيانات صارمة. إذا كان انقطاع الخدمة للمناطق التي لديها متطلبات موقع البيانات، تحتاج إلى إنشاء ملفات/قوالب Bicep في منطقة وجغرافية مختلفة.

Zone redundancy

يدعم التوزيع تكرار المنطقة، ويتم توزيع الأقراص الصلبة الظاهرية (VHDs) إلى حساب التخزين المتكرر للمنطقة (ZRS) بشكل افتراضي، وسيدعم إصدار Azure Compute Gallery (المعروف سابقا باسم معرض الصور المشتركة) نوع تخزين ZRS إذا تم تحديده.

Tags

العلامات هي أزواج مفتاح/قيمة يمكنك تحديدها للصورة التي تم إنشاؤها.

Identity

هناك طريقتان لإضافة الهويات المعينة من قِبَل المستخدم الموضحة أدناه.

الهوية المعينة من قِبَل المستخدم لمورد قالب Azure Image Builder

مطلوب - لكي يكون لدى Image Builder أذونات لقراءة/كتابة الصور، وقراءة البرامج النصية من Azure Storage، يجب عليك إنشاء هوية معيّنة من قبل مستخدم Azure لها أذونات إلى الموارد الفردية. للحصول على تفاصيل حول كيفية عمل أذونات Image Builder، والخطوات ذات الصلة، راجع إنشاء صورة واستخدام هوية مُدارة معينة من قبل المستخدم للوصول إلى الملفات في حساب تخزين Azure.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<imgBuilderId>": {}
    }
}

الهوية المعينة من قِبَل مستخدم خدمة Image Builder:

  • تدعم هوية واحدة فقط.
  • لا تدعم أسماء المجالات المخصصة.

لمعرفة المزيد، راجع ما هي الهويات المدارة لموارد Azure؟. لمزيد من المعلومات حول نشر هذه الميزة، راجع تكوين الهويات المدارة لموارد Azure على Azure VM باستخدام Azure CLI.

الهوية المعينة من قبل المستخدم لـ Image Builder Build VM

هذه الخاصية متاحة فقط في إصدارات API2021-10-01 أو أحدث.

اختياري - يتم استخدام الجهاز الظاهري لإنشاء منشئ الصور الذي تم إنشاؤه بواسطة خدمة Image Builder في اشتراكك لإنشاء الصورة وتخصيصها. لكي يحصل Image Builder Build VM على أذونات المصادقة مع خدمات أخرى مثل Azure Key Vault في اشتراكك، يجب عليك إنشاء Azure User Assigned Identities واحدة أو أكثر تتضمن أذونات للموارد الفردية. يمكن لـ Azure Image Builder بعد ذلك إقران هذه الهويات المعينة من قِبَل المستخدم بـ Build VM. يمكن للبرامج النصية المخصصة التي تعمل داخل Build VM بعد ذلك جلب الرموز المميزة لهذه الهويات والتفاعل مع موارد Azure الأخرى حسب الحاجة. يجب أن تعلم أن الهوية المعينة من قِبَل المستخدم لمنشئ الصور في Azure يجب أن يكون لديها تعيين دور "عامل الهوية المُدارة" على جميع الهويات المعينة من قِبَل المستخدم لمنشئ الصور في Azure حتى تتمكن من ربطها بالجهاز الظاهري للإنشاء.

Note

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

"properties": {
  "vmProfile": {
    "userAssignedIdentities": [
      "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
    ]
  }
}

الهوية المعينة من قِبَل مستخدم Image Builder Build VM:

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

لمعرفة المزيد، راجع:

Properties: buildTimeoutInMinutes

المدة القصوى للانتظار أثناء إنشاء قالب الصورة (بما في ذلك جميع التخصيصات وعمليات التحقق من الصحة والتوزيعات).

إذا لم تحدد الخاصية أو تعين القيمة إلى 0، فسيتم استخدام القيمة الافتراضية، وهي 240 دقيقة أو أربع ساعات. الحد الأدنى للقيمة هو 6 دقائق، والحد الأقصى للقيمة هو 960 دقيقة أو 16 ساعة. عند الوصول إلى قيمة المهلة (سواء اكتمل بناء الصورة أم لا)، سترى خطأ مشابها لما يلي:

[ERROR] Failed while waiting for packerizer: Timeout waiting for microservice to
[ERROR] complete: 'context deadline exceeded'

بالنسبة لنظام التشغيل Windows، لا نوصي بتعيين buildTimeoutInMinutesأقل من 60 دقيقة. If you find you're hitting the timeout, review the logs to see if the customization step is waiting on something like user input. إذا وجدت أنك بحاجة إلى مزيد من الوقت لإكمال التخصيصات، فقم بزيادة buildTimeoutInMinutes القيمة. لكن، لا تقم بتعينه على وقت مرتفع للغاية لأنك قد تضطر إلى الانتظار حتى تنتهي مهلته قبل رؤية خطأ.

Properties: customize

يدعم "منشئ الصور" العديد من "التخصيصات"، وهي وظائف تستخدم لتخصيص صورتك، مثل تشغيل البرامج النصية أو إعادة تشغيل الخوادم.

عند استخدام customize:

  • يمكنك استخدام أدوات تخصيص متعددة.
  • تقوم أدوات التخصيص بالتنفيذ بالترتيب المحدد في القالب.
  • إذا فشلت إحدى أدوات التخصيص، فسيفشل مكون التخصيص بأكمله ويبلغ عن خطأ.
  • اختبر البرامج النصية بدقة قبل استخدامها في قالب. تصحيح أخطاء البرامج النصية في حد ذاتها أسهل.
  • لا تضع بيانات حساسة في البرامج النصية. يمكن عرض الأوامر المضمنة في تعريف قالب الصورة. إذا كانت لديك معلومات حساسة (بما في ذلك كلمات المرور ورمز SAS المميز ورموز المصادقة المميزة وما إلى ذلك)، فيجب نقلها إلى البرامج النصية في Azure Storage، حيث يتطلب الوصول المصادقة.
  • يجب أن تكون مواقع البرامج النصية متاحة للجميع، إلا إذا كنت تستخدم هوية معينة من قبل المستخدم.

إن القسمcustomize عبارة عن صفيف. أنواع التخصيص المدعومة هي: File وPowerShell وShell وWindowsRestart وWindowsUpdate.

"customize": [
  {
    "type": "File",
    "destination": "string",
    "sha256Checksum": "string",
    "sourceUri": "string"
  },
  {
    "type": "PowerShell",
    "inline": [ "string" ],
    "runAsSystem": "bool",
    "runElevated": "bool",
    "scriptUri": "string",
    "sha256Checksum": "string",
    "validExitCodes": [ "int" ]
  },
  {
    "type": "Shell",
    "inline": [ "string" ],
    "scriptUri": "string",
    "sha256Checksum": "string"
  },
  {
    "type": "WindowsRestart",
    "restartCheckCommand": "string",
    "restartCommand": "string",
    "restartTimeout": "string"
  },
  {
    "type": "WindowsUpdate",
    "filters": [ "string" ],
    "searchCriteria": "string",
    "updateLimit": "int"
  }
]

Shell customizer

Shell يدعم التخصيص تشغيل البرامج النصية shell على Linux. The shell scripts must be publicly accessible or you must have configured an MSI for Image Builder to access them.

"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<link to script>",
    "sha256Checksum": "<sha256 checksum>"
  }
],
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "inline": "<commands to run>"
  }
]

Customize properties:

  • type – Shell.

  • name - name for tracking the customization.

  • scriptUri - URI to the location of the file.

  • inline - array of shell commands, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this value locally, and then Image Builder will checksum and validate.

    لإنشاء المجموع الاختباري sha256Checksum، باستخدام محطة طرفية على Mac/Linux شغّل: sha256sum <fileName>

Note

يتم تخزين الأوامر المضمنة كجزء من تعريف قالب الصورة، التي يمكنك رؤيتها عند تفريغ تعريف الصورة. إذا كانت لديك أوامر أو قيم حساسة (بما في ذلك كلمات المرور ورمز SAS المميز ورموز المصادقة وما إلى ذلك)، فمن المستحسن نقلها إلى البرامج النصية واستخدام هوية مستخدم للمصادقة على Azure Storage.

امتيازات المستخدم المتميز

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

"type": "Shell",
"name": "setupBuildPath",
"inline": [
    "sudo mkdir /buildArtifacts",
    "sudo cp /tmp/index.html /buildArtifacts/index.html"
]

مثال على برنامج نصي يستخدم sudo يمكنك الرجوع إليه باستخدام scriptUri:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

echo "Telemetry: running sudo 'as-is' in a script"
sudo touch /myfiles/somethingElevated.txt

أداة تخصيص إعادة التشغيل في Windows

تسمح لك WindowsRestart أداة التخصيص بإعادة تشغيل جهاز Windows VM وانتظار عودة الجهاز الظاهري إلى الاتصال بالإنترنت، ويسمح لك هذا المُخصص بتثبيت برنامج يتطلب إعادة تشغيل الكمبيوتر.

"customize": [
  {
    "type": "WindowsRestart",
    "restartCommand": "shutdown /r /f /t 0",
    "restartCheckCommand": "echo Azure-Image-Builder-Restarted-the-VM  > c:\\buildArtifacts\\azureImageBuilderRestart.txt",
    "restartTimeout": "5m"
  }
]

Customize properties:

  • Type: WindowsRestart.
  • restartCommand - Command to execute the restart (optional). الافتراضي هو 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand – Command to check if restart succeeded (optional).
  • restartTimeout - Restart time out specified as a string of magnitude and unit. على سبيل المثال، 5m (5 دقائق) أو 2h (ساعتين). القيمة الافتراضية هي: 5m.

Note

لا توجد أداة تخصيص لإعادة تشغيل Linux.

PowerShell customizer

يدعم المخصص PowerShell تشغيل البرامج النصية PowerShell والأمر المضمن على Windows، ويجب أن تكون البرامج النصية متاحة للجميع حتى تتمكن الخدمة من الوصول إليها.

"customize": [
  {
    "type": "PowerShell",
    "name":   "<name>",
    "scriptUri": "<path to script>",
    "runElevated": <true false>,
    "runAsSystem": <true false>,
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "PowerShell",
    "name": "<name>",
    "inline": "<PowerShell syntax to run>",
    "validExitCodes": [<exit code>],
    "runElevated": <true or false>,
    "runAsSystem": <true or false>
  }
]

Customize properties:

  • type – PowerShell.

  • scriptUri - URI to the location of the PowerShell script file.

  • inline – Inline commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command. تتجنب الخاصية فشل البرنامج النصي/الأمر المضمن الذي تم الإبلاغ عنه.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • runAsSystem - Optional, boolean, determines whether the PowerShell script should be run as the System user.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

File customizer

تتيح File أداة تخصيص الملفات لـ Image Builder تنزيل ملف من GitHub repo أو Azure storage. يدعم التخصيص كلاً من Linux وWindows. إذا كانت لديك بنية أساسية لإنشاء صورة تعتمد على إنشاء البيانات الاصطناعية، يمكنك تعيين أداة تخصيص الملفات للتنزيل من مشاركة الإنشاء، ونقل البيانات الاصطناعية إلى الصورة.

"customize": [
  {
    "type": "File",
    "name": "<name>",
    "sourceUri": "<source location>",
    "destination": "<destination>",
    "sha256Checksum": "<sha256 checksum>"
  }
]

خصائص أداة تخصيص الملفات:

  • sourceUri - an accessible storage endpoint, this endpoint can be GitHub or Azure storage. يمكنك تنزيل ملف واحد فقط، وليس دليلاً كاملاً. إذا كنت بحاجة إلى تنزيل دليل، فاستخدم ملفاً مضغوطاً، ثم قم بإلغاء ضغطه باستخدام أدوات تخصيص Shell أو PowerShell.

    Note

    إذا كان sourceUri هو حساب تخزين Azure، بغض النظر عما إذا تم وضع علامة عام على الكائن الثنائي كبير الحجم، فستحتاج إلى منح أذونات هوية المستخدم المدارة لقراءة الوصول على الكائن الثنائي كبير الحجم. See this example to set the storage permissions.

  • destination – the full destination path and file name. يجب أن يوجد أي مسار مرجعي وأدلة فرعية، استخدم أدوات تخصيص Shell أو PowerShell لإعداد هذه المسارات مسبقًا. يمكنك استخدام أدوات تخصيص البرنامج النصي لإنشاء المسار.

يتم دعم أداة التخصيص هذه بواسطة أدلة Windows ومسارات Linux، ولكن هناك بعض الاختلافات:

  • Linux - المسار الوحيد الذي يمكن لمنشئ الصورة الكتابة إليه هو / tmp.
  • Windows - لا يوجد تقييد على المسار، ولكن يجب أن يكون المسار موجوداً.

إذا كان هناك خطأ أثناء محاولة تنزيل الملف، أو وضعه في دليل محدد، ففشل تخصيص الخطوة، وسيكون هذا الخطأ في customization.log.

Note

أداة تخصيص الملفات مناسبة فقط لتنزيلات الملفات الصغيرة، < 20 ميجابايت. بالنسبة لتنزيلات الملفات الأكبر حجماً، استخدم برنامجاً نصياً أو أمراً مضمناً، ثم استخدم التعليمات البرمجية لتنزيل الملفات، مثل Linux wget أو curl، أو Windows، Invoke-WebRequest. بالنسبة إلى الملفات الموجودة في تخزين Azure، تأكد من تعيين هوية بأذونات لعرض هذا الملف إلى الجهاز الظاهري للبناء باتباع الوثائق هنا: الهوية المعينة من قبل المستخدم ل Image Build VM. يجب أن يكون أي ملف غير مخزن في Azure متاحا للجمهور حتى يتمكن Azure Image Builder من تنزيله.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

مُخصص تحديث Windows

تم WindowsUpdateبناء أداة التخصيص على مجتمع Windows Update Provisioner لـ Packer، وهو مشروع مفتوح المصدر تتم صيانته بواسطة مجتمع Packer. تقوم Microsoft باختبار الموفر والتحقق من صحته باستخدام خدمة Image Builder، وستدعم التحقيق في المشكلات معها، وتعمل على حل المشكلات، ومع ذلك، فإن المشروع مفتوح المصدر غير مدعوم رسميًا من قبل Microsoft. للحصول على وثائق مفصلة والمساعدة حول مقدم خدمة Windows Update، يرجى الاطلاع على مستودع المشروع.

"customize": [
  {
    "type": "WindowsUpdate",
    "searchCriteria": "IsInstalled=0",
    "filters": [
      "exclude:$_.Title -like '*Preview*'",
      "include:$true"
    ],
    "updateLimit": 20
  }
]

Customizer properties:

  • type – WindowsUpdate.
  • searchCriteria - Optional, defines which type of updates are installed (like Recommended or Important), BrowseOnly=0 and IsInstalled=0 (Recommended) is the default.
  • filters – Optional, allows you to specify a filter to include or exclude updates.
  • updateLimit – Optional, defines how many updates can be installed, default 1000.

Note

يمكن أن تفشل أداة تخصيص Windows Update إذا كانت هناك أي عمليات إعادة تشغيل Windows معلقة، أو عمليات تثبيت التطبيقات التي لا تزال قيد التشغيل، وعادة ما قد ترى هذا الخطأ في التخصيص.log، System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. We strongly advise you consider adding in a Windows Restart, and/or allowing applications enough time to complete their installations using sleep or wait commands in the inline commands or scripts before running Windows Update.

Generalize

بشكل افتراضي، ستقوم Azure Image Builder أيضاً بتشغيل التعليمة البرمجية deprovision في نهاية كل مرحلة تخصيص صورة، لتعميم الصورة. التعميم هو عملية يتم فيها إعداد الصورة بحيث يمكن إعادة استخدامها لإنشاء أجهزة ظاهرية متعددة. بالنسبة لأجهزة Windows الظاهرية، تستخدم Azure Image Builder Sysprep. بالنسبة لنظام التشغيل Linux، تشغل Azure Image Builder waagent -deprovision.

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

إذا كنت تقوم بترحيل التخصيص الموجود، وكنت تستخدم أوامر Sysprep/waagent مختلفة، فيمكنك استخدام الأوامر العامة لـ Image Builder، وإذا فشل إنشاء الجهاز الظاهري، فاستخدم أوامر Sysprep أو waagent الخاصة بك.

إذا قام Azure Image Builder بإنشاء صورة مخصصة ل Windows بنجاح، وقمت بإنشاء جهاز ظاهري منها، ثم وجدت أن إنشاء الجهاز الظاهري فشل أو لم يكتمل بنجاح، فأنت بحاجة إلى مراجعة وثائق Windows Server Sysprep أو رفع طلب دعم مع فريق دعم خدمات العملاء في Windows Server Sysprep، الذي يمكنه استكشاف أخطاء استخدام Sysprep الصحيح وتقديم المشورة بشأنه.

أمر Sysprep الافتراضي

Write-Output '>>> Waiting for GA Service (RdAgent) to start ...'
while ((Get-Service RdAgent).Status -ne 'Running') { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureTelemetryService) to start ...'
while ((Get-Service WindowsAzureTelemetryService) -and ((Get-Service WindowsAzureTelemetryService).Status -ne 'Running')) { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureGuestAgent) to start ...'
while ((Get-Service WindowsAzureGuestAgent).Status -ne 'Running') { Start-Sleep -s 5 }
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Write-Output '>>> Removing Sysprep\unattend.xml ...'
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
if (Test-Path $Env:SystemRoot\Panther\unattend.xml) {
  Write-Output '>>> Removing Panther\unattend.xml ...'
  Remove-Item $Env:SystemRoot\Panther\unattend.xml -Force
}
Write-Output '>>> Sysprepping VM ...'
& $Env:SystemRoot\System32\Sysprep\Sysprep.exe /oobe /generalize /quiet /quit
while($true) {
  $imageState = (Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\State).ImageState
  Write-Output $imageState
  if ($imageState -eq 'IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE') { break }
  Start-Sleep -s 5
}
Write-Output '>>> Sysprep complete ...'

أمر إلغاء توفير Linux الافتراضي

WAAGENT=/usr/sbin/waagent
waagent -version 1> /dev/null 2>&1
if [ $? -eq 0 ]; then
  WAAGENT=waagent
fi
$WAAGENT -force -deprovision+user && export HISTSIZE=0 && sync

تجاوز الأوامر

لتجاوز الأوامر، استخدم موفري البرامج النصية PowerShell أو Shell لإنشاء ملفات الأوامر باسم الملف الدقيق، ووضعها في الأدلة الصحيحة:

  • Windows: c:\DeprovisioningScript.ps1
  • Linux: /tmp/DeprovisioningScript.sh

يقرأ "منشئ الصور" هذه الأوامر، وتتم كتابة هذه الأوامر في سجلات AIB، customization.log. See troubleshooting on how to collect logs.

Properties: errorHandling

errorHandling تسمح لك الخاصية بتكوين كيفية معالجة الأخطاء أثناء إنشاء الصورة.

{
  "errorHandling": {
    "onCustomizerError": "abort",
    "onValidationError": "cleanup"
  }
}

errorHandling تسمح لك الخاصية بتكوين كيفية معالجة الأخطاء أثناء إنشاء الصورة. يحتوي على خاصيتين:

  • onCustomizerError - Specifies the action to take when an error occurs during the customizer phase of image creation.
  • onValidationError - Specifies the action to take when an error occurs during validation of the image template.

تحتوي errorHandling الخاصية أيضا على قيمتين محتملتين لمعالجة الأخطاء أثناء إنشاء الصورة:

  • cleanup - Ensures that temporary resources created by Packer are cleaned up even if Packer or one of the customizations/validations encounters an error. يحافظ هذا على التوافق مع الإصدارات السابقة مع السلوك الحالي.
  • abort - In case Packer encounters an error, the Azure Image Builder (AIB) service skips the clean up of temporary resources. بصفتك مالك قالب AIB، فأنت مسؤول عن تنظيف هذه الموارد من اشتراكك. قد تحتوي هذه الموارد على معلومات مفيدة مثل السجلات والملفات المتبقية في جهاز ظاهري مؤقت، والتي يمكن أن تساعد في التحقيق في الخطأ الذي واجهه Packer.

Properties: distribute

تدعم Azure Image Builder ثلاثة أهداف توزيع:

  • ManagedImage - Managed image.
  • sharedImage - Azure Compute Gallery.
  • VHD - VHD in a storage account.

يمكنك توزيع صورة على النوعين كليهما من الأهداف في التكوين نفسه.

Note

لا يتضمن أمر AIB sysprep الافتراضي "/ mode: vm"، ولكن قد تكون هذه الخاصية مطلوبة عند إنشاء الصور التي سيتم تثبيت دور HyperV عليها. إذا كنت بحاجة إلى إضافة وسيطة الأمر هذه، يجب تجاوز الأمر sysprep.

ونظراً لأنه يمكن أن يكون لديك أكثر من هدف واحد للتوزيع عليه، تحتفظ Image Builder بحالة لكل هدف توزيع يمكن الوصول إليه عن طريق الاستعلام عن runOutputName. الكائن runOutputName هو كائن يمكنك استخدامه في الاستعلام عن التوزيع للحصول على معلومات حول ذلك التوزيع. على سبيل المثال، يمكنك الاستعلام عن موقع VHD، أو المناطق التي تم نسخ إصدار الصورة إليها، أو إنشاء إصدار SIG Image. هذه خاصية لكل هدف توزيع. يجب أن يكون runOutputName فريد لكل هدف توزيع. فيما يلي مثال على ذلك، هذا هو الاستعلام عن توزيع Azure Compute Gallery:

subscriptionID=<subcriptionID>
imageResourceGroup=<resourceGroup of image template>
runOutputName=<runOutputName>

az resource show \
  --ids "/subscriptions/$subscriptionID/resourcegroups/$imageResourceGroup/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/$runOutputName" \
--api-version=2023-07-01

Output:

{
  "id": "/subscriptions/xxxxxx/resourcegroups/rheltest/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/rhel77",
  "identity": null,
  "kind": null,
  "location": null,
  "managedBy": null,
  "name": "rhel77",
  "plan": null,
  "properties": {
    "artifactId": "/subscriptions/xxxxxx/resourceGroups/aibDevOpsImg/providers/Microsoft.Compute/galleries/devOpsSIG/images/rhel/versions/0.24105.52755",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "rheltest",
  "sku": null,
  "tags": null,
  "type": "Microsoft.VirtualMachineImages/imageTemplates/runOutputs"
}

Distribute: managedImage

إخراج الصورة هو مورد صورة مدار.

{
  "type":"ManagedImage",
  "imageId": "<resource ID>",
  "location": "<region>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Distribute properties:

  • type – ManagedImage
  • imageId – Resource ID of the destination image, expected format: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location - location of the managed image.
  • runOutputName – unique name for identifying the distribution.
  • artifactTags - Optional user specified key\value tags.

Note

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

Distribute: sharedImage

Azure Compute Gallery هي خدمة جديدة لإدارة الصور تسمح بإدارة النسخ المتماثل لمنطقة الصورة وتعيين الإصدار ومشاركة الصور المخصصة. تدعم Azure Image Builder التوزيع باستخدام هذه الخدمة، بحيث يمكنك توزيع الصور على المناطق التي تدعمها Azure Compute Galleries.

يتكون Azure Compute Gallery من:

  • Gallery - Container for multiple images. يتم نشر المعرض في منطقة واحدة.
  • Image definitions - a conceptual grouping for images.
  • Image versions - an image type used for deploying a VM or scale set. يمكن نسخ إصدارات الصور إلى مناطق أخرى حيث يلزم نشر الأجهزة الظاهرية.

قبل أن تتمكن من التوزيع على المعرض، يجب عليك إنشاء تعريف للصورة ومعرض، راجع إنشاء معرض.

Note

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

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

JSON التالي هو مثال على كيفية استخدام replicationRegions الحقل لتوزيعه على معرض حوسبة Azure.

  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]

Note

replicationRegions مهمل لتوزيعات المعرض كما targetRegions يتم تحديث الخاصية. For more information, see targetRegions.

Distribute: targetRegions

JSON التالي هو مثال على كيفية استخدام حقل targetRegions للتوزيع على معرض حوسبة Azure.

"distribute": [
      {
        "type": "SharedImage",
        "galleryImageId": "<resource ID>",
        "runOutputName": "<name>",
        "artifactTags": {
          "<name>": "<value>",
          "<name>": "<value>"
        },
        "targetRegions": [
             {
              "name": "eastus",
              "replicaCount": 2,
              "storageAccountType": "Standard_ZRS"
             },
             {
              "name": "eastus2",
              "replicaCount": 3,
              "storageAccountType": "Premium_LRS"
             }
          ]
       },
    ]

توزيع خصائص المعارض:

  • type - sharedImage

  • galleryImageId – ID of the Azure Compute Gallery, this property can be specified in two formats:

    • تعيين الإصدار التلقائي - ينشئ "منشئ الصور" رقم إصدار رتيبا لك، وهذه الخاصية مفيدة عندما تريد الاحتفاظ بإعادة إنشاء الصور من نفس القالب: التنسيق هو: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • تعيين الإصدار الصريح - يمكنك تمرير رقم الإصدار الذي تريد أن يستخدمه منشئ الصور. التنسيق هو: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>

  • runOutputName – unique name for identifying the distribution.

  • artifactTags - optional user specified key\value tags.

  • replicationRegions - array of regions for replication. يجب أن تكون إحدى المناطق هي المنطقة التي يتم فيها نشر المعرض. إضافة مناطق تعني زيادة وقت الإنشاء، حيث لا يكتمل البناء حتى يكتمل النسخ المتماثل. تم إهمال هذا الحقل اعتبارا من إصدار API 2022-07-01، يرجى استخدامه targetRegions عند توزيع نوع "SharedImage".

  • targetRegions - an array of regions for replication. It's newly introduced as part of the 2022-07-01 API and applies only to the SharedImage type distribute.

  • excludeFromLatest (optional) - allows you to mark the image version you create not be used as the latest version in the gallery definition, the default is 'false'.

  • storageAccountType (optional) - AIB supports specifying these types of storage for the image version that is to be created:

    • "Standard_LRS"
    • "Standard_ZRS","

Note

إذا لم يكن قالب الصورة وimage definition المشار إليه في الموقع نفسه، فسترى وقتًا إضافيًا لإنشاء الصور. لا تحتوي Image Builder حالياً على معلمة location لمورد إصدار الصورة، بل نأخذها من أصلها image definition. على سبيل المثال، إذا كان تعريف الصورة موجودًا وwestusتريد نسخ نسخة الصورة إليهeastus، يتم نسخ blob إليه، وwestusيتم إنشاء مورد إصدار صورة فيهwestus، ثم النسخ المتماثل إليهeastus. لتجنب وقت النسخ المتماثل الإضافي، تأكد من وجود image definition وقالب الصورة في الموقع نفسه.

versioning

The versioning property is for the sharedImage distribute type only. إنه تعداد بقيمتين محتملتين:

  • latest - New strictly increasing schema per design
  • source - Schema based upon the version number of the source image.

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

Note

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

    "distribute": [
        "versioning": {
            "scheme": "Latest",
            "major": 1
        }
    ]

versioning properties:

  • scheme - Generate new version number for distribution. Latest أو Source قيمتان محتملتان.
  • major - Specifies the major version under which to generate the latest version. ينطبق فقط عند scheme تعيين إلى Latest. على سبيل المثال، في معرض مع الإصدارات التالية المنشورة: 0.1.1، 0.1.2، 1.0.0، 1.0.1، 1.1.0، 1.1.1، 1.2.0، 2.0.0، 2.0.1، 2.1.0
    • مع تعيين رئيسي أو تعيين رئيسي إلى 2، Latest ينشئ النظام الإصدار 2.1.1
    • مع تعيين رئيسي إلى 1، ينشئ أحدث نظام الإصدار 1.2.1
    • مع تعيين رئيسي إلى 0، ينشئ أحدث نظام الإصدار 0.1.3

Distribute: VHD

يمكنك الإخراج إلى VHD. يمكنك بعد ذلك نسخ VHD، واستخدامه للنشر إلى Azure MarketPlace، أو استخدامه مع Azure Stack.

{
  "type": "VHD",
  "runOutputName": "<VHD name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

دعم نظام التشغيل: Windows وLinux

توزيع معلمات VHD:

  • type - VHD.
  • runOutputName – unique name for identifying the distribution.
  • tags - Optional user specified key value pair tags.

لا تسمح Azure Image Builder للمستخدم بتحديد موقع حساب تخزين، ولكن يمكنك الاستعلام عن حالة runOutputs للحصول على الموقع.

az resource show \
  --ids "/subscriptions/$subscriptionId/resourcegroups/<imageResourceGroup>/providers/Microsoft.VirtualMachineImages/imageTemplates/<imageTemplateName>/runOutputs/<runOutputName>"  | grep artifactUri

Note

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

يوزع JSON التالي الصورة ك VHD إلى حساب تخزين مخصص.

"distribute": [
  {
    "type": "VHD",
    "runOutputName": "<VHD name>",
    "artifactTags": {
        "<name>": "<value>",
        "<name>": "<value>"
    },
    "uri": "<replace with Azure storage URI>"
  }
]

توزيع خصائص VHD:

uri - Optional Azure Storage URI for the distributed VHD blob. حذف استخدام الافتراضي (سلسلة فارغة) في هذه الحالة سيتم نشر VHD إلى حساب التخزين في مجموعة الموارد المرحلية.

Properties: optimize

optimize يمكن تمكين الخاصية أثناء إنشاء صورة جهاز ظاهري وتسمح بتحسين الجهاز الظاهري لتحسين وقت إنشاء الصورة.

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: A configuration related to the booting process of the virtual machine (VM), used to control optimizations that can improve boot time or other performance aspects.
  • الحالة: حالة ميزة تحسين التمهيد داخل vmBoot، مع القيمة Enabled التي تشير إلى أن الميزة قيد التشغيل لتحسين وقت إنشاء الصور.

لمعرفة المزيد، راجع تحسين الجهاز الظاهري لصور المعرض باستخدام Azure VM Image Builder.

Properties: source

يحتوي القسم source على معلومات حول الصورة المصدر التي سيستخدمها Image Builder. يدعم Azure Image Builder الصور المعممة فقط كصور مصدر، ولا يتم دعم الصور المتخصصة في الوقت الحالي.

تتطلب واجهة برمجة التطبيقات SourceType الذي يحدد مصدر إنشاء الصورة، وهناك حالياً ثلاثة أنواع:

  • PlatformImage - وهو يشير إلى أن الصورة المصدر هي صورة Marketplace.
  • ManagedImage - تُستخدم عند البدء من صورة مُدارة عادية.
  • SharedImageVersion - يُستخدم عند استخدام إصدار صورة في Azure Compute Gallery كمصدر.

Note

When using existing Windows custom images, you can run the Sysprep command up to three times on a single Windows 7 or Windows Server 2008 R2 image, or 1001 times on a single Windows image for later versions; for more information, see the sysprep documentation.

PlatformImage source

يدعم Azure Image Builder خادم Windows وعميله، وصور Linux Azure Marketplace، راجع التعرف على Azure Image Builder للحصول على القائمة الكاملة.

"source": {
  "type": "PlatformImage",
  "publisher": "Canonical",
  "offer": "UbuntuServer",
  "sku": "18.04-LTS",
  "version": "latest"
}

تعد الخصائص هنا هي الخصائص نفسها المستخدمة لإنشاء أجهزة VM، باستخدام AZ CLI قم بتشغيل ما يلي للحصول على الخصائص:

az vm image list -l westus -f UbuntuServer -p Canonical --output table --all

يمكنك استخدام latest في الإصدار، حيث يتم تقييم الإصدار عند إنشاء الصورة، وليس عند إرسال القالب. إذا كنت تستخدم هذه الوظيفة مع وجهة Azure Compute Gallery، يمكنك تجنب إعادة إرسال القالب، وإعادة تشغيل بنية الصورة على فترات، بحيث تتم إعادة إنشاء صورك من أحدث الصور.

دعم معلومات خطة السوق

يمكنك أيضاً تحديد معلومات الخطة، على سبيل المثال:

"source": {
  "type": "PlatformImage",
  "publisher": "RedHat",
  "offer": "rhel-byos",
  "sku": "rhel-lvm75",
  "version": "latest",
  "planInfo": {
    "planName": "rhel-lvm75",
    "planProduct": "rhel-byos",
    "planPublisher": "redhat"
  }
}

ManagedImage source

يضبط الصورة المصدر كصورة مدارة موجودة لـ VHD أو VM معمم.

Note

يجب أن تكون الصورة المدارة المصدر من نظام تشغيل مدعوم ويجب أن تكون الصورة موجودة في الاشتراك والمنطقة نفسها الموجود فيها قالب Azure Image Builder.

"source": {
  "type": "ManagedImage",
  "imageId": "/subscriptions/<subscriptionId>/resourceGroups/{destinationResourceGroupName}/providers/Microsoft.Compute/images/<imageName>"
}

يجب أن يكون imageId ResourceId للصورة المدارة. استخدم az image list لسرد الصور المتاحة.

SharedImageVersion source

تعيين الصورة المصدر كإصدار صورة موجود في Azure Compute Gallery.

Note

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

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId - معرف مورد قالب ARM لإصدار الصورة. عندما يكون اسم إصدار الصورة "الأحدث"، يتم تقييم الإصدار عند إجراء إنشاء الصورة. imageVersionId يجب أن يكون من ResourceId إصدار الصورة. استخدم قائمة az sig image-version لسرد إصدارات الصورة.

يعين JSON التالي الصورة المصدر كصورة مخزنة في معرض مشترك مباشر.

Note

المعرض المشترك المباشر متوفر حاليا في المعاينة.

    source: {
      "type": "SharedImageVersion",
      "imageVersionId": "<replace with resourceId of the image stored in the Direct Shared Gallery>"
    },

يعين JSON التالي الصورة المصدر كأحدث إصدار صورة لصورة مخزنة في معرض حوسبة Azure.

"properties": {
    "source": {
        "type": "SharedImageVersion",
        "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<azureComputeGalleryName>/images/<imageDefinitionName>/versions/latest"
    }
},

SharedImageVersion properties:

imageVersionId - ARM template resource ID of the image version. عندما يكون اسم إصدار الصورة "الأحدث"، يتم تقييم الإصدار عند إجراء إنشاء الصورة.

Properties: stagingResourceGroup

stagingResourceGroup تحتوي الخاصية على معلومات حول مجموعة الموارد المرحلية التي تنشئها خدمة Image Builder لاستخدامها أثناء عملية إنشاء الصورة. هذه stagingResourceGroup خاصية اختيارية لأي شخص يريد مزيدًا من التحكم في مجموعة الموارد التي تم إنشاؤها بواسطة Image Builder أثناء عملية بناء الصورة. يمكنك إنشاء مجموعة موارد خاصة بك وتحديدها في القسم stagingResourceGroup أو إنشاء منشئ الصور نيابة عنك.

Important

لا يمكن إقران مجموعة الموارد المرحلية المحددة بقالب صورة آخر، ويجب أن تكون فارغة (لا توجد موارد داخلها)، وفي نفس المنطقة مثل قالب الصورة، وأن يكون RBAC "مساهم" أو "مالك" مطبقا على الهوية المعينة لمورد قالب صورة Azure Image Builder. يتحقق "منشئ الصور" من العلامات الموجودة على مجموعة موارد التقسيم المرحلي باستخدام المفاتيح imageTemplateResourceGroupName وتحديد imageTemplateName ما إذا كان أي قالب صورة يستخدم مجموعة موارد التقسيم المرحلي. إذا كانت هذه العلامات موجودة قبل إرسال قالب الصورة أو أنها لا تتطابق مع قالب الصورة قيد التشغيل أثناء إنشاء الصورة، فستفشل العملية.

"properties": {
  "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>"
}

سيناريوهات إنشاء القالب

  • تم ترك الخاصية stagingResourceGroup فارغة

    stagingResourceGroup إذا لم يتم تحديد الخاصية أو تحديدها بسلسلة فارغة، تنشئ خدمة Image Builder مجموعة موارد مرحلية مع اصطلاح الاسم الافتراضي "IT_***". تحتوي مجموعة الموارد المرحلية على العلامات الافتراضية المطبقة عليها: createdBy، ، imageTemplateName. imageTemplateResourceGroupName أيضا، يتم تطبيق RBAC الافتراضي على الهوية المعينة لمورد قالب Azure Image Builder، وهو "المساهم".

  • يتم تحديد الخاصية stagingResourceGroup مع مجموعة موارد موجودة

    stagingResourceGroup إذا تم تحديد الخاصية مع مجموعة موارد موجودة بالفعل، فإن خدمة Image Builder تتحقق للتأكد من أن مجموعة الموارد غير مقترنة بقالب صورة آخر، وهي فارغة (لا توجد موارد داخلها)، في نفس المنطقة مثل قالب الصورة، ولها إما "مساهم" أو "مالك" RBAC مطبق على الهوية المعينة لمورد قالب صورة Azure Image Builder. إذا لم يتم استيفاء أي من المتطلبات المذكورة أعلاه، يتم طرح خطأ. تحتوي مجموعة الموارد المرحلية على العلامات التالية المضافة إليها: usedBy، ، imageTemplateName. imageTemplateResourceGroupName لا يتم حذف العلامات الموجودة مسبقًا.

Important

ستحتاج إلى تعيين دور المساهم إلى مجموعة الموارد لكيان الخدمة المقابل لتطبيق الطرف الأول من Azure Image Builder عند محاولة تحديد مجموعة موارد موجودة مسبقا وVNet لخدمة Azure Image Builder مع صورة مصدر Windows. للحصول على أمر CLI وإرشادات المدخل حول كيفية تعيين دور المساهم إلى مجموعة الموارد، راجع الوثائق التالية استكشاف أخطاء VM Azure Image Builder وإصلاحها: خطأ التخويل في إنشاء القرص

  • تم تحديد الخاصية stagingResourceGroup مع مجموعة موارد غير موجودة

    إذا تم تحديد الخاصية stagingResourceGroup مع مجموعة موارد غير موجودة، فإن خدمة Image Builder تنشئ مجموعة موارد مرحلية بالاسم المتوفر في الخاصية stagingResourceGroup . سيكون هناك خطأ إذا كان الاسم المحدد لا يفي بمتطلبات تسمية Azure لمجموعات الموارد. تحتوي مجموعة الموارد المرحلية على العلامات الافتراضية المطبقة عليها: createdBy، ، imageTemplateName. imageTemplateResourceGroupName بشكل افتراضي، الهوية المعينة لمورد قالب صورة Azure Image Builder لها RBAC "المساهم" المطبق عليها في مجموعة الموارد.

Template deletion

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

إذا لم يقم Image Builder بإنشاء عملية تقسيم مرحلي لمجموعة الموارد، ولكن الموارد الموجودة داخل مجموعة الموارد، فسيتم حذف هذه الموارد بعد حذف قالب الصورة، نظرًا لأن خدمة Image Builder لديها الأذونات المناسبة أو الدور المطلوب لحذف الموارد.

Properties: validate

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

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

يأخذ inVMValidations الخاصية قائمة بالمدققات التي سيتم تنفيذها على الصورة. يدعم Azure Image Builder مدققي الملفات وPowerShell وShell.

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

عند استخدام validate:

  • يمكنك استخدام مدققين متعددين.
  • يقوم المدققون بالتنفيذ بالترتيب المحدد في القالب.
  • إذا فشل أحد المدققين، فسيفشل مكون التحقق من الصحة بأكمله ويبلغ عن خطأ.
  • يُنصح باختبار البرنامج النصي جيدًا قبل استخدامه في قالب. سيكون تصحيح أخطاء البرنامج النصي على الجهاز الظاهري الخاص بك أسهل.
  • لا تضع بيانات حساسة في البرامج النصية.
  • The script locations need to be publicly accessible, unless you're using MSI.

كيفية استخدام validateالخاصية للتحقق من صحة صور Windows:

{
   "properties":{
      "validate":{
         "continueDistributeOnFailure":false,
         "sourceValidationOnly":false,
         "inVMValidations":[
            {
               "type":"File",
               "destination":"string",
               "sha256Checksum":"string",
               "sourceUri":"string"
            },
            {
               "type":"PowerShell",
               "name":"test PowerShell validator inline",
               "inline":[
                  "<command to run inline>"
               ],
               "validExitCodes":"<exit code>",
               "runElevated":"<true or false>",
               "runAsSystem":"<true or false>"
            },
            {
               "type":"PowerShell",
               "name":"<name>",
               "scriptUri":"<path to script>",
               "runElevated":"<true false>",
               "sha256Checksum":"<sha256 checksum>"
            }
         ]
      }
   }
}

خصائص inVMValidations:

  • type – PowerShell.

  • name - name of the validator

  • scriptUri - URI of the PowerShell script file.

  • inline – array of commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command, this avoids reported failure of the script/inline command.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    To generate the sha256Checksum, using a PowerShell on Windows Get-Hash

كيفية استخدام validate الخاصية للتحقق من صور Linux:

{
  "properties": {
    "validate": {
      "continueDistributeOnFailure": false,
      "sourceValidationOnly": false,
      "inVMValidations": [
        {
          "type": "Shell",
          "name": "<name>",
          "inline": [
            "<command to run inline>"
          ]
        },
        {
          "type": "Shell",
          "name": "<name>",
          "scriptUri": "<path to script>",
          "sha256Checksum": "<sha256 checksum>"
        },
        {
          "type": "File",
          "destination": "string",
          "sha256Checksum": "string",
          "sourceUri": "string"
        }
      ]
    }
  }
}

خصائص inVMValidations:

  • type – Shell or File specified as the validation type to be performed.

  • name - name of the validator

  • scriptUri - URI of the script file

  • inline - array of commands to be run, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    لإنشاء المجموع الاختباري sha256Checksum، باستخدام محطة طرفية على Mac/Linux شغّل: sha256sum <fileName>

  • destination - Destination of the file.

  • sha256Checksum - Specifies the SHA256 checksum of the file.

  • sourceUri - The source URI of the file.

Properties: vmProfile

vmSize (optional)

يستخدم Image Builder حجم SKU افتراضيًا Standard_D1_v2لصور Gen1 وStandard_D2ds_v4 صور Gen2. يتم تعريف الإنشاء عن طريق الصورة التي تحددها في source. يمكنك تجاوز vmSize لهذه الأسباب:

  • إجراء التخصيصات التي تتطلب زيادة الذاكرة ووحدة المعالجة المركزية ومعالجة الملفات الكبيرة (GBs).
  • عند تشغيل إنشاءات Windows، يجب عليك استخدام "Standard_D2_v2" أو جهاز ظاهري يعادلها في الحجم.
  • Require VM isolation.
  • خصص صورة تتطلب أجهزة محددة. على سبيل المثال، بالنسبة إلى جهاز ظاهري لوحدة معالجة الرسومات، تحتاج إلى حجم GPU VM.
  • Require end to end encryption at rest of the build VM, you need to specify the support build VM size that doesn't use local temporary disks.

osDiskSizeGB

بشكل افتراضي، لا يغير Image Builder حجم الصورة، بل يستخدم الحجم من الصورة المصدر. You can optionally only increase the size of the OS Disk (Win and Linux), and a value of 0 means leaving the same size as the source image. لا يمكنك تقليل حجم قرص نظام التشغيل إلى أصغر من حجم الصورة المصدر.

{
  "osDiskSizeGB": 100
}

vnetConfig (optional)

إذا لم تحدد أي خصائص VNet، يقوم Image Builder بإنشاء VNet الخاصة به وIP العام ومجموعة أمان الشبكة (NSG). يُستخدم عنوان IP العام للخدمة للتواصل مع الجهاز الظاهري للبناء. إذا كنت لا ترغب في الحصول على عنوان IP عام أو إذا كنت تريد أن يتمكن Image Builder من الوصول إلى موارد VNet الحالية، مثل خوادم التكوين (DSC، Chef، Puppet، Ansible)، مشاركة الملفات، فيمكنك تحديد VNet. For more information, review the networking documentation.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
  "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
  "proxyVmSize": "<vmSize>"
}

subnetId

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

containerInstanceSubnetId (optional)

Resource ID of a pre-existing subnet on which Azure Container Instance (ACI) is deployed for Isolated Builds. إذا لم يتم تحديد هذا الحقل، نشر شبكة ظاهرية مؤقتة، جنبا إلى جنب مع الشبكات الفرعية ومجموعات أمان الشبكة، في مجموعة موارد التقسيم المرحلي بالإضافة إلى موارد الشبكات الأخرى (نقطة النهاية الخاصة وخدمة الارتباط الخاص وموازن تحميل Azure والوكيل الظاهري) لتمكين الاتصال بين ACI والجهاز الظاهري للبناء.

[تتوفر هذه الخاصية فقط في إصدارات واجهة برمجة التطبيقات أو الإصدارات 2024-02-01 الأحدث على الرغم من أنه يمكن تحديث القوالب الموجودة التي تم إنشاؤها باستخدام إصدارات واجهة برمجة التطبيقات السابقة لتحديد هذه الخاصية.]

يمكن تحديد هذا الحقل فقط إذا subnetId تم تحديده أيضا ويجب أن يفي بالمتطلبات التالية:

  • يجب أن تكون هذه الشبكة الفرعية على نفس الشبكة الظاهرية مثل الشبكة الفرعية المحددة في subnetId.
  • يجب ألا تكون هذه الشبكة الفرعية هي نفس الشبكة الفرعية المحددة في subnetId.
  • يجب تفويض هذه الشبكة الفرعية إلى خدمة ACI بحيث يمكن استخدامها لتوزيع موارد ACI. You can read more about subnet delegation for Azure services here. ACI specific subnet delegation information is available here.
  • يجب أن تسمح هذه الشبكة الفرعية بالوصول الصادر إلى الإنترنت وإلى الشبكة الفرعية المحددة في subnetId. هذه الوصولات مطلوبة بحيث يمكن توفير ACI ويمكنه الاتصال بالجهاز الظاهري للبناء لإجراء التخصيصات/عمليات التحقق من الصحة. على الطرف الآخر، يجب أن تسمح الشبكة الفرعية المحددة في subnetId بالوصول الوارد من هذه الشبكة الفرعية. بشكل عام، تسمح قواعد الأمان الافتراضية لمجموعات أمان شبكة Azure (NSGs) بهذه الوصولات. ومع ذلك، إذا أضفت المزيد من قواعد الأمان إلى مجموعات أمان الشبكة الخاصة بك، فيجب السماح بالوصولات التالية:
    1. الوصول الصادر من الشبكة الفرعية المحددة في containerInstanceSubnetId إلى:
      1. إلى الإنترنت على المنفذ 443 (لتوفير صورة الحاوية).
      2. إلى الإنترنت على المنفذ 445 (لتحميل مشاركة الملفات من Azure Storage).
      3. إلى الشبكة الفرعية المحددة في subnetId على المنفذ 22 (ل ssh/Linux) والمنفذ 5986 (ل WinRM/Windows) (للاتصال بالجهاز الظاهري للإنشاء).
    2. الوصول الوارد إلى الشبكة الفرعية المحددة في subnetId:
      1. إلى المنفذ 22 (ل ssh/Linux) والمنفذ 5986 (ل WinRM/Windows) من الشبكة الفرعية المحددة في containerInstanceSubnetId (ل ACI للاتصال بالجهاز الظاهري للبناء).
  • The template identity must have permission to perform 'Microsoft.Network/virtualNetworks/subnets/join/action' action on this subnet's scope. You can read more about Azure permissions for Networking here.

proxyVmSize (optional)

حجم الجهاز الظاهري الوكيل المستخدم لتمرير نسبة استخدام الشبكة إلى الجهاز الظاهري للبناء والتحقق من الصحة. يجب عدم تحديد هذا الحقل إذا containerInstanceSubnetId تم تحديده لأنه لم يتم نشر أي جهاز ظاهري وكيل في هذه الحالة. حذف سلسلة فارغة أو تحديدها لاستخدام الافتراضي (Standard_A1_v2).

Properties: autoRun

يمكنك استخدام الخاصية autoRun للتحكم في ما إذا كان يجب بدء عملية إنشاء قالب الصورة تلقائيا عند إنشاء القالب. إنه تعداد بقيمتين محتملتين:

  • Enabled - Auto run is enabled, so your image template build process will automatically start when the template is created.
  • Disabled - Auto run is disabled, so you will have to manually start the image build process after the template is created.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Note

When you set autoRun to "Enabled," the image build process runs once upon template creation. يضمن أن يتم إنشاء الصورة الأولية بسلاسة. ومع ذلك، فإنه لا يوفر إصدارات صور متسقة ومستمرة. للحصول على إصدارات صور متسقة ومستمرة يتم تشغيلها بمجرد تحديث قالب صورة، راجع كيفية استخدام مشغلات Azure Image Builder لإعداد بنية صورة تلقائية.

على عكس autoRun، يضمن إنشاء الصورة التلقائي عبر مورد مشغل Azure Image Builder حدوث إنشاءات الصور باستمرار. كلما كانت هناك تغييرات على القالب، ستقوم خدمة Azure Image Builder تلقائيا بتشغيل عملية إنشاء الصورة.

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

Properties: managedResourceTags

يمكنك استخدام الخاصية managedResourceTags لتطبيق العلامات على الموارد التي تنشئها خدمة Azure Image Builder في مجموعة الموارد المرحلية أثناء إنشاء الصورة. لمزيد من المعلومات حول مجموعة الموارد المرحلية، راجع نظرة عامة على Azure Image Builder

"properties": {
    "managedResourceTags": {
      "tag1": "value1",
            "tag2": "value2"
              }
}

عمليات قالب الصورة

بدء إنشاء صورة

لبدء الإنشاء، تحتاج إلى استدعاء "تشغيل" على مورد قالب الصورة، أمثلة على أوامر run:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Run -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

إلغاء إنشاء صورة

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

من الممكن إلغاء الإنشاء في أي وقت. إذا بدأت مرحلة التوزيع، فلا يزال بإمكانك إلغاء الأمر، ولكنك تحتاج إلى تنظيف أي صور قد لا تكون مكتملة. The cancel command doesn't wait for cancel to complete, monitor lastrunstatus.runstate for canceling progress, using these status commands.

أمثلة على أوامر cancel:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Cancel -Force

az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Cancel

Next steps

هناك نماذج من ملفات.json لسيناريوهات مختلفة في GitHub Azure Image Builder.

  • Last updated on