Anpassat skripttillägg för Windows

  • Artikel

Tillägget för anpassat skript laddar ned och kör skript på virtuella Azure-datorer (VM). Använd det här tillägget för konfiguration efter distribution, programvaruinstallation eller någon annan konfigurations- eller hanteringsuppgift. Du kan ladda ned skript från Azure Storage eller GitHub eller tillhandahålla dem till Azure-portalen vid tilläggskörning.

Tillägget för anpassade skript integreras med Azure Resource Manager-mallar. Du kan också köra den med hjälp av Azure CLI, Azure PowerShell, Azure-portalen eller REST-API:et för Virtuella Azure-datorer.

Den här artikeln beskriver hur du använder tillägget för anpassat skript med hjälp av Azure PowerShell-modulen och Azure Resource Manager-mallar. Den innehåller även felsökningssteg för Windows-system.

Förutsättningar

Kommentar

Använd inte tillägget för anpassat skript för att köra Update-AzVM med samma virtuella dator som parametern . Tillägget väntar på sig självt.

Windows-operativsystem som stöds

Windows OS x64
Windows 10 Stöds
Windows 11 Stöds
Windows Server 2008 SP2 Stöds
Windows Server 2008 R2 Stöds
Windows Server 2012 Stöds
Windows Server 2012 R2 Stöds
Windows Server 2016 Stöds
Windows Server 2016 Core Stöds
Windows Server 2019 Stöds
Windows Server 2019 Core Stöds
Windows Server 2022 Stöds
Windows Server 2022 Core Stöds

Skriptplats

Du kan konfigurera tillägget så att det använder dina Azure Blob Storage-inloggningsuppgifter för att få tillgång till Azure Blob Storage. Skriptplatsen kan vara var som helst, förutsatt att den virtuella datorn kan dirigera trafik till den slutpunkten, till exempel GitHub eller en intern filserver.

Internet-anslutning

Om du vill ladda ned ett skript externt, till exempel från GitHub eller Azure Storage, måste du öppna andra portar i brandväggen eller i nätverkssäkerhetsgruppen (NSG). Om skriptet till exempel finns i Azure Storage kan du tillåta åtkomst med hjälp av Azure NSG tjänsttaggar för Storage.

Det anpassade skripttillägget kan inte kringgå certifikatverifieringen. Om du laddar ned från en säker plats med till exempel ett självsignerat certifikat kan du få fel som fjärrcertifikatet är ogiltigt enligt valideringsproceduren. Kontrollera att certifikatet är korrekt installerat i arkivet Betrodda rotcertifikatutfärdare på den virtuella datorn.

Om skriptet finns på en lokal server kan du fortfarande behöva öppna andra brandväggar eller NSG-portar.

Tips

  • Utdata är begränsade till de senaste 4 096 bytena.
  • Om du tar emot tecken på rätt sätt kan du se till att strängarna parsas korrekt. Du behöver till exempel alltid två omvänt snedstreck för att undvika ett enda literalt omvänt snedstreck när du hanterar filsökvägar. Exempel: {"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
  • Den högsta felfrekvensen för det här tillägget beror på syntaxfel i skriptet. Kontrollera att skriptet körs utan fel. Lägg till mer loggning i skriptet för att underlätta identifiering av fel.
  • Skriv idempotenta skript, så att att det inte orsakar förändringar i systemet om du kör dem flera gånger oavsiktligt.
  • Se till att skripten inte kräver indata från användaren när de körs.
  • Skriptet kan köras i 90 minuter. Sedan misslyckas etableringen av tillägget.
  • Placera inte omstarter i skriptet. Denna åtgärd orsakar problem med andra tillägg som installeras och tillägget fortsätter inte efter omstarten.
  • Om du har ett skript som orsakar en omstart innan du installerar program och kör skript schemalägger du omstarten med hjälp av en schemalagd Windows-aktivitet eller med verktyg som DSC-, Chef- eller Puppet-tillägg.
  • Kör inte ett skript som orsakar ett stopp eller en uppdatering av VM-agenten. Det kan lämna tillägget i ett övergångstillstånd och leda till en timeout.
  • Tillägget kör bara ett skript en gång. Om du vill köra ett skript vid varje start använder du tillägget för att skapa en schemalagd Windows-aktivitet.
  • Om du vill schemalägga när ett skript ska köras använder du tillägget för att skapa en schemalagd Windows-aktivitet.
  • När skriptet körs visas endast tilläggsstatusen övergång i Azure-portalen eller i Azure CLI. Om du behöver mer frekventa statusuppdateringar för ett skript som körs skapar du en egen lösning.
  • Tillägget för anpassat skript har inte inbyggt stöd för proxyservrar. Du kan dock använda ett filöverföringsverktyg, t.ex. Invoke-WebRequest, som stöder proxyservrar i skriptet.
  • Kontrollera om dina skript eller kommandon använder andra katalogplatser än standardplatserna. I så fall måste du ha logik som hanterar detta.
  • Tillägget för anpassat skript körs under LocalSystem-kontot.
  • Om du planerar att använda egenskaperna storageAccountName och storageAccountKey måste dessa egenskaper vara indelade i protectedSettings.
  • Du kan bara ha en version av ett tillägg som tillämpas på den virtuella datorn. Om du vill köra ett andra anpassat skript kan du uppdatera det befintliga tillägget med en ny konfiguration. Alternativt kan du ta bort tillägget för anpassat skript och återanvända det med det uppdaterade skriptet

Tilläggsschema

Konfigurationen för anpassat skripttillägg anger saker som skriptplats och kommandot som ska köras. Du kan lagra den här konfigurationen i konfigurationsfiler, ange den på kommandoraden eller ange den i en Azure Resource Manager-mall.

Du kan lagra känsliga data i en skyddad konfiguration, som är krypterad och endast dekrypterad i den virtuella datorn. Den skyddade konfigurationen är användbar när körningskommandot innehåller hemligheter som ett lösenord eller en sas-filreferens (signatur för delad åtkomst). Här är ett exempel:

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

Kommentar

Egenskapen managedIdentityfår inte användas tillsammans med storageAccountName egenskapen eller storageAccountKey .

Endast en version av ett tillägg kan installeras på en virtuell dator i taget. Det går inte att ange ett anpassat skript två gånger i samma Azure Resource Manager-mall för samma virtuella dator.

Du kan använda det här schemat i den virtuella datorresursen eller som en fristående resurs. Om det här tillägget används som en fristående resurs i Azure Resource Manager-mallen måste namnet på resursen vara i formatet virtualMachineName/extensionName.

Egenskapsvärden

Name Värde eller exempel Datatyp
apiVersion 2015-06-15 datum
Publisher Microsoft.Compute sträng
type CustomScriptExtension sträng
typeHandlerVersion 1.10 heltal
fileUris https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 matris
timestamp 123456789 32-bitars heltal
commandToExecute powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 sträng
storageAccountName examplestorageacct sträng
storageAccountKey TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== sträng
managedIdentity { }eller { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }{ "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" } JSON-objekt

Kommentar

Dessa egenskapsnamn är skiftlägeskänsliga. Undvik distributionsproblem genom att använda namnen som visas här.

Information om egenskapsvärde

Property Valfritt eller obligatoriskt Details
fileUris Valfritt URL:er för filer som ska laddas ned. Om URL:er är känsliga, till exempel om de innehåller nycklar, bör det här fältet anges i protectedSettings.
commandToExecute Obligatoriskt Startpunktsskriptet som ska köras. Använd den här egenskapen om kommandot innehåller hemligheter som lösenord eller om dina fil-URI:er är känsliga.
timestamp Valfritt Ändra endast det här värdet för att utlösa en omkörning av skriptet. Ett heltalsvärde är acceptabelt, så länge det skiljer sig från det tidigare värdet.
storageAccountName Valfritt Namnet på lagringskontot. Om du anger autentiseringsuppgifter för lagring måste alla fileUris värden vara URL:er för Azure-blobar.
storageAccountKey Valfritt Åtkomstnyckeln för lagringskontot.
managedIdentity Valfritt Den hanterade identiteten för nedladdning av filer. Giltiga värden är clientId (valfritt, sträng), vilket är klient-ID för den hanterade identiteten och objectId (valfritt, sträng), vilket är objekt-ID för den hanterade identiteten.

Offentliga inställningar skickas i klartext till den virtuella dator där skriptet körs. Skyddade inställningar krypteras via en nyckel som endast är känd för Azure och den virtuella datorn. Inställningarna sparas på den virtuella datorn när de skickades. Om inställningarna krypterades sparas de alltså krypterade på den virtuella datorn. Certifikatet som används för att dekryptera de krypterade värdena lagras på den virtuella datorn. Certifikatet används också för att dekryptera inställningar vid behov vid körning.

Det kan vara användbart att använda offentliga inställningar för felsökning, men vi rekommenderar att du använder skyddade inställningar.

Du kan ange följande värden i offentliga eller skyddade inställningar. Tillägget avvisar alla konfigurationer där dessa värden anges i både offentliga och skyddade inställningar.

  • commandToExecute
  • fileUris

Egenskap: managedIdentity

Kommentar

Den här egenskapen måste endast anges i skyddade inställningar.

Tillägget för anpassade skript, version 1.10 och senare, stöder hanterade identiteter för nedladdning av filer från URL:er som anges i inställningen fileUris . Egenskapen gör att tillägget för anpassat skript kan komma åt privata Azure Storage-blobbar eller containrar utan att användaren behöver skicka hemligheter som SAS-token eller lagringskontonycklar.

Om du vill använda den här funktionen lägger du till en systemtilldelad eller användartilldelad identitet till den virtuella datorn eller vm-skalningsuppsättningen där det anpassade skripttillägget körs. Bevilja sedan den hanterade identiteten åtkomst till Azure Storage-containern eller bloben.

Om du vill använda den systemtilldelade identiteten på den virtuella måldatorn eller VM-skalningsuppsättningen anger du managedidentity till ett tomt JSON-objekt.

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

Om du vill använda den användartilldelade identiteten på den virtuella måldatorn eller VM-skalningsuppsättningen konfigurerar managedidentity du med klient-ID:t eller objekt-ID:t för den hanterade identiteten.

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

Kommentar

Egenskapen managedIdentityfår inte användas tillsammans med storageAccountName egenskapen eller storageAccountKey .

Malldistribution

Du kan distribuera Azure VM-tillägg med hjälp av Azure Resource Manager-mallar. JSON-schemat som beskrivs i föregående avsnitt kan användas i en Azure Resource Manager-mall för att köra tillägget för anpassat skript under mallens distribution. Följande exempel visar hur du använder tillägget för anpassat skript:

PowerShell-distribution

Du kan använda Set-AzVMCustomScriptExtension kommandot för att lägga till tillägget för anpassat skript till en befintlig virtuell dator. Mer information finns i Set-AzVMCustomScriptExtension.

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

Exempel

Använda flera skript

I det här exemplet används tre skript för att skapa servern. Egenskapen commandToExecute anropar det första skriptet. Sedan har du alternativ för hur de andra anropas. Du kan till exempel ha ett leadskript som styr körningen med rätt felhantering, loggning och tillståndshantering. Skripten laddas ned till den lokala datorn som ska köras.

I 1_Add_Tools.ps1 anropar du till exempel 2_Add_Features.ps1 genom att lägga .\2_Add_Features.ps1 till i skriptet. Upprepa den här processen för de andra skript som du definierar i $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;

Köra skript från en lokal resurs

I det här exemplet kanske du vill använda en lokal SMB-server (Server Message Block) för skriptplatsen. Sedan behöver du inte ange några andra inställningar, förutom 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

Köra ett anpassat skript mer än en gång med hjälp av CLI

Hanteraren för anpassat skripttillägg förhindrar att ett skript körs igen om exakt samma inställningar har skickats. Det här beteendet förhindrar oavsiktlig omkörning, vilket kan orsaka oväntade beteenden om skriptet inte är idempotent. Kontrollera om hanteraren blockerade omkörningen genom att titta på C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*. Söker efter en varning som den här:

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

Om du vill köra tillägget för anpassat skript mer än en gång kan du bara göra det under följande villkor:

  • Tilläggets Name parameter är samma som den tidigare distributionen av tillägget.
  • Du har uppdaterat konfigurationen. Du kan lägga till en dynamisk egenskap i kommandot, till exempel en tidsstämpel. Om hanteraren identifierar en ändring i konfigurationsinställningarna anser den att ändringen är en uttrycklig önskan att köra skriptet igen.

Du kan också ange egenskapen ForceUpdateTag till true.

Använda Invoke-WebRequest

Om du använder Invoke-WebRequest i skriptet måste du ange parametern -UseBasicParsing. Om du inte anger parametern får du följande fel när du kontrollerar den detaljerade statusen:

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

Om du distribuerar tillägget för anpassade skript från Azure-portalen har du inte kontroll över förfallodatumet för SAS-token för åtkomst till skriptet i ditt lagringskonto. Den inledande distributionen fungerar, men när lagringskontots SAS-token upphör att gälla misslyckas alla efterföljande skalningsåtgärder eftersom det anpassade skripttillägget inte längre kan komma åt lagringskontot.

Vi rekommenderar att du använder PowerShell, Azure CLI eller en Azure Resource Manager-mall när du distribuerar tillägget för anpassade skript på en VM-skalningsuppsättning. På så sätt kan du välja att använda en hanterad identitet eller ha direkt kontroll över förfallodatumet för SAS-token för åtkomst till skriptet i ditt lagringskonto så länge du behöver.

Felsökning och support

Du kan hämta data om tillståndet för tilläggsdistributioner från Azure-portalen och med hjälp av Azure PowerShell-modulen. Kör följande kommando för att se distributionstillståndet för tillägg för en virtuell dator:

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

Tilläggsutdata loggas till filer som finns under följande mapp på den virtuella måldatorn:

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

De angivna filerna laddas ned till följande mapp på den virtuella måldatorn:

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

I föregående sökväg <n> finns ett decimaltal som kan ändras mellan körningar av tillägget. Värdet 1.* matchar det faktiska aktuella typeHandlerVersion värdet för tillägget. Den faktiska katalogen kan till exempel vara C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

När du kör commandToExecute kommandot anger tillägget den här katalogen, ...\Downloads\2till exempel , som den aktuella arbetskatalogen. Med den här processen kan du använda relativa sökvägar för att hitta de filer som laddas ned med hjälp fileURIs av egenskapen . Här är exempel på nedladdade filer:

URI i fileUris Relativ nedladdningsplats Absolut nedladdningsplats
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

De absoluta katalogsökvägarna ändras under den virtuella datorns livslängd, men inte inom en enda körning av tillägget för anpassat skript.

Eftersom den absoluta nedladdningsvägen kan variera över tid är det bättre att välja relativa skript-/filsökvägar i strängen commandToExecute när det är möjligt. Till exempel:

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

Sökvägsinformation efter att det första URI-segmentet sparats för filer som laddats ned med hjälp fileUris av egenskapslistan. Som du ser i den tidigare tabellen mappas nedladdade filer till underkataloger för nedladdning för att återspegla värdenas fileUris struktur.

Support