Rozšíření vlastních skriptů pro virtuální počítače

Článek
02/02/2024

Rozšíření vlastních skriptů stáhne a spustí skripty na virtuálních počítačích Azure. Toto rozšíření použijte pro konfiguraci po nasazení, instalaci softwaru nebo jakoukoli jinou úlohu konfigurace nebo správy. Skripty si můžete stáhnout ze služby Azure Storage nebo GitHubu nebo je poskytnout webu Azure Portal za běhu rozšíření.

Rozšíření vlastních skriptů se integruje se šablonami Azure Resource Manageru. Můžete ho také spustit pomocí Azure CLI, Azure PowerShellu, webu Azure Portal nebo rozhraní REST API služby Azure Virtual Machines.

Tento článek popisuje, jak používat rozšíření vlastních skriptů pomocí modulu Azure PowerShellu a šablon Azure Resource Manageru. Poskytuje také postup řešení potíží pro systémy Windows.

Požadavky

Poznámka:

Nepoužívejte rozšíření vlastních skriptů ke spuštění Update-AzVM se stejným virtuálním počítačem jako jeho parametr. Rozšíření počká sám na sebe.

Podporované operační systémy Windows

Operační systém Windows	x64
Windows 10	Podporováno
Windows 11	Podporováno
Windows Server 2008 SP2	Podporováno
Windows Server 2008 R2	Podporováno
Windows Server 2012	Podporováno
Windows Server 2012 R2	Podporováno
Windows Server 2016	Podporováno
Windows Server 2016 Core	Podporováno
Windows Server 2019	Podporováno
Windows Server 2019 Core	Podporováno
Windows Server 2022	Podporováno
Windows Server 2022 Core	Podporováno

Umístění skriptu

Rozšíření můžete nastavit tak, aby používalo vaše přihlašovací údaje do služby Azure Blob Storage, a tak mělo přístup ke službě Azure Blob Storage. Skript může být umístěn kdekoli, pokud může virtuální počítač k tomuto koncovému bodu směrovat, například GitHub nebo interní souborový server.

Připojení k internetu

Chcete-li skript stáhnout zvenčí, například ze služby GitHub nebo Azure Storage, musíte otevřít další porty brány firewall nebo skupiny zabezpečení sítě (NSG). Pokud je váš skript například umístěn na úložišti Azure Storage, můžete povolit přístup pomocí značek služeb Azure NSG pro úložiště.

Rozšíření vlastních skriptů nemá žádný způsob, jak obejít ověření certifikátu. Pokud se například stahujete ze zabezpečeného umístění s certifikátem podepsaným svým držitelem, můžou se zobrazit chyby, jako je vzdálený certifikát, podle ověřovací procedury je neplatný. Ujistěte se, že je certifikát správně nainstalovaný v úložišti důvěryhodných kořenových certifikačních autorit na virtuálním počítači.

Pokud je váš skript na místním serveru, možná budete muset otevřít další porty brány firewall nebo NSG.

Tipy

