Ekstensi Skrip Kustom untuk Windows

  • Artikel

Ekstensi Skrip Kustom mengunduh dan menjalankan skrip pada mesin virtual Azure. Gunakan ekstensi ini untuk konfigurasi pasca-penyebaran, penginstalan perangkat lunak, atau tugas konfigurasi atau manajemen lainnya. Skrip dapat diunduh dari Microsoft Azure Storage atau GitHub, atau disediakan ke portal Microsoft Azure pada durasi ekstensi.

Ekstensi Skrip Kustom terintegrasi dengan templat Azure Resource Manager. Anda juga dapat menjalankannya dengan menggunakan Azure CLI, Azure PowerShell, portal Azure, atau REST API Azure Virtual Machines.

Artikel ini menjelaskan cara menggunakan Ekstensi Skrip Kustom dengan menggunakan modul Azure PowerShell dan templat Azure Resource Manager. Ini juga menyediakan langkah-langkah pemecahan masalah untuk sistem Windows.

Prasyarat

Catatan

Jangan gunakan Ekstensi Skrip Kustom untuk dijalankan Update-AzVM dengan VM yang sama dengan parameternya. Ekstensi akan menunggu sendiri.

Sistem operasi Windows yang didukung

OS Windows x64
Windows 10 Didukung
Windows 11 Didukung
Windows Server 2008 SP2 Didukung
Windows Server 2008 R2 Didukung
Windows Server 2012 Didukung
Windows Server 2012 R2 Didukung
Server Windows 2016 Didukung
Windows Server 2016 Core Didukung
Windows Server 2019 Didukung
Windows Server 2019 Core Didukung
Windows Server 2022 Didukung
Windows Server 2022 Core Didukung

Lokasi skrip

Anda dapat mengatur ekstensi untuk menggunakan info mandat Azure Blob Storage Anda sehingga dapat mengakses Azure Blob Storage. Lokasi skrip dapat berada di mana saja, selama VM dapat merutekan ke titik akhir tersebut, misalnya, GitHub atau server file internal.

Konektivitas internet

Untuk mengunduh skrip secara eksternal, seperti dari GitHub atau Azure Storage, Anda perlu membuka port firewall atau kelompok keamanan jaringan (NSG) lainnya. Misalnya, jika skrip terletak di Azure Storage, Anda dapat mengizinkan akses dengan menggunakan tag layanan Azure NSG untuk Storage.

Ekstensi Skrip Kustom tidak memiliki cara apa pun untuk melewati validasi sertifikat. Jika Anda mengunduh dari lokasi aman dengan, misalnya, sertifikat yang ditandatangani sendiri, Anda mungkin mendapatkan kesalahan seperti Sertifikat jarak jauh tidak valid sesuai dengan prosedur validasi. Pastikan bahwa sertifikat diinstal dengan benar di penyimpanan Otoritas Sertifikasi Akar Tepercaya pada VM.

Jika skrip Anda berada di server lokal, Anda mungkin masih perlu membuka firewall atau port NSG lainnya.

