Windows için Özel Betik Uzantısı
Özel Betik Uzantısı, Azure sanal makinelerinde (VM) betikleri indirir ve çalıştırır. Dağıtım sonrası yapılandırma, yazılım yüklemesi veya başka bir yapılandırma veya yönetim görevi için bu uzantıyı kullanın. Betikleri Azure Depolama veya GitHub'dan indirebilir veya uzantı çalışma zamanında Azure portalına sağlayabilirsiniz.
Özel Betik Uzantısı, Azure Resource Manager şablonlarıyla tümleşir. Azure CLI, Azure PowerShell, Azure portalı veya Azure Sanal Makineler REST API'sini kullanarak da çalıştırabilirsiniz.
Bu makalede, Azure PowerShell modülünü ve Azure Resource Manager şablonlarını kullanarak Özel Betik Uzantısı'nın nasıl kullanılacağı açıklanmaktadır. Ayrıca Windows sistemleri için sorun giderme adımları sağlar.
Önkoşullar
Not
Parametresiyle aynı VM ile çalışmak Update-AzVM
için Özel Betik Uzantısı'nı kullanmayın. Uzantı kendisini bekler.
Desteklenen Windows işletim sistemleri
Windows İşletim Sistemi | x64 |
---|---|
Windows 10 | Desteklenir |
Windows 11 | Desteklenir |
Windows Server 2008 SP2 | Desteklenir |
Windows Server 2008 R2 | Desteklenir |
Windows Server 2012 | Desteklenir |
Windows Server 2012 R2 | Desteklenir |
Windows Server 2016 | Desteklenir |
Windows Server 2016 Core | Desteklenir |
Windows Server 2019 | Desteklenir |
Windows Server 2019 Core | Desteklenir |
Windows Server 2022 | Desteklenir |
Windows Server 2022 Core | Desteklenir |
Betik konumu
Uzantıyı Azure Blob Depolama'ya erişebilmesi için Azure Blob Depolama kimlik bilgilerinizi kullanacak şekilde ayarlayabilirsiniz. Sanal makine, GitHub veya iç dosya sunucusu gibi bir uç noktaya yönlendirebildiği sürece betik konumu her yer olabilir.
İnternet bağlantısı
Betiği GitHub veya Azure Depolama gibi bir dış konumdan indirmek için diğer güvenlik duvarı veya ağ güvenlik grubu (NSG) bağlantı noktalarını açmanız gerekir. Örneğin, betiğiniz Azure Depolama'da bulunuyorsa Depolama için Azure NSG hizmet etiketlerini kullanarak erişime izin verebilirsiniz.
Özel Betik Uzantısı'nın sertifika doğrulamasını atlayacak bir yolu yoktur. Güvenli bir konumdan , örneğin otomatik olarak imzalanan bir sertifikayla indiriyorsanız, doğrulama yordamına göre uzak sertifika geçersiz gibi hatalar alabilirsiniz. Sertifikanın VM'deki Güvenilen Kök Sertifika Yetkilileri deposuna doğru yüklendiğinden emin olun.
Betiğiniz yerel bir sunucuda olsa bile diğer güvenlik duvarı veya NSG bağlantı noktalarını açmanız gerekebilir.
İpuçları
- Çıkış son 4.096 baytla sınırlıdır.
- Karakterlerden uygun şekilde kaçınılması, dizgilerin doğru şekilde ayrıştırılmasını sağlar. Örneğin, dosya yollarıyla ilgilenirken tek bir değişmez değer ters eğik çizgiden kurtulmak için her zaman iki ters eğik çizgiye ihtiyacınız vardır. Örnek:
{"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
- Bu uzantı için en yüksek hata oranı betikteki söz dizimi hatalarından kaynaklanır. Betiğin hatasız çalıştığını doğrulayın. Hataları bulmayı kolaylaştırmak için betiğe daha fazla günlük kaydı ekleyin.
- Bir kez etkili betikler yazın. Böylece yanlışlıkla birden fazla çalıştırılan betikler sistem değişikliklerine neden olmaz.
- Betiklerin çalışırken kullanıcı girişi gerektirmediğinden emin olun.
- Betiğin 90 dakika çalışmasına izin verilir. Daha uzun olan betikler uzantının sağlanamamasına neden olur.
- Betiğin içine yeniden başlatmalar yerleştirmeyin. Bu eylem, yüklenen diğer uzantılarla ilgili sorunlara neden olur ve uzantı yeniden başlatıldıktan sonra devam etmez.
- Uygulamaları yüklemeden ve betikleri çalıştırmadan önce yeniden başlatmaya neden olan bir betiğiniz varsa, Windows Zamanlanmış Görevi’ni veya DSC, Chef ya da Puppet uzantıları gibi araçları kullanarak yeniden başlatmayı zamanlayın.
- VM aracısının durdurulmasına veya güncelleştirilmesine neden olan bir betik çalıştırmayın. Bunun yapılması uzantıyı geçiş durumunda bırakabilir ve zaman aşımına neden olabilir.
- Uzantı bir betiği yalnızca bir kez çalıştırır. Her başlangıçta bir betik çalıştırmak istiyorsanız uzantıyı kullanarak bir Windows Zamanlanmış Görevi oluşturun.
- Betiğin çalıştırılacağı zamanı belirlemek istiyorsanız uzantıyı kullanarak bir Windows Zamanlanmış Görevi oluşturun.
- Betik çalışırken Azure portal veya Azure CLI üzerinden uzantı durumunu yalnızca geçiş durumunda şeklinde görürsünüz. Çalışan bir betikle ilgili daha sık durum güncelleştirmesi almak isterseniz kendi çözümünüzü oluşturun.
- Özel Betik Uzantısı, ara sunucuları yerel olarak desteklemez. Bununla birlikte betiğinizin içinde ara sunucuları destekleyen Invoke-WebRequest gibi bir dosya aktarım aracı kullanabilirsiniz.
- Betiklerinizin veya komutlarınızın kullanıyor olabileceği varsayılan olmayan dizin konumlarına dikkat edin. Bu durumla başa çıkmak için bir mantık oluşturun.
- Kayıt defteri anahtarında
HKLM\SOFTWARE\Microsoft\Command Processor\AutoRun
herhangi bir özel ayar olmadığından emin olun (burada ayrıntılı olarak anlatılır). Bu, Özel Betik Uzantısı yüklemesi sırasında tetiklenecek veya aşamaları etkinleştirebilir ve gibi'XYZ is not recognized as an internal or external command, operable program or batch file'
bir hataya neden olur. - Özel Betik Uzantısı
LocalSystem
hesabının altında çalışır. storageAccountName
vestorageAccountKey
özelliklerini kullanmayı planlıyorsanız bu özelliklerinprotectedSettings
konumunda birlikte bulunması gerekir.- Sanal makineye bir uzantının yalnızca bir sürümünü uygulayabilirsiniz. İkinci bir özel betik çalıştırmak için mevcut uzantıyı yeni bir yapılandırmayla güncelleştirebilirsiniz. Alternatif olarak, özel betik uzantısını kaldırabilir ve güncelleştirilmiş betikle yeniden uygulayabilirsiniz
Uzantı şeması
Özel Betik Uzantısı yapılandırması, betik konumu ve çalıştırılacak komut gibi öğeleri belirtir. Bu yapılandırmayı yapılandırma dosyalarında depolayabilir, komut satırında belirtebilir veya bir Azure Resource Manager şablonunda belirtebilirsiniz.
Hassas verileri korumalı bir yapılandırmada depolayabilirsiniz. Bu yapılandırma yalnızca VM içinde şifrelenir ve şifresi çözülür. Korumalı yapılandırma, yürütme komutu parola veya paylaşılan erişim imzası (SAS) dosya başvurusu gibi gizli diziler içerdiğinde yararlıdır. Bir örnek aşağıda verilmiştir:
{
"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"
]
}
}
}
Not
özelliği managedIdentity
veya özelliğiyle storageAccountName
birlikte kullanılmamalıdırstorageAccountKey
.
Bir kerede bir VM'ye uzantının yalnızca bir sürümü yüklenebilir. Aynı VM için aynı Azure Resource Manager şablonunda iki kez özel betik belirtme başarısız olur.
Bu şemayı VM kaynağı içinde veya tek başına kaynak olarak kullanabilirsiniz. Bu uzantı Azure Resource Manager şablonunda tek başına kaynak olarak kullanılıyorsa, kaynağın adı virtualMachineName/extensionName biçiminde olmalıdır.
Özellik değerleri
Veri Akışı Adı | Değer veya örnek | Veri türü |
---|---|---|
apiVersion | 2015-06-15 |
tarih |
yayınevi | Microsoft.Compute |
Dize |
Tür | CustomScriptExtension |
Dize |
typeHandlerVersion | 1.10 |
int |
fileUris | https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 |
dizi |
timestamp | 123456789 |
32 bit tamsayı |
commandToExecute | powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 |
Dize |
storageAccountName | examplestorageacct |
Dize |
storageAccountKey | TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== |
Dize |
managedIdentity | { } veya veya { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" } { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" } |
JSON nesnesi |
Not
Bu özellik adları büyük/küçük harfe duyarlıdır. Dağıtım sorunlarını önlemek için burada gösterildiği gibi adları kullanın.
Özellik değeri ayrıntıları
Özellik | İsteğe bağlı veya gerekli | Ayrıntılar |
---|---|---|
fileUris | İsteğe bağlı | İndirilecek dosyaların URL'leri. URL'ler hassassa, örneğin anahtar içeriyorsa, bu alan içinde protectedSettings belirtilmelidir. |
commandToExecute | Zorunlu | Çalıştırılacak giriş noktası betiği. Komutunuz parolalar gibi gizli diziler içeriyorsa veya dosya URI'leriniz hassassa bu özelliği kullanın. |
timestamp | İsteğe bağlı | Bu değeri yalnızca betiğin yeniden çalıştırılmasını tetikleecek şekilde değiştirin. Herhangi bir tamsayı değeri, önceki değerden farklı olduğu sürece kabul edilebilir. |
storageAccountName | İsteğe bağlı | Depolama hesabının adı. Depolama kimlik bilgilerini belirtirseniz tüm fileUris değerlerin Azure blobları için URL'ler olması gerekir. |
storageAccountKey | İsteğe bağlı | Depolama hesabının erişim anahtarı. |
managedIdentity | İsteğe bağlı | Dosyaları indirmek için yönetilen kimlik. Geçerli değerler, clientId yönetilen kimliğin istemci kimliği olan (isteğe bağlı, dize) ve objectId yönetilen kimliğin nesne kimliği olan (isteğe bağlı, dize) değerleridir. |
Genel ayarlar , betiğin çalıştığı VM'ye düz metin olarak gönderilir. Korumalı ayarlar yalnızca Azure ve VM tarafından bilinen bir anahtar aracılığıyla şifrelenir. Ayarlar vm'ye gönderildikçe kaydedilir. Başka bir ifadeyle, ayarlar şifrelendiyse vm'ye şifrelenir. Şifrelenmiş değerlerin şifresini çözmek için kullanılan sertifika VM'de depolanır. Sertifika, gerekirse çalışma zamanında ayarların şifresini çözmek için de kullanılır.
Genel ayarları kullanmak hata ayıklama için yararlı olabilir, ancak korumalı ayarları kullanmanızı öneririz.
Genel veya korumalı ayarlarda aşağıdaki değerleri ayarlayabilirsiniz. Uzantı, bu değerlerin hem genel hem de korumalı ayarlarda ayarlandığı tüm yapılandırmaları reddeder.
commandToExecute
fileUris
Özellik: managedIdentity
Not
Bu özellik yalnızca korumalı ayarlarda belirtilmelidir .
Sürüm 1.10 ve üzeri olan Özel Betik Uzantısı, ayarda fileUris
sağlanan URL'lerden dosya indirmek için yönetilen kimlikleri destekler. özelliği, Kullanıcının SAS belirteçleri veya depolama hesabı anahtarları gibi gizli dizileri geçirmesine gerek kalmadan Özel Betik Uzantısı'nın Azure Depolama özel bloblarına veya kapsayıcılarına erişmesine olanak tanır.
Bu özelliği kullanmak için, Özel Betik Uzantısı'nın çalıştığı VM'ye veya Sanal Makine Ölçek Kümesine sistem tarafından atanan veya kullanıcı tarafından atanan bir kimlik ekleyin. Ardından yönetilen kimliğe Azure Depolama kapsayıcısına veya bloba erişim verin.
Hedef VM veya Sanal Makine Ölçek Kümesinde sistem tarafından atanan kimliği kullanmak için boş bir JSON nesnesine ayarlayın managedidentity
.
{
"fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
"commandToExecute": "powershell.exe script1.ps1",
"managedIdentity" : {}
}
Hedef VM veya Sanal Makine Ölçek Kümesinde kullanıcı tarafından atanan kimliği kullanmak için, istemci kimliği veya yönetilen kimliğin nesne kimliğiyle yapılandırın managedidentity
.
{
"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" }
}
Not
özelliği managedIdentity
veya özelliğiyle storageAccountName
birlikte kullanılmamalıdırstorageAccountKey
.
Şablon dağıtımı
Azure Resource Manager şablonlarını kullanarak Azure VM uzantılarını dağıtabilirsiniz. Önceki bölümde ayrıntılarıyla belirtilen JSON şeması, bir Azure Resource Manager şablonunda, şablonun dağıtımı sırasında Özel Betik Uzantısı'nı çalıştırmak için kullanılabilir. Aşağıdaki örneklerde Özel Betik Uzantısının nasıl kullanılacağı gösterilmektedir:
- Azure Resource Manager şablonlarıyla sanal makine uzantılarını dağıtma
- Windows ve Azure SQL Veritabanı'da İki Katmanlı Uygulama Dağıtma
PowerShell dağıtımı
Özel Betik Uzantısı'nı Set-AzVMCustomScriptExtension
mevcut bir sanal makineye eklemek için komutunu kullanabilirsiniz. Daha fazla bilgi için bkz . Set-AzVMCustomScriptExtension.
Set-AzVMCustomScriptExtension -ResourceGroupName <resourceGroupName> `
-VMName <vmName> `
-Location myLocation `
-FileUri <fileUrl> `
-Run 'myScript.ps1' `
-Name DemoScriptExtension
Örnekler
Birden çok betik kullanma
Bu örnekte sunucunuzu oluşturmak için üç betik kullanılır. commandToExecute
özelliği ilk betiği çağırır. Ardından diğerlerinin nasıl çağrıldığıyla ilgili seçenekleriniz vardır. Örneğin, doğru hata işleme, günlüğe kaydetme ve durum yönetimi ile yürütmeyi denetleen bir müşteri adayı betiğiniz olabilir. Betikler çalıştırılacak yerel makineye indirilir.
Örneğin, 1_Add_Tools.ps1'de betike ekleyerek .\2_Add_Features.ps1
2_Add_Features.ps1'i çağırırsınız. içinde tanımladığınız $settings
diğer betikler için bu işlemi yineleyin.
$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;
Betikleri yerel paylaşımdan çalıştırma
Bu örnekte, betik konumunuz için yerel bir Sunucu İleti Bloğu (SMB) sunucusu kullanmak isteyebilirsiniz. Ardından dışında commandToExecute
başka bir ayar sağlamanız gerekmez.
$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
CLI kullanarak özel betiği birden çok kez çalıştırma
Özel Betik Uzantısı işleyicisi, tam olarak aynı ayarlar geçirilmişse betiğin yeniden çalıştırılmasını engeller. Bu davranış yanlışlıkla yeniden çalıştırmayı önler ve betik bir kez etkili değilse beklenmeyen davranışlara neden olabilir. İşleyicinin yeniden çalıştırmayı engelleyip engellemediğini onaylamak için bölümüne bakın C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*
. Aşağıdakine benzer bir uyarı aranıyor:
Current sequence number, <SequenceNumber>, is not greater than the sequence number
of the most recently executed configuration. Exiting...
Özel Betik Uzantısı'nı birden çok kez çalıştırmak istiyorsanız, bunu yalnızca şu koşullar altında yapabilirsiniz:
- Uzantının
Name
parametresi, uzantının önceki dağıtımıyla aynıdır. - Yapılandırmayı güncelleştirdiniz. Komutuna zaman damgası gibi bir dinamik özellik ekleyebilirsiniz. İşleyici yapılandırma ayarlarında bir değişiklik algılarsa, bu değişikliği betiği yeniden çalıştırmak için açık bir istek olarak değerlendirir.
Alternatif olarak, ForceUpdateTag özelliğini olarak true
ayarlayabilirsiniz.
Invoke-WebRequest kullanma
Betiğinizde Invoke-WebRequest kullanıyorsanız parametresini -UseBasicParsing
belirtmeniz gerekir. Parametresini belirtmezseniz, ayrıntılı durumu denetlerken aşağıdaki hatayı alırsınız:
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.
Sanal Makine Ölçek Kümeleri
Özel Betik Uzantısı'nı Azure portalından dağıtırsanız, depolama hesabınızdaki betiklere erişmek için SAS belirtecinin süresinin dolması üzerinde denetiminiz yoktur. İlk dağıtım çalışır, ancak depolama hesabının SAS belirtecinin süresi dolduğunda, Özel Betik Uzantısı artık depolama hesabına erişemediğinden sonraki ölçeklendirme işlemleri başarısız olur.
Özel Betik Uzantısını bir Sanal Makine Ölçek Kümesine dağıtırken PowerShell, Azure CLI veya Azure Resource Manager şablonu kullanmanızı öneririz. Bu şekilde, yönetilen kimlik kullanmayı seçebilir veya ihtiyacınız olduğu sürece depolama hesabınızdaki betiklere erişmek için SAS belirtecinin süresinin dolmak üzere doğrudan denetimine sahip olabilirsiniz.
Sorun giderme ve destek
Azure portalından ve Azure PowerShell modülünü kullanarak uzantı dağıtımlarının durumuyla ilgili verileri alabilirsiniz. Bir VM için uzantıların dağıtım durumunu görmek için aşağıdaki komutu çalıştırın:
Get-AzVMExtension -ResourceGroupName <resourceGroupName> `
-VMName <vmName> -Name myExtensionName
Uzantı çıkışı, hedef sanal makinede aşağıdaki klasörün altında bulunan dosyalara kaydedilir:
C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension
Belirtilen dosyalar hedef sanal makinede aşağıdaki klasöre indirilir:
C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.*\Downloads\<n>
Yukarıdaki yolda, <n>
uzantının yürütmeleri arasında değişebilen ondalık bir tamsayıdır. Değer 1.*
, uzantının gerçek, geçerli typeHandlerVersion
değeriyle eşleşir. Örneğin, gerçek dizin olabilir C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2
.
Komutu çalıştırdığınızda commandToExecute
, uzantı bu dizini (örneğin, ...\Downloads\2
geçerli çalışma dizini) ayarlar. Bu işlem, özelliğini kullanarak indirilen dosyaları bulmak için göreli yolların fileURIs
kullanılmasını sağlar. İndirilen dosya örnekleri şunlardır:
içinde URI fileUris |
Göreli indirme konumu | Mutlak indirme konumu |
---|---|---|
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 |
Mutlak dizin yolları VM'nin ömrü boyunca değişir, ancak Özel Betik Uzantısı'nın tek bir yürütmesi içinde değişmez.
Mutlak indirme yolu zaman içinde farklılık gösterebileceğinden, mümkün olduğunca dizede commandToExecute
göreli betik/dosya yollarını tercih etmek daha iyidir. Örneğin:
"commandToExecute": "powershell.exe . . . -File \"./scripts/myscript.ps1\""
özellik listesi kullanılarak indirilen dosyalar için ilk URI kesiminden fileUris
sonraki yol bilgileri tutulur. Önceki tabloda gösterildiği gibi, indirilen dosyalar, değerlerin fileUris
yapısını yansıtmak için indirme alt dizinleriyle eşlenir.
Destek
Bu makalenin herhangi bir bölümüyle ilgili yardıma ihtiyacınız varsa Azure Topluluk Desteği'ndeki Azure uzmanlarına başvurun.
Azure desteği olayı kaydetmek için Azure desteği sitesine gidin ve Destek al'ı seçin.
Azure desteği kullanma hakkında bilgi için Microsoft Azure desteği SSS bölümünü okuyun.