Výstup je omezený na posledních 4 096 bajtů.
Správné řídicí znaky pomůžou zajistit, aby se řetězce správně parsovaly. Při práci s cestami k souborům například vždy potřebujete dvě zpětná lomítka s jedním literálovým zpětným lomítkem. Ukázka: {"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
K selhání tohoto rozšíření nejčastěji dochází kvůli chybám syntaxe ve skriptu. Ověřte, že skript běží bez chyb. Vložte do skriptu více protokolování, aby bylo snazší najít chyby.
Pište skripty, které jsou idempotentní, aby jejich náhodné spuštění více než jednou nezpůsobilo systémové změny.
Ujistěte se, že skripty při svém spuštění nevyžadují vstup uživatele.
Skript má povoleno běžet 90 minut. Cokoli delšího má za následek neúspěšné nasazení rozšíření.
Do skriptu nevkládejte restarty. Tato akce způsobuje problémy s dalšími instalovanými rozšířeními a rozšíření po restartu nepokračuje.
Pokud máte skript, který způsobí restart před instalací aplikací a spuštěním skriptů, naplánujte restart pomocí naplánované úlohy systému Windows nebo pomocí nástrojů, jako jsou rozšíření DSC, Chef nebo Puppet.
Nespouštějte skript, který způsobí zastavení nebo aktualizaci agenta virtuálního počítače. Rozšíření by tak mohlo zůstat ve stavu přechodu a vést k vypršení časového limitu.
Rozšíření spustí skript pouze jednou. Pokud chcete spustit skript při každém spuštění, použijte rozšíření k vytvoření naplánované úlohy systému Windows.
Pokud chcete naplánovat spuštění skriptu, použijte rozšíření k vytvoření naplánované úlohy systému Windows.
Pokud skript běží, vidíte pouze stav přechodu rozšíření z portálu Azure nebo Azure CLI. Pokud chcete častější aktualizace stavu spuštěného skriptu, vytvořte si vlastní řešení.
Rozšíření Custom Script Extension nativně nepodporuje proxy servery. Můžete však použít nástroj pro přenos souborů, například Invoke-WebRequest, který podporuje proxy servery ve vašem skriptu.
Pamatujte na nevýchozí umístění adresářů, na která mohou vaše skripty nebo příkazy odkazovat. Zajistěte logiku pro řešení takové situace.
Rozšíření vlastního skriptu Custom Script Extension běží pod účtem LocalSystem.
Pokud plánujete používat vlastnosti storageAccountName a storageAccountKey, musí být tyto vlastnosti v umístění protectedSettings.
Na virtuálním počítači můžete použít pouze jednu verzi rozšíření. Chcete-li spustit druhý vlastní skript, můžete aktualizovat stávající rozšíření pomocí nové konfigurace. Případně můžete rozšíření Custom Script Extension odebrat a znovu ho použít s aktualizovaným skriptem.

Schéma rozšíření

Konfigurace rozšíření vlastních skriptů určuje například umístění skriptu a příkaz, který se má spustit. Tuto konfiguraci můžete uložit do konfiguračních souborů, zadat ji na příkazovém řádku nebo ji zadat v šabloně Azure Resource Manageru.

Citlivá data můžete ukládat v chráněné konfiguraci, která se šifruje a dešifruje jenom uvnitř virtuálního počítače. Chráněná konfigurace je užitečná, když spouštěcí příkaz obsahuje tajné kódy, jako je heslo nebo odkaz na soubor sdíleného přístupového podpisu (SAS). Tady je příklad:

{
    "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"
            ]
        }
    }
}

Poznámka:

Vlastnost managedIdentitynesmí být použita ve spojení s storageAccountName vlastností nebo storageAccountKey vlastností.

Na virtuální počítač je možné nainstalovat najednou jenom jednu verzi rozšíření. Zadání vlastního skriptu dvakrát ve stejné šabloně Azure Resource Manageru pro stejný virtuální počítač selže.

Toto schéma můžete použít uvnitř prostředku virtuálního počítače nebo jako samostatný prostředek. Pokud se toto rozšíření používá jako samostatný prostředek v šabloně Azure Resource Manageru, musí být název prostředku ve formátu virtualMachineName/extensionName.

Hodnoty vlastností

Název	Hodnota nebo příklad	Datový typ
apiVersion	`2015-06-15`	datum
Vydavatel	`Microsoft.Compute`	string
type	`CustomScriptExtension`	string
typeHandlerVersion	`1.10`	int
identifikátory fileUris	`https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1`	pole
časové razítko	`123456789`	32bitové celé číslo
commandToExecute	`powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1`	string
storageAccountName	`examplestorageacct`	string
storageAccountKey	`TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==`	string
managedIdentity	`{ }`nebo `{ "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }{ "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }`	Objekt JSON

Poznámka:

V těchto názvech vlastností se rozlišují malá a velká písmena. Pokud se chcete vyhnout problémům s nasazením, použijte názvy, jak je znázorněno tady.

Podrobnosti o hodnotě vlastnosti

Vlastnost	Volitelné nebo povinné	Detaily
identifikátory fileUris	Volitelné	Adresy URL souborů, které se mají stáhnout. Pokud jsou adresy URL citlivé, například pokud obsahují klíče, musí být toto pole zadáno v `protectedSettings`.
commandToExecute	Požaduje se	Skript vstupního bodu, který se má spustit. Tuto vlastnost použijte, pokud váš příkaz obsahuje tajné kódy, jako jsou hesla nebo jestli jsou citlivé identifikátory URI vašeho souboru.
časové razítko	Volitelné	Tuto hodnotu změňte pouze tak, aby se aktivovalo opětovné spuštění skriptu. Jakákoli celočíselná hodnota je přijatelná, pokud se liší od předchozí hodnoty.
storageAccountName	Volitelné	Název účtu úložiště. Pokud zadáte přihlašovací údaje úložiště, `fileUris` všechny hodnoty musí být adresy URL pro objekty blob Azure.
storageAccountKey	Volitelné	Přístupový klíč účtu úložiště.
managedIdentity	Volitelné	Spravovaná identita pro stahování souborů. Platné hodnoty jsou `clientId` (volitelné, řetězec), což je ID klienta spravované identity a `objectId` (volitelné, řetězec), což je ID objektu spravované identity.

Veřejné nastavení se do virtuálního počítače, na kterém běží skript, odesílá ve formátu prostého textu. Chráněná nastavení se šifrují prostřednictvím klíče známého jenom v Azure a virtuálním počítači. Nastavení se uloží na virtuální počítač při jejich odeslání. To znamená, že pokud se nastavení zašifrovalo, uloží se na virtuální počítač zašifrované. Certifikát, který slouží k dešifrování šifrovaných hodnot, je uložený na virtuálním počítači. Certifikát se také používá k dešifrování nastavení v případě potřeby za běhu.

Použití veřejných nastavení může být užitečné pro ladění, ale doporučujeme používat chráněná nastavení.

Následující hodnoty můžete nastavit buď ve veřejném, nebo chráněném nastavení. Rozšíření odmítne jakoukoli konfiguraci, ve které jsou tyto hodnoty nastavené ve veřejném i chráněném nastavení.

commandToExecute
fileUris

Vlastnost: managedIdentity

Poznámka:

Tato vlastnost musí být zadána pouze v chráněných nastaveních.

Rozšíření vlastních skriptů verze 1.10 a novější podporuje spravované identity pro stahování souborů z adres URL uvedených v fileUris nastavení. Tato vlastnost umožňuje rozšíření vlastních skriptů přistupovat k privátním objektům blob nebo kontejnerům Azure Storage, aniž by uživatel musel předávat tajné kódy, jako jsou tokeny SAS nebo klíče účtu úložiště.

Pokud chcete tuto funkci použít, přidejte do virtuálního počítače nebo škálovací sady virtuálních počítačů, ve které běží rozšíření vlastních skriptů, identitu přiřazenou systémem nebo uživatelem. Potom udělte spravované identitě přístup ke kontejneru nebo objektu blob služby Azure Storage.

Pokud chcete použít identitu přiřazenou systémem na cílovém virtuálním počítači nebo ve škálovací sadě virtuálních počítačů, nastavte managedidentity na prázdný objekt JSON.

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

Pokud chcete použít identitu přiřazenou uživatelem na cílovém virtuálním počítači nebo škálovací sadě virtuálních počítačů, nakonfigurujte managedidentity ID klienta nebo ID objektu spravované identity.

{
  "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" }
}

Poznámka:

Vlastnost managedIdentitynesmí být použita ve spojení s storageAccountName vlastností nebo storageAccountKey vlastností.

Nasazení šablon

Rozšíření virtuálních počítačů Azure můžete nasadit pomocí šablon Azure Resource Manageru. Schéma JSON podrobně popsané v předchozí části se dá použít v šabloně Azure Resource Manageru ke spuštění rozšíření vlastních skriptů během nasazení šablony. Následující ukázky ukazují, jak používat rozšíření vlastních skriptů:

Nasazení PowerShellu

Pomocí příkazu můžete Set-AzVMCustomScriptExtension přidat rozšíření vlastních skriptů do existujícího virtuálního počítače. Další informace naleznete v tématu Set-AzVMCustomScriptExtension.