Tips

  • Output dibatasi hingga 4.096 byte terakhir.
  • Karakter yang melarikan diri dengan benar akan membantu memastikan bahwa string diurai dengan benar. Misalnya, Anda selalu memerlukan dua garis miring terbelakang untuk melepaskan satu garis miring terbelakang harfiah saat berhadapan dengan jalur file. Sampel: {"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
  • Tingkat kegagalan tertinggi untuk ekstensi ini adalah karena kesalahan sintaks dalam skrip. Verifikasi bahwa skrip berjalan tanpa kesalahan. Masukkan lebih banyak pengelogan ke dalam skrip untuk mempermudah menemukan kegagalan.
  • Tulis skrip yang idempotensi, sehingga menjalankannya lebih dari sekali secara tidak sengaja tidak menyebabkan perubahan sistem.
  • Pastikan skrip tidak memerlukan input pengguna saat dijalankan.
  • Skrip diizinkan untuk dijalankan selama 90 menit. Apa pun yang lebih lama menghasilkan penyediaan ekstensi yang gagal.
  • Jangan letakkan hidupkan ulang di dalam skrip. Tindakan ini menyebabkan masalah dengan ekstensi lain yang sedang diinstal, dan ekstensi tidak berlanjut setelah mulai ulang.
  • Jika Anda memiliki skrip yang menyebabkan mulai ulang sebelum menginstal aplikasi dan menjalankan skrip, jadwalkan mulai ulang dengan menggunakan Tugas Terjadwal Windows atau dengan menggunakan alat seperti ekstensi DSC, Chef, atau Boneka.
  • Jangan menjalankan skrip yang menyebabkan penghentian atau pembaruan agen VM. Ekstensi mungkin meninggalkan ekstensi dalam status transisi dan menyebabkan waktu habis.
  • Ekstensi menjalankan skrip hanya sekali. Jika Anda ingin menjalankan skrip pada setiap boot, gunakan ekstensi untuk membuat Tugas Terjadwal Windows.
  • Jika Anda ingin menjadwalkan kapan skrip berjalan, gunakan ekstensi untuk membuat Tugas Terjadwal Windows.
  • Saat skrip berjalan, Anda hanya melihat status ekstensi transisi dari portal Azure atau Azure CLI. Jika Anda menginginkan pembaruan status yang lebih sering untuk skrip yang sedang berjalan, buat solusi Anda sendiri.
  • Ekstensi Skrip Kustom tidak mendukung server proxy secara native. Namun, Anda dapat menggunakan alat transfer file, seperti Invoke-WebRequest, yang mendukung server proksi dalam skrip Anda.
  • Ketahui lokasi direktori nondefault yang mungkin diandalkan oleh skrip atau perintah Anda. Memiliki logika untuk menangani situasi ini.
  • Ekstensi Skrip Kustom berjalan di LocalSystem bawah akun.
  • Jika Anda berencana untuk menggunakan storageAccountName properti dan storageAccountKey , properti ini harus dikolokasikan di protectedSettings.
  • Anda hanya dapat memiliki satu versi ekstensi yang diterapkan ke mesin virtual. Untuk menjalankan skrip kustom kedua, Anda dapat memperbarui ekstensi yang ada dengan konfigurasi baru. Atau, Anda dapat menghapus ekstensi skrip kustom dan menerapkannya kembali dengan skrip yang diperbarui

Skema ekstensi

Konfigurasi Ekstensi Skrip Kustom menentukan hal-hal seperti lokasi skrip dan perintah yang akan dijalankan. Anda dapat menyimpan konfigurasi ini dalam file konfigurasi, menentukan file pada baris perintah, atau menentukan file dalam templat Azure Resource Manager.

Anda dapat menyimpan data sensitif dalam konfigurasi yang dilindungi, yang dienkripsi dan hanya didekripsi di dalam VM. Konfigurasi yang dilindungi berguna saat perintah eksekusi menyertakan rahasia seperti kata sandi atau referensi file tanda tangan akses bersama (SAS). Berikut contohnya:

{
    "apiVersion": "2018-06-01",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "name": "virtualMachineName/config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
        "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
        "[variables('musicstoresqlName')]"
    ],
    "tags": {
        "displayName": "config-app"
    },
    "properties": {
        "publisher": "Microsoft.Compute",
        "type": "CustomScriptExtension",
        "typeHandlerVersion": "1.10",
        "autoUpgradeMinorVersion": true,
        "settings": {
            "timestamp":123456789
        },
        "protectedSettings": {
            "commandToExecute": "myExecutionCommand",
            "storageAccountName": "myStorageAccountName",
            "storageAccountKey": "myStorageAccountKey",
            "managedIdentity" : {},
            "fileUris": [
                "script location"
            ]
        }
    }
}

Catatan

Properti managedIdentitytidak boleh digunakan bersama dengan properti storageAccountName atau storageAccountKey.

Hanya satu versi ekstensi yang dapat diinstal pada VM pada satu waktu. Menentukan skrip kustom dua kali dalam templat Azure Resource Manager yang sama untuk VM yang sama gagal.

Anda dapat menggunakan skema ini di dalam sumber daya mesin virtual atau sebagai sumber daya mandiri. Jika ekstensi ini digunakan sebagai sumber daya mandiri di templat Azure Resource Manager, nama sumber daya harus dalam format virtualMachineName/extensionName.

Nilai properti

Nama Nilai atau contoh Jenis data
apiVersion 2015-06-15 date
penerbit Microsoft.Compute string
jenis CustomScriptExtension string
typeHandlerVersion 1.10 int
fileUris https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 array
rentang waktu 123456789 bilangan bulat 32-bit
commandToExecute powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 string
storageAccountName examplestorageacct string
storageAccountKey TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== string
managedIdentity { } atau { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" } atau { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" } Objek JSON

Catatan

Nama properti ini peka huruf besar/kecil. Untuk menghindari masalah penyebaran, gunakan nama seperti yang ditunjukkan di sini.

Detail nilai properti

Properti Opsional atau diperlukan Detail
fileUris Opsional URL untuk file yang akan diunduh. Jika URL sensitif, misalnya, jika berisi kunci, bidang ini harus ditentukan dalam protectedSettings.
commandToExecute Wajib Skrip titik masuk untuk dijalankan. Gunakan bidang ini sebagai gantinya jika perintah Anda berisi rahasia seperti kata sandi, atau file Url sensitif.
rentang waktu Opsional Ubah nilai ini hanya untuk memicu tayangan ulang skrip. Setiap nilai bilangan bulat dapat diterima, asalkan berbeda dari nilai sebelumnya.
storageAccountName Opsional Nama akun penyimpanan. Jika Anda menentukan info masuk penyimpanan, semua nilai fileUris harus merupakan URL untuk blob Azure.
storageAccountKey Opsional Kunci akses akun penyimpanan.
managedIdentity Opsional Identitas terkelola untuk mengunduh file. Nilai yang valid adalah clientId (opsional, string), yang merupakan ID klien dari identitas terkelola, dan objectId (opsional, string), yang merupakan ID objek dari identitas terkelola.

Pengaturan publik dikirim dalam teks yang jelas ke VM tempat skrip berjalan. Pengaturan yang dilindungi dienkripsi melalui kunci yang hanya diketahui oleh Azure dan VM. Pengaturan disimpan di mesin virtual selagi dikirimkan. Artinya, jika pengaturan dienkripsi, mereka disimpan sebagai dienkripsi di mesin virtual. Sertifikat yang digunakan untuk mendekripsi nilai yang dienkripsi disimpan di mesin virtual. Sertifikat juga digunakan untuk mendekripsi pengaturan, jika perlu, pada waktu proses.

Menggunakan pengaturan publik mungkin berguna untuk penelusuran kesalahan, tetapi kami menyarankan Anda menggunakan pengaturan yang dilindungi.

Anda dapat mengatur nilai berikut di pengaturan publik atau yang dilindungi. Ekstensi menolak konfigurasi apa pun di mana nilai-nilai ini diatur dalam pengaturan publik dan terlindungi.

  • commandToExecute
  • fileUris

Properti: managedIdentity

Catatan

Properti ini harus ditentukan dalam pengaturan yang dilindungi saja.

Ekstensi Skrip Kustom, versi 1.10 dan yang lebih baru, mendukung identitas terkelola untuk mengunduh file dari URL yang disediakan dalam fileUris pengaturan. Properti ini memungkinkan Ekstensi Skrip Kustom untuk mengakses blob atau kontainer privat Azure Storage tanpa pengguna harus meneruskan rahasia seperti token SAS atau kunci akun penyimpanan.

Untuk menggunakan fitur ini, tambahkan identitas yang ditetapkan sistem atau ditetapkan pengguna ke VM atau Virtual Machine Scale Set tempat Ekstensi Skrip Kustom berjalan. Kemudian berikan akses identitas terkelola ke kontainer atau blob Azure Storage.

Untuk menggunakan identitas yang ditetapkan sistem pada VM target atau Virtual Machine Scale Set, atur managedidentity ke objek JSON kosong.

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : {}
}

Untuk menggunakan identitas yang ditetapkan pengguna pada VM target atau Virtual Machine Scale Set, konfigurasikan managedidentity dengan ID klien atau ID objek identitas terkelola.

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }
}

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }
}

Catatan

Properti managedIdentitytidak boleh digunakan bersama dengan properti storageAccountName atau storageAccountKey.

Penyebaran templat

Anda dapat menyebarkan ekstensi mesin virtual Azure dengan menggunakan templat Azure Resource Manager. Skema JSON yang dirinci di bagian sebelumnya dapat digunakan dalam templat Azure Resource Manager untuk menjalankan Ekstensi Skrip Kustom selama penyebaran templat. Sampel berikut menunjukkan cara menggunakan ekstensi Skrip Kustom:

