Ekstensi Skrip Kustom untuk Windows

Artikel
08/25/2024

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
Server Windows 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 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.

Tips

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\AutoRun registri (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 storageAccountName 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;

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. Contohnya:

"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.

Bagikan melalui

Ekstensi Skrip Kustom untuk Windows

Prasyarat

Sistem operasi Windows yang didukung

Lokasi skrip

Konektivitas internet

Tips

Skema ekstensi

Nilai properti

Detail nilai properti

Properti: managedIdentity

Penyebaran templat

Penyebaran PowerShell

Contoh

Menggunakan beberapa skrip

Menjalankan skrip kustom lebih dari satu kali dengan menggunakan CLI

Menggunakan Invoke-WebRequest

Virtual Machine Scale Sets

Pemecahan masalah dan dukungan

Dukungan

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Ekstensi Skrip Kustom untuk Windows

Prasyarat

Sistem operasi Windows yang didukung

Lokasi skrip

Konektivitas internet

Tips

Skema ekstensi

Nilai properti

Detail nilai properti

Properti: managedIdentity

Penyebaran templat

Penyebaran PowerShell

Contoh

Menggunakan beberapa skrip

Menjalankan skrip dari berbagi lokal

Menjalankan skrip kustom lebih dari satu kali dengan menggunakan CLI

Menggunakan Invoke-WebRequest

Virtual Machine Scale Sets

Pemecahan masalah dan dukungan

Dukungan

Saran dan Komentar

Sumber Daya Tambahan: