Ekstensi Skrip Kustom untuk Windows

Ekstensi Skrip Kustom mengunduh dan menjalankan skrip pada komputer virtual Azure. Ekstensi ini berguna untuk konfigurasi pasca penyebaran, penginstalan perangkat lunak, atau tugas konfigurasi atau manajemen lainnya. Skrip dapat diunduh dari penyimpanan Azure atau GitHub, atau disediakan ke portal Microsoft Azure pada durasi ekstensi. Ekstensi Skrip Kustom terintegrasi dengan templat Azure Resource Manager, dan dapat dijalankan menggunakan CLI Azure, PowerShell, portal Microsoft Azure, atau REST API Komputer Virtual Azure.

Dokumen ini merinci cara menggunakan Ekstensi Skrip Kustom menggunakan modul Azure PowerShell, templat Azure Resource Manager, dan langkah-langkah pemecahan masalah detail pada sistem Windows.

Prasyarat

Catatan

Jangan gunakan Ekstensi Skrip Kustom untuk menjalankan Update-AzVM dengan komputer virtual yang sama dengan parameternya, karena akan menunggu dengan sendirinya.

Sistem Operasi

Ekstensi Skrip Kustom untuk Windows akan berjalan pada OS ekstensi yang didukung ekstensi;

Windows

  • Windows Server 2008 R2
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows 10
  • Server Windows 2016
  • Windows Server 2016 Core
  • Server Windows 2019
  • Windows Server 2019 Inti

Lokasi Skrip

Anda dapat mengonfigurasi ekstensi untuk menggunakan info masuk penyimpanan Blob Azure untuk mengakses penyimpanan Blob Azure. Lokasi skrip dapat berada di mana saja, selama komputer virtual dapat merutekan ke titik akhir tersebut, seperti GitHub atau server file internal.

Konektivitas Internet

Jika Anda perlu mengunduh skrip secara eksternal seperti dari GitHub atau Azure Storage, maka firewall tambahan dan port Kelompok Keamanan Jaringan perlu dibuka. Misalnya, jika skrip Anda terletak di Azure Storage, Anda dapat mengizinkan akses menggunakan Tag Layanan NSG Azure untuk Penyimpanan.

Perhatikan bahwa Ekstensi CustomScript tidak memiliki cara apa pun untuk melewati validasi sertifikat. Jadi, jika Anda mengunduh dari lokasi yang aman dengan misalnya. sertifikat yang ditandatangani sendiri, Anda mungkin berakhir dengan kesalahan seperti "Sertifikat jarak jauh tidak valid sesuai dengan prosedur validasi" . Pastikan sertifikat dipasang dengan benar di penyimpanan "Otoritas Sertifikasi Akar Tepercaya" pada Komputer Virtual.

Jika skrip Anda ada di server lokal, maka Anda mungkin masih memerlukan firewall tambahan dan port Kelompok Keamanan Jaringan perlu dibuka.

