Anpassat skripttillägg för Windows

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 ange dem till Azure Portal 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 Portal eller REST-API:et för Azure Virtual Machines.

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

Windows-operativsystem som 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 lagringsplatsen 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.

Råd

• Utdata är begränsade till de senaste 4 096 bytena.
• Att korrekt maskera tecken säkerställer 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. Något längre leder till ett misslyckat tillhandahållande 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. Ha logik för att hantera denna situation.
• Kontrollera att du inte har någon anpassad inställning i registernyckeln HKLM\SOFTWARE\Microsoft\Command Processor\AutoRun (beskrivs här). Detta skulle utlösas under installationen av tillägget för anpassat skript eller aktivera faser och orsaka ett fel som 'XYZ is not recognized as an internal or external command, operable program or batch file'.
• 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"
            ]
        }
    }
}

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

Information om egenskapsvärde

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

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 blobben.

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": "00001111-aaaa-2222-bbbb-3333cccc4444" }
}

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : { "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" }
}

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:

• Distribuera tillägg för virtuella datorer med Azure Resource Manager-mallar
• Distribuera tvånivåprogram i Windows och Azure SQL Database

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 valmöjligheter för hur de andra kallas. Du kan till exempel ha ett huvudskript 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 upprepningen genom att kontrollera C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*. Söker efter en varning liknande denna:

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.

Skalningsuppsättningar för virtuella maskiner

Om du distribuerar tillägget för anpassat skript från Azure Portal 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 stöd

Du kan hämta data om tillståndet för tilläggsdistributioner från Azure Portal 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 den föregående sökvägen är <n> ett decimalt heltal 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:

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 det första URI-segmentet behålls för filer som laddas ned genom att använda egenskapslistan fileUris. Som du ser i den tidigare tabellen mappas nedladdade filer till underkataloger för nedladdning för att återspegla värdenas fileUris struktur.

Stöd

• Om du behöver hjälp med någon del av den här artikeln kontaktar du Azure-experterna på Azure Community Support.

• Om du vill skicka en Azure Support incident går du till webbplatsen Azure Support och väljer Hämta support.

• Information om hur du använder Azure Support finns i Vanliga frågor och svar om Microsoft Azure Support.