Windows için Özel Betik Uzantısı

  • Makale

Ö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.
  • Özel Betik Uzantısı LocalSystem hesabının altında çalışır.
  • storageAccountName ve storageAccountKey özelliklerini kullanmayı planlıyorsanız bu özelliklerin protectedSettings 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ımcı 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 protectedSettingsbelirtilmelidir.
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:

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 $settingsdiğ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 commandToExecutebaş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 trueayarlayabilirsiniz.

Invoke-WebRequest kullanma

Betiğinizde Invoke-WebRequest kullanıyorsanız parametresini -UseBasicParsingbelirtmeniz 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\2geç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.