Tips dan trik

  • Tingkat kegagalan tertinggi untuk ekstensi ini adalah karena galat sintaksis dalam skrip, menguji skrip yang berjalan tanpa kesalahan, dan juga memasukkan pengelogan tambahan ke dalam skrip untuk mempermudah menemukan kegagalannya.
  • Tulis skrip yang bersifat idempotent. Hal ini memastikan bahwa ketika menjalankan tindakan lagi secara tidak sengaja, tidak akan menyebabkan perubahan sistem.
  • Pastikan skrip tidak memerlukan input pengguna saat dijalankan.
  • Ada waktu 90 menit yang diizinkan untuk menjalankan skrip, melebihi waktu ini akan mengakibatkan ketentuan ekstensi yang gagal.
  • Jangan meletakkan boot ulang di dalam skrip, tindakan ini akan menyebabkan masalah dengan ekstensi lain yang sedang diinstal. Pasca boot ulang, ekstensi tidak akan berlanjut setelah dimulai ulang.
  • Jika Anda memiliki skrip yang akan menyebabkan boot ulang, maka pasang aplikasi dan jalankan skrip, Anda dapat menjadwalkan boot ulang menggunakan Tugas Terjadwal Windows, atau menggunakan alat seperti ekstensi DSC, Chef, atau Puppet.
  • Tidak disarankan untuk menjalankan skrip yang akan menyebabkan pemberhentian atau pembaruan Agen komputer virtual. Skrip dapat meninggalkan ekstensi dalam status Transisi, yang mengarah ke waktu tunggu.
  • Ekstensi hanya akan menjalankan skrip satu kali, jika ingin menjalankan skrip pada setiap boot, Anda perlu menggunakan 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 CLI. Jika ingin pembaruan status yang lebih sering dari skrip yang sedang berjalan, Anda harus membuat solusi Anda sendiri.
  • Ekstensi Skrip Kustom tidak secara asli mendukung server proksi, namun Anda dapat menggunakan alat transfer file yang mendukung server proksi dalam skrip, seperti Invoke-WebRequest
  • Waspadai lokasi direktori non-default yang mungkin diandalkan oleh skrip atau perintah Anda, gunakan logika untuk menangani situasi ini.
  • Ekstensi Skrip Kustom akan dijalankan di bawah Akun LocalSystem
  • Jika Anda berencana untuk menggunakan storageAccountName dan properti storageAccountKey, properti ini harus berada di protectedSettings.

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 didekripsikan di dalam komputer virtual. Konfigurasi yang dilindungi berguna saat perintah eksekusi menyertakan rahasia seperti kata sandi atau referensi file tanda tangan akses bersama (SAS), yang harus dilindungi.

Item ini harus diperlakukan sebagai data sensitif dan ditentukan dalam konfigurasi pengaturan yang dilindungi ekstensi. Data pengaturan yang dilindungi ekstensi Azure VM dienkripsi, dan hanya didekripsi pada komputer virtual target.

{
    "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 managedIdentity tidak dapat digunakan bersama dengan properti storageAccountName atau storageAccountKey

Catatan

Hanya satu versi ekstensi yang dapat dipasang di komputer virtual pada suatu waktu, menentukan skrip kustom dua kali dalam templat Azure Resource Manager yang sama untuk komputer virtual yang sama akan gagal.

Catatan

Kita dapat menggunakan skema ini di dalam sumber daya VirtualMachine atau sebagai sumber daya tunggal. Nama sumber daya harus dalam format ini "virtualMachineName /extensionName", jika ekstensi ini digunakan sebagai sumber daya tunggal di templat ARM.

Nilai properti

Nama Nilai/Contoh Jenis Data
apiVersion 2015-06-15 tanggal
penerbit Microsoft.Compute untai (karakter)
jenis CustomScriptExtension untai (karakter)
typeHandlerVersion 1.10 int
fileUris (misalnya) https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 array
tanda waktu (misalnya) 123456789 bilangan bulat 32-bit
commandToExecute (misalnya) powershell -ExecutionPolicy Tidak Dibatasi -File configure-music-app.ps1 untai (karakter)
storageAccountName (misalnya) examplestorageacct string
storageAccountKey (misalnya) TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== string
managedIdentity (misalnya) { } or { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" } or { "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

  • commandToExecute: (diperlukan, string) skrip titik entri untuk dijalankan. Gunakan bidang ini sebagai gantinya jika perintah Anda berisi rahasia seperti kata sandi, atau fileUris sensitif.
  • fileUris: (opsional, array string) URL untuk file yang akan diunduh. Jika URL sensitif (seperti URL yang berisi kunci), bidang ini harus ditentukan dalam protectedSettings
  • timestamp (opsional, bilangan bulat 32-bit) gunakan bidang ini hanya untuk memicu agar skrip dijalankan ulang dengan mengubah nilai bidang ini. Setiap nilai bilangan bulat dapat diterima; nilai bilangan bulat harus berbeda dari nilai sebelumnya.
  • storageAccountName: (opsional, string) nama akun penyimpanan. Jika Anda menentukan info masuk penyimpanan, semua fileUris harus berupa URL untuk Azure Blob.
  • storageAccountKey: (opsional, string) kunci akses akun penyimpanan
  • managedIdentity: (opsional, objek json) identitas terkelola untuk mengunduh file
    • clientId: (opsional, string) ID klien identitas terkelola
    • objectId: (opsional, string) ID objek identitas terkelola

Nilai berikut dapat diatur dalam pengaturan publik atau terlindungi, ekstensi akan menolak konfigurasi apa pun di mana nilai di bawah ini diatur dalam pengaturan publik dan terlindungi.

  • commandToExecute
  • fileUris

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

Pengaturan publik dikirim dalam teks yang jelas ke komputer virtual tempat skrip akan dijalankan. Pengaturan terproteksi dienkripsi menggunakan kunci yang hanya diketahui oleh Azure dan komputer virtual. Pengaturan disimpan ke komputer virtual saat dikirim, yaitu, jika pengaturan dienkripsi, pengaturan disimpan dan dienkripsi pada komputer virtual. Sertifikat yang digunakan untuk mendekripsi nilai terenkripsi disimpan pada komputer virtual, dan digunakan untuk mendekripsi pengaturan (jika perlu) pada runtime.

Properti: managedIdentity

Catatan

Properti ini harus ditentukan dalam pengaturan yang dilindungi saja.

CustomScript (versi 1.10 dan seterusnya) mendukung identitas terkelola untuk mengunduh file dari URL yang diberikan dalam pengaturan "fileUris". Hal ini memungkinkan CustomScript untuk mengakses blob atau kontainer privat Azure Storage tanpa pengguna harus melewati rahasia seperti token SAS atau kunci akun penyimpanan.

Untuk menggunakan fitur ini, pengguna harus menambahkan identitas yang ditetapkan sistem atau ditetapkan pengguna ke VM atau VMMS di mana CustomScript diharapkan untuk berjalan, dan memberikan akses identitas terkelola ke blob atau kontainer Azure Storage.

Untuk menggunakan identitas yang ditetapkan sistem pada VM/VMSS target, atur bidang "managedidentity" ke objek json kosong.

Contoh:

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

Untuk menggunakan identitas yang ditetapkan pengguna pada VM/VMSS target, konfigurasikan bidang "managedidentity" dengan ID klien atau ID objek identitas terkelola.

Contoh:

{
  "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 managedIdentity tidak dapat digunakan bersama dengan properti storageAccountName atau storageAccountKey

Penyebaran templat

Ekstensi komputer virtual Azure dapat disebarkan dengan 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. Sampel berikut menunjukkan cara menggunakan ekstensi Skrip Kustom:

Penyebaran PowerShell

Perintah Set-AzVMCustomScriptExtension dapat digunakan 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 tambahan

Menggunakan beberapa skrip

Dalam contoh ini, Anda memiliki tiga skrip yang digunakan untuk membangun server. commandToExecute memanggil skrip pertama, maka Anda memiliki opsi tentang bagaimana skrip yang lain dipanggil. Misalnya, Anda dapat memiliki skrip master yang mengontrol eksekusi, dengan penanganan kesalahan, pengelogan, dan manajemen status yang tepat. Skrip diunduh ke komputer lokal untuk dijalankan. Misalnya dalam 1_Add_Tools.ps1 Anda akan memanggil 2_Add_Features.ps1dengan menambahkan .\2_Add_Features.ps1 ke skrip, dan mengulangi 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 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

Cara menjalankan skrip kustom lebih dari sekali dengan CLI

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

  • Parameter Nama ekstensi sama dengan penyebaran ekstensi sebelumnya.
  • Perbarui konfigurasi jika tidak, perintah tidak akan dijalankan kembali. Anda dapat menambahkan properti dinamis ke dalam perintah, seperti tanda waktu.

Atau, Anda dapat mengatur properti ForceUpdateTag ke benar.

Menggunakan Invoke-WebRequest

Jika Anda menggunakan Invoke-WebRequest dalam skrip, Anda harus menentukan parameter -UseBasicParsing atau Anda akan menerima kesalahan berikut saat memeriksa status detail:

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

Untuk menyebarkan Ekstensi Skrip Kustom pada Set Skala, lihat Add-AzVmssExtension

Komputer virtual klasik

Penting

Komputer virtual klasik akan dihentikan pada 1 Maret 2023.

Jika Anda menggunakan sumber IaaS dari ASM, harap menyelesaikan migrasi sebelum 1 Maret 2023. Kami mendorong Anda untuk beralih lebih cepat untuk memanfaatkan banyak peningkatan fitur di Azure Resource Manager.

Untuk mengetahui informasi selengkapnya, lihat Migrasikan sumber IaaS Anda ke Azure Resource Manager sebelum 1 Maret 2023.

Untuk menyebarkan Ekstensi Skrip Kustom pada komputer virtual klasik, Anda dapat menggunakan portal Microsoft Azure atau cmdlet Azure PowerShell Klasik.

portal Microsoft Azure

Navigasikan ke sumber daya Komputer Virtual Klasik Anda. Pilih Ekstensi di bawah Pengaturan.

Klik + Tambahkan dan dalam daftar sumber daya pilih Ekstensi Skrip Kustom.

Pada halaman Memasang ekstensi, pilih file PowerShell lokal, dan isi argumen apa pun dan klik Ok.

PowerShell

Gunakan cmdlet Set-AzureVMCustomScriptExtension yang dapat digunakan untuk menambahkan ekstensi Skrip Kustom ke komputer virtual yang ada.

# define your file URI
$fileUri = 'https://xxxxxxx.blob.core.windows.net/scripts/Create-File.ps1'

# create vm object
$vm = Get-AzureVM -Name <vmName> -ServiceName <cloudServiceName>

# set extension
Set-AzureVMCustomScriptExtension -VM $vm -FileUri $fileUri -Run 'Create-File.ps1'

# update vm
$vm | Update-AzureVM

Memecahkan masalah dan mendukung

Pecahkan masalah

Data tentang status penyebaran ekstensi dapat diambil dari portal Microsoft Azure dan dengan menggunakan modul Azure PowerShell. Untuk melihat status penyebaran ekstensi untuk komputer 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 komputer virtual target.

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

FIle yang ditetapkan diunduh ke folder berikut ini pada komputer virtual target.

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

di mana <n> merupakan bilangan bulat desimal, yang dapat 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.

Ketika menjalankan perintah commandToExecute, ekstensi mengatur direktori ini (misalnya, ...\Downloads\2) sebagai direktori yang bekerja saat ini. Proses ini memungkinkan penggunaan jalur relatif untuk menemukan file yang diunduh melalui properti fileURIs. Lihat tabel di bawah ini misalnya.

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 melalui daftar properti fileUris. Seperti yang ditunjukkan pada tabel di bawah ini, file yang diunduh dipetakan ke dalam subdirectories pengunduhan untuk mencerminkan struktur nilai fileUris.

Contoh File yang Diunduh

URI dalam fileUris Lokasi pengunduhan relatif Lokasi pengunduhan absolut 1
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

1 Jalur direktori absolut berubah selama masa berlaku komputer virtual, tetapi tidak dalam satu eksekusi ekstensi CustomScript.

Dukungan

Jika Anda memerlukan bantuan lebih lanjut kapan saja dalam artikel ini, Anda dapat menghubungi pakar Azure di forum Azure MSDN dan Stack Overflow. Anda juga dapat mengajukan insiden dukungan Azure. Buka situs dukungan Azure dan pilih Dapatkan dukungan. Untuk mengetahui informasi tentang cara menggunakan Dukungan Azure, baca FAQ tentang Dukungan Microsoft Azure.