Penyebaran PowerShell

Anda dapat menggunakan Set-AzVMCustomScriptExtension perintah untuk menambahkan Ekstensi Skrip Kustom ke komputer virtual yang ada. Untuk mengetahui informasi selengkapnya, lihat Set-AzVMCustomScriptExtension.

Set-AzVMCustomScriptExtension -ResourceGroupName <resourceGroupName> `
    -VMName <vmName> `
    -Location myLocation `
    -FileUri <fileUrl> `
    -Run 'myScript.ps1' `
    -Name DemoScriptExtension

Contoh

Menggunakan beberapa skrip

Contoh ini menggunakan tiga skrip untuk membangun server Anda. Properti commandToExecute memanggil skrip pertama. Kemudian Anda memiliki opsi tentang cara memanggil yang lain. Misalnya, Anda dapat memiliki skrip prospek yang mengontrol eksekusi, dengan penanganan kesalahan, pengelogan, dan manajemen status yang tepat. Skrip diunduh ke komputer lokal untuk dijalankan.

Misalnya, di 1_Add_Tools.ps1, Anda akan memanggil 2_Add_Features.ps1 dengan menambahkan .\2_Add_Features.ps1 skrip. Ulangi proses ini untuk skrip lain yang Anda tentukan di $settings.

$fileUri = @("https://xxxxxxx.blob.core.windows.net/buildServer1/1_Add_Tools.ps1",
"https://xxxxxxx.blob.core.windows.net/buildServer1/2_Add_Features.ps1",
"https://xxxxxxx.blob.core.windows.net/buildServer1/3_CompleteInstall.ps1")

$settings = @{"fileUris" = $fileUri};

$storageAcctName = "xxxxxxx"
$storageKey = "1234ABCD"
$protectedSettings = @{"storageAccountName" = $storageAcctName; "storageAccountKey" = $storageKey; "commandToExecute" = "powershell -ExecutionPolicy Unrestricted -File 1_Add_Tools.ps1"};

#run command
Set-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -Location <locationName> `
    -VMName <vmName> `
    -Name "buildserver1" `
    -Publisher "Microsoft.Compute" `
    -ExtensionType "CustomScriptExtension" `
    -TypeHandlerVersion "1.10" `
    -Settings $settings `
    -ProtectedSettings $protectedSettings;

Menjalankan skrip dari berbagi lokal

Dalam contoh ini, Anda mungkin ingin menggunakan server Server Message Block (SMB) lokal untuk lokasi skrip. Dengan melakukan ini, Anda tidak perlu memberikan pengaturan lain, kecuali commandToExecute.

$protectedSettings = @{"commandToExecute" = "powershell -ExecutionPolicy Unrestricted -File \\filesvr\build\serverUpdate1.ps1"};

Set-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -Location <locationName> `
    -VMName <vmName> `
    -Name "serverUpdate"
    -Publisher "Microsoft.Compute" `
    -ExtensionType "CustomScriptExtension" `
    -TypeHandlerVersion "1.10" `
    -ProtectedSettings $protectedSettings

Menjalankan skrip kustom lebih dari satu kali dengan menggunakan CLI

Penangan Ekstensi Skrip Kustom mencegah menjalankan ulang skrip jika pengaturan yang sama persis telah diteruskan. Perilaku ini mencegah rerunning yang tidak disengaja, yang dapat menyebabkan perilaku tak terduga jika skrip tidak idempotent. Untuk mengonfirmasi apakah handler memblokir eksekusi ulang, lihat C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*. Mencari peringatan seperti ini:

Current sequence number, <SequenceNumber>, is not greater than the sequence number
of the most recently executed configuration. Exiting...

Jika Anda ingin menjalankan ekstensi skrip kustom lebih dari sekali, Anda hanya dapat melakukan tindakan ini dalam kondisi berikut:

  • Parameter Name ekstensi sama dengan penyebaran ekstensi sebelumnya.
  • Anda telah memperbarui konfigurasi. Anda dapat menambahkan properti dinamis ke perintah, seperti stempel waktu. Jika handler mendeteksi perubahan pengaturan konfigurasi, penghandel menganggap perubahan tersebut sebagai keinginan eksplisit untuk menjalankan ulang skrip.

Atau, Anda dapat mengatur properti ForceUpdateTag ke true.

Menggunakan Invoke-WebRequest

Jika Anda menggunakan Invoke-WebRequest dalam skrip Anda, Anda harus menentukan parameter -UseBasicParsing. Jika Anda tidak menentukan parameter, Anda mendapatkan kesalahan berikut saat memeriksa status terperinci:

The response content cannot be parsed because the Internet Explorer engine
is not available, or Internet Explorer's first-launch configuration
is not complete. Specify the UseBasicParsing parameter and try again.

Virtual Machine Scale Sets

Jika Anda menyebarkan Ekstensi Skrip Kustom dari portal Azure, Anda tidak memiliki kendali atas kedaluwarsa token SAS untuk mengakses skrip di akun penyimpanan Anda. Penyebaran awal berfungsi, tetapi ketika token SAS akun penyimpanan kedaluwarsa, operasi penskalaan berikutnya gagal karena Ekstensi Skrip Kustom tidak dapat lagi mengakses akun penyimpanan.

Kami menyarankan agar Anda menggunakan PowerShell, Azure CLI, atau templat Azure Resource Manager saat Anda menyebarkan Ekstensi Skrip Kustom pada Set Skala Komputer Virtual. Dengan cara ini, Anda dapat memilih untuk menggunakan identitas terkelola atau memiliki kontrol langsung atas kedaluwarsa token SAS untuk mengakses skrip di akun penyimpanan Anda selama yang Anda butuhkan.

Pemecahan masalah dan dukungan

Data tentang status penyebaran ekstensi dapat diambil dari portal Microsoft Azure dan dengan menggunakan modul Azure PowerShell. Untuk melihat status penyebaran ekstensi pada mesin virtual tertentu, jalankan perintah berikut:

Get-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -VMName <vmName> -Name myExtensionName

Output ekstensi dicatat ke file yang ditemukan di bawah folder berikut pada mesin virtual target:

C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension

FIle yang ditetapkan diunduh ke folder berikut ini pada mesin virtual target:

C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.*\Downloads\<n>

Pada jalur sebelumnya, <n> adalah bilangan bulat desimal yang mungkin berubah di antara eksekusi ekstensi. Nilai 1.* cocok dengan nilai aktual typeHandlerVersion saat ini dari ekstensi. Misalnya, direktori yang asli dapat berupa C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

Saat Anda menjalankan commandToExecute perintah, ekstensi mengatur direktori ini, misalnya, ...\Downloads\2, sebagai direktori kerja saat ini. Proses ini memungkinkan penggunaan jalur relatif untuk menemukan file yang diunduh dengan menggunakan fileURIs properti . Berikut adalah contoh file yang diunduh:

URI di fileUris Lokasi pengunduhan relatif Lokasi unduhan absolut
https://someAcct.blob.core.windows.net/aContainer/scripts/myscript.ps1 ./scripts/myscript.ps1 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\scripts\myscript.ps1
https://someAcct.blob.core.windows.net/aContainer/topLevel.ps1 ./topLevel.ps1 C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\topLevel.ps1

Jalur direktori absolut berubah selama masa pakai VM, tetapi tidak dalam satu eksekusi Ekstensi Skrip Kustom.

Karena jalur pengunduhan absolut dapat bervariasi dari waktu ke waktu, lebih baik memilih jalur skrip/file relatif dalam string commandToExecute, jika memungkinkan. Misalnya:

"commandToExecute": "powershell.exe . . . -File \"./scripts/myscript.ps1\""

Informasi jalur setelah segmen URI pertama disimpan untuk file yang diunduh dengan menggunakan fileUris daftar properti. Seperti yang ditunjukkan pada tabel sebelumnya, file yang diunduh dipetakan ke dalam subdirektori unduhan untuk mencerminkan struktur nilai fileUris.

Dukungan

  • Jika Anda memerlukan bantuan tentang bagian mana pun dari artikel ini, hubungi pakar Azure di Dukungan Komunitas Azure.

  • Untuk mengajukan insiden dukungan Azure, buka situs dukungan Azure dan pilih Dapatkan dukungan.

  • Selengkapnya tentang cara menggunakan dukungan Azure, baca FAQ tentang dukungan Microsoft Azure.