Set-AzVMCustomScriptExtension -ResourceGroupName <resourceGroupName> `
    -VMName <vmName> `
    -Location myLocation `
    -FileUri <fileUrl> `
    -Run 'myScript.ps1' `
    -Name DemoScriptExtension

Příklady

Použití více skriptů

Tento příklad používá k sestavení serveru tři skripty. Vlastnost commandToExecute volá první skript. Pak máte možnosti, jak se ostatní volají. Můžete mít například skript potenciálního zákazníka, který řídí provádění se správným zpracováním chyb, protokolováním a správou stavu. Skripty se stáhnou do místního počítače, který se má spustit.

Například v 1_Add_Tools.ps1 byste volali 2_Add_Features.ps1 přidáním .\2_Add_Features.ps1 do skriptu. Opakujte tento proces pro ostatní skripty, které definujete v $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;

V tomto příkladu můžete pro umístění skriptu použít místní server SMB (Server Message Block). Pak nemusíte zadávat žádná další nastavení s výjimkou 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

Spuštění vlastního skriptu více než jednou pomocí rozhraní příkazového řádku

Obslužná rutina rozšíření vlastních skriptů zabraňuje opětovnému spuštění skriptu, pokud byla předána stejná nastavení. Toto chování zabraňuje náhodnému opětovnému spuštění, což může způsobit neočekávané chování, pokud skript není idempotentní. Pokud chcete ověřit, jestli obslužná rutina zablokovala opakování, podívejte se na C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*. Hledáte upozornění podobné tomuto:

Current sequence number, <SequenceNumber>, is not greater than the sequence number
of the most recently executed configuration. Exiting...

Pokud chcete rozšíření vlastních skriptů spustit více než jednou, můžete to provést pouze za těchto podmínek:

Parametr rozšíření Name je stejný jako předchozí nasazení rozšíření.
Aktualizovali jste konfiguraci. Do příkazu můžete přidat dynamickou vlastnost, například časové razítko. Pokud obslužná rutina zjistí změnu v nastavení konfigurace, považuje ji za explicitní potřebu znovu spustit skript.

Případně můžete vlastnost ForceUpdateTag nastavit na truehodnotu .

Použití invoke-WebRequest

Pokud ve skriptu používáte Invoke-WebRequest , musíte zadat parametr -UseBasicParsing. Pokud parametr nezadáte, při kontrole podrobného stavu se zobrazí následující chyba:

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

Pokud nasadíte rozšíření vlastních skriptů z webu Azure Portal, nemáte kontrolu nad vypršením platnosti tokenu SAS pro přístup ke skriptu ve vašem účtu úložiště. Počáteční nasazení funguje, ale když vyprší platnost tokenu SAS účtu úložiště, všechny následné operace škálování selžou, protože rozšíření vlastních skriptů už nemá přístup k účtu úložiště.

Při nasazování rozšíření vlastních skriptů do škálovací sady virtuálních počítačů doporučujeme použít PowerShell, Azure CLI nebo šablonu Azure Resource Manageru. Tímto způsobem se můžete rozhodnout použít spravovanou identitu nebo mít přímou kontrolu nad vypršením platnosti tokenu SAS pro přístup ke skriptu v účtu úložiště, pokud potřebujete.

Řešení potíží a podpora

Data o stavu nasazení rozšíření můžete načíst z webu Azure Portal a pomocí modulu Azure PowerShellu. Pokud chcete zobrazit stav nasazení rozšíření pro virtuální počítač, spusťte následující příkaz:

Get-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -VMName <vmName> -Name myExtensionName

Výstup rozšíření se protokoluje do souborů nalezených v následující složce na cílovém virtuálním počítači:

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

Zadané soubory se stáhnou do následující složky na cílovém virtuálním počítači:

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

V předchozí cestě je desetinné celé číslo, <n> které se může změnit mezi spuštěními rozšíření. Hodnota 1.* odpovídá skutečné, aktuální typeHandlerVersion hodnotě rozšíření. Například skutečný adresář může být C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

Když spustíte commandToExecute příkaz, rozšíření nastaví tento adresář, ...\Downloads\2například , jako aktuální pracovní adresář. Tento proces umožňuje použití relativních cest k vyhledání souborů stažených pomocí fileURIs vlastnosti. Tady jsou příklady stažených souborů:

Identifikátor URI v `fileUris`	Relativní umístění stahování	Absolutní umístění stahování
`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`

Absolutní cesty k adresářům se v průběhu životnosti virtuálního počítače mění, ale ne v rámci jediného spuštění rozšíření vlastních skriptů.

Vzhledem k tomu, že absolutní cesta ke stažení se může v průběhu času lišit, je lepší zvolit relativní skript nebo cesty k souborům v commandToExecute řetězci, kdykoli je to možné. Příklad:

"commandToExecute": "powershell.exe . . . -File \"./scripts/myscript.ps1\""

Informace o cestě po prvním segmentu identifikátoru URI se uchovávají pro soubory stažené pomocí fileUris seznamu vlastností. Jak je znázorněno v předchozí tabulce, stažené soubory se mapují do podadresářů pro stahování tak, aby odrážely strukturu fileUris hodnot.

Technická podpora

Pokud potřebujete pomoc s jakoukoli částí tohoto článku, obraťte se na odborníky na Azure na podporu komunity Azure.
Pokud chcete vytvořit podpora Azure incident, přejděte na web podpora Azure a vyberte Získat podporu.
Informace o používání podpora Azure najdete v nejčastějších dotazech k Microsoftu podpora Azure.

Rozšíření vlastních skriptů pro virtuální počítače

Požadavky

Podporované operační systémy Windows

Umístění skriptu

Připojení k internetu

Tipy

Schéma rozšíření

Hodnoty vlastností

Podrobnosti o hodnotě vlastnosti

Vlastnost: managedIdentity

Nasazení šablon

Nasazení PowerShellu

Příklady

Použití více skriptů

Spouštění skriptů z místní sdílené složky

Spuštění vlastního skriptu více než jednou pomocí rozhraní příkazového řádku

Použití invoke-WebRequest

Virtual Machine Scale Sets

Řešení potíží a podpora

Technická podpora

Další materiály