Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
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 Azure Storage atau GitHub, atau disediakan ke portal Azure saat runtime 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.
Catatan
Coba bantuan VM untuk diagnostik yang lebih cepat. Kami menyarankan agar Anda menjalankan VM assist untuk Windows atau VM assist untuk Linux. Alat diagnostik berbasis skrip ini membantu Anda mengidentifikasi masalah umum yang memengaruhi Agen Tamu Azure VM dan kesehatan VM secara keseluruhan.
Prasyarat
Catatan
Jangan gunakan Ekstensi Skrip Kustom untuk menjalankan Update-AzVM pada VM yang sama dengan parameternya. Ekstensi akan menunggu dengan sendirinya.
Sistem operasi Windows yang didukung
| Versi OS | x64 | ARM64 |
|---|---|---|
| Windows 10 | Didukung | Didukung |
| Windows 11 | Didukung | Didukung |
| Windows Server 2016 | Didukung | Didukung |
| Windows Server 2016 Core | Didukung | Didukung |
| Windows Server 2019 | Didukung | Didukung |
| Windows Server 2019 Core | Didukung | Didukung |
| Windows Server 2022 | Didukung | Didukung |
| Windows Server 2022 Core | Didukung | Didukung |
| Windows Server 2025 | Didukung | Didukung |
| Windows Server 2025 Core | Didukung | 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 mesin virtual 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 grup 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.
Meskipun skrip ada di server lokal, Anda mungkin masih perlu membuka port firewall dan NSG lainnya.
Petunjuk
- Output dibatasi hingga 4.096 byte terakhir.
- Karakter yang lolos 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 membuatnya lebih mudah menemukan kegagalan.
- Tulis skrip yang idempoten, jadi jika skrip dijalankan lagi beberapa kali secara tidak sengaja, hal tersebut tidak akan menyebabkan perubahan sistem.
- Pastikan skrip tidak memerlukan input pengguna saat dijalankan.
- Skrip diizinkan untuk dijalankan selama 90 menit. Apa pun yang lebih lama akan mengakibatkan kegagalan penyediaan ekstensi.
- Jangan menempatkan restart di dalam skrip. Tindakan ini akan menyebabkan masalah pada ekstensi lain yang sedang dipasang, dan ekstensi tidak akan berlanjut setelah restart.
- Jika Anda memiliki skrip yang akan menyebabkan restart sebelum memasang aplikasi dan menjalankan skrip, jadwalkan restart dengan menggunakan Tugas Terjadwal Windows atau menggunakan alat seperti DSC, Chef, atau ekstensi Puppet.
- Tidak disarankan untuk menjalankan skrip yang akan menyebabkan penghentian atau pembaruan agen mesin virtual. Hal ini dapat membuat ekstensi berada dalam status transisi dan menyebabkan waktu habis.
- Ekstensi hanya akan menjalankan skrip satu kali. Jika Anda ingin menjalankan skrip pada setiap boot, gunakan ekstensi untuk membuat Tugas Terjadwal Windows.
- Jika ingin menjadwalkan kapan skrip akan berjalan, Anda harus menggunakan ekstensi untuk membuat Tugas Terjadwal Windows.
- Saat skrip berjalan, Anda hanya akan melihat status ekstensi transisi dari portal Azure atau Azure CLI. Jika ingin pembaruan status yang lebih sering dari 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.
- Waspadai lokasi direktori non-default yang mungkin diandalkan oleh skrip atau perintah Anda. Memiliki logika untuk menangani situasi ini.
- Pastikan Anda tidak memiliki pengaturan kustom dalam kunci
HKLM\SOFTWARE\Microsoft\Command Processor\AutoRunregistri (dirinci di sini). Ini akan memicu selama ekstensi Skrip Kustom menginstal atau mengaktifkan fase dan menyebabkan kesalahan seperti'XYZ is not recognized as an internal or external command, operable program or batch file'. - Ekstensi Skrip Kustom berjalan di bawah akun
LocalSystem. - Jika Anda berencana untuk menggunakan properti
storageAccountNamedanstorageAccountKey, properti ini harus dikolokasikan diprotectedSettings. - 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 | 2018-06-01 |
tanggal |
| penerbit | Microsoft.Compute |
string |
| jenis | CustomScriptExtension |
string |
| typeHandlerVersion | 1.10 |
int (integer) |
| fileUris | https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 |
array |
| stempel waktu | 123456789 |
bilangan bulat 32-bit |
| perintahUntukDijalankan | powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 |
string |
| namaAkunPenyimpanan (storageAccountName) | examplestorageacct |
string |
| kunciAkunPenyimpanan | TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== |
string |
| managedIdentity |
{ } atau { "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444" } atau { "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" } |
Objek JSON |
Catatan
Nama properti ini peka terhadap huruf besar/kecil. Untuk menghindari masalah penyebaran, gunakan nama seperti yang ditunjukkan di sini.
Detail nilai properti
| Properti | Opsional atau diperlukan | Detail-detail |
|---|---|---|
| fileUris | Opsional | URL untuk file yang akan diunduh. Jika URL sensitif, misalnya, jika berisi kunci, bidang ini harus ditentukan dalam protectedSettings. |
| perintahUntukDijalankan | Wajib | Skrip titik masuk yang akan dijalankan. Gunakan properti ini jika perintah Anda berisi rahasia seperti kata sandi atau jika URI file Anda bersifat sensitif. |
| stempel waktu | Opsional | Ubah nilai ini hanya untuk memicu tayangan ulang skrip. Setiap nilai bilangan bulat dapat diterima, asalkan berbeda dari nilai sebelumnya. |
| namaAkunPenyimpanan (storageAccountName) | Opsional | Nama akun penyimpanan. Jika Anda menentukan kredensial penyimpanan, semua nilai fileUris harus berupa URL untuk blob Azure. |
| kunciAkunPenyimpanan | Opsional | Kunci akses akun penyimpanan. |
| managedIdentity | Opsional | Identitas yang dikelola untuk pengunduhan 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.
commandToExecutefileUris
Properti: identitasTerkelola
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 pengaturan fileUris. 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.
Catatan
Ekstensi Skrip Kustom saat ini tidak mendukung penggunaan autentikasi Identitas Terkelola di server yang diaktifkan Azure Arc.
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": "00001111-aaaa-2222-bbbb-3333cccc4444" }
}
{
"fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
"commandToExecute": "powershell.exe script1.ps1",
"managedIdentity" : { "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
}
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:
- Menyebarkan ekstensi komputer virtual dengan templat Azure Resource Manager
- Sebarkan Aplikasi Dua Tingkat di Windows dan database Azure SQL
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 utama yang mengontrol eksekusi, dengan penanganan kesalahan, pencatatan, 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 skrip dijalankan ulang jika pengaturan yang sama persis telah diteruskan. Perilaku ini mencegah pengulangan yang tidak disengaja, yang dapat menyebabkan perilaku tidak terduga jika skrip tidak bersifat idempotent (berperilaku sama meskipun dijalankan berulang kali). 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
Nameekstensi 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 dari ekstensi dicatat ke file yang ditemukan di dalam 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. Contohnya:
"commandToExecute": "powershell.exe . . . -File \"./scripts/myscript.ps1\""
Informasi jalur setelah segmen URI pertama disimpan untuk file yang diunduh dengan menggunakan daftar properti fileUris. 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.