Aangepaste scriptextensie voor Windows

Artikel
02/03/2024

Met de aangepaste scriptextensie worden scripts gedownload en uitgevoerd op virtuele Azure-machines (VM's). Gebruik deze extensie voor configuratie na implementatie, software-installatie of een andere configuratie- of beheertaak. U kunt scripts downloaden van Azure Storage of GitHub, of deze tijdens de extensieruntime aan Azure Portal verstrekken.

De aangepaste scriptextensie kan worden geïntegreerd met Azure Resource Manager-sjablonen. U kunt deze ook uitvoeren met behulp van de Azure CLI, Azure PowerShell, Azure Portal of de REST API van Azure Virtual Machines.

In dit artikel wordt beschreven hoe u de aangepaste scriptextensie gebruikt met behulp van de Azure PowerShell-module en Azure Resource Manager-sjablonen. Het biedt ook stappen voor probleemoplossing voor Windows-systemen.

Vereisten

Notitie

Gebruik de aangepaste scriptextensie niet om te worden uitgevoerd Update-AzVM met dezelfde VIRTUELE machine als de parameter. De extensie wacht op zichzelf.

Ondersteunde Windows-besturingssystemen

Windows-besturingssysteem	x64
Windows 10	Ondersteund
Windows 11	Ondersteund
Windows Server 2008 SP2	Ondersteund
Windows Server 2008 R2	Ondersteund
Windows Server 2012	Ondersteund
Windows Server 2012 R2	Ondersteund
Windows Server 2016	Ondersteund
Windows Server 2016 Core	Ondersteund
Windows Server 2019	Ondersteund
Windows Server 2019 Core	Ondersteund
Windows Server 2022	Ondersteund
Windows Server 2022 Core	Ondersteund

Scriptlocatie

U kunt de extensie instellen voor het gebruik van uw Azure Blob Storage-referenties, zodat deze toegang heeft tot Azure Blob Storage. De scriptlocatie kan overal zijn zolang de VM naar dat eindpunt kan worden gerouteerd, bijvoorbeeld GitHub of een interne bestandsserver.

Verbinding met internet

Als u een script extern wilt downloaden, zoals van GitHub of Azure Storage, moet u andere firewall- of netwerkbeveiligingsgroep (NSG)-poorten openen. Als uw script zich bijvoorbeeld in Azure Storage bevindt, kunt u toegang toestaan met Azure NSG-servicetags voor Storage.

De aangepaste scriptextensie heeft geen manier om certificaatvalidatie te omzeilen. Als u downloadt vanaf een beveiligde locatie met bijvoorbeeld een zelfondertekend certificaat, krijgt u mogelijk fouten zoals het externe certificaat is ongeldig volgens de validatieprocedure. Zorg ervoor dat het certificaat correct is geïnstalleerd in het archief vertrouwde basiscertificeringsinstanties op de virtuele machine.

Als uw script zich op een lokale server bevindt, moet u mogelijk nog steeds andere firewall- of NSG-poorten openen.

Tips

De uitvoer is beperkt tot de laatste 4096 bytes.
Door tekens goed te escapen, zorgt u ervoor dat tekenreeksen correct worden geparseerd. U hebt bijvoorbeeld altijd twee backslashes nodig om een enkele letterlijke backslash te ontsnappen bij het omgaan met bestandspaden. Voorbeeld: {"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
De meeste fouten voor deze extensie worden veroorzaakt door syntaxisfouten in het script. Controleer of het script foutloos wordt uitgevoerd. Plaats meer logboekregistratie in het script om het gemakkelijker te maken om fouten te vinden.
Schrijf scripts die idempotent zijn, zodat het systeem niet wordt gewijzigd als de scripts per ongeluk meer dan één keer worden uitgevoerd.
Zorg ervoor dat de scripts geen gebruikersinvoer nodig hebben wanneer ze worden uitgevoerd.
Het script mag 90 minuten worden uitgevoerd. Een langere periode resulteert in een mislukte inrichting van de extensie.
Plaats geen herstarts in het script. Deze actie veroorzaakt problemen met andere extensies die worden geïnstalleerd en de extensie blijft niet doorgaan na het opnieuw opstarten.
Als u een script hebt dat ervoor zorgt dat u opnieuw moet opstarten voordat u toepassingen installeert en scripts uitvoert, plant u het opnieuw opstarten met een Windows Scheduled Task of met hulpprogramma's zoals DSC-, Chef- of Puppet-extensies.
Voer geen script uit dat ervoor zorgt dat de VM-agent wordt gestopt of bijgewerkt. Het kan de extensie in een overgangsstatus laten en leiden tot een time-out.
De extensie voert een script slechts één keer uit. Als u bij elke keer opstarten een script wilt uitvoeren, gebruikt u de extensie om een Windows Scheduled Task te maken.
Als u wilt plannen wanneer een script wordt uitgevoerd, gebruikt u de extensie om een Windows Scheduled Task te maken.
Wanneer het script wordt uitgevoerd, ziet u alleen de extensiestatus overgang van Azure Portal of CLI. Als u meer statusupdates voor een actief script wilt, maakt u uw eigen oplossing.
De aangepaste scriptextensie biedt geen systeemeigen ondersteuning voor proxyservers. U kunt echter een hulpprogramma voor bestandsoverdracht, zoals Invoke-WebRequest, gebruiken dat ondersteuning biedt voor proxyservers in uw script.
Houd rekening met niet-standaard maplocaties waar uw scripts of opdrachten eventueel van gebruikmaken. Zorg voor logica om deze situatie aan te pakken.
De aangepaste scriptextensie wordt uitgevoerd onder het LocalSystem-account.
Als u van plan bent om de storageAccountName- en storageAccountKey- eigenschappen te gebruiken, moeten deze eigenschappen bij elkaar geplaatst zijn in protectedSettings.
U kunt slechts één versie van een extensie toepassen op de VM. Als u een tweede aangepast script wilt uitvoeren, kunt u de bestaande extensie bijwerken met een nieuwe configuratie. U kunt de aangepaste scriptextensie ook verwijderen en opnieuw met het bijgewerkte script toepassen.

Extensieschema

De configuratie van de aangepaste scriptextensie geeft zaken op zoals de scriptlocatie en de opdracht die moet worden uitgevoerd. U kunt deze configuratie opslaan in configuratiebestanden, deze opgeven op de opdrachtregel of opgeven in een Azure Resource Manager-sjabloon.

U kunt gevoelige gegevens opslaan in een beveiligde configuratie, die is versleuteld en alleen ontsleuteld in de virtuele machine. De beveiligde configuratie is handig wanneer de uitvoeringsopdracht geheimen bevat, zoals een wachtwoord of een SAS-bestand (Shared Access Signature). Hier volgt een voorbeeld:

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

Notitie

De managedIdentity eigenschap mag niet worden gebruikt in combinatie met de storageAccountName of storageAccountKey eigenschap.

Er kan slechts één versie van een extensie tegelijk op een VIRTUELE machine worden geïnstalleerd. Het opgeven van een aangepast script twee keer in dezelfde Azure Resource Manager-sjabloon voor dezelfde VIRTUELE machine mislukt.

U kunt dit schema in de VM-resource of als zelfstandige resource gebruiken. Als deze extensie wordt gebruikt als een zelfstandige resource in de Azure Resource Manager-sjabloon, moet de naam van de resource de indeling virtualMachineName/extensionName hebben.

Eigenschapswaarden

Naam	Waarde of voorbeeld	Gegevenstype
apiVersion	`2015-06-15`	datum
Publisher	`Microsoft.Compute`	tekenreeks
type	`CustomScriptExtension`	tekenreeks
typeHandlerVersion	`1.10`	int
fileUris	`https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1`	matrix
timestamp	`123456789`	32-bits geheel getal
commandToExecute	`powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1`	tekenreeks
storageAccountName	`examplestorageacct`	tekenreeks
storageAccountKey	`TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==`	tekenreeks
managedIdentity	`{ }`of `{ "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }{ "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }`	JSON-object

Notitie

Deze eigenschapsnamen zijn hoofdlettergevoelig. Gebruik de namen zoals hier wordt weergegeven om implementatieproblemen te voorkomen.

Details van eigenschapswaarde

Eigenschappen	Optioneel of vereist	DETAILS
fileUris	Optioneel	URL's voor bestanden die moeten worden gedownload. Als URL's bijvoorbeeld gevoelig zijn als ze sleutels bevatten, moet dit veld worden opgegeven in `protectedSettings`.
commandToExecute	Vereist	Het invoerpuntscript dat moet worden uitgevoerd. Gebruik deze eigenschap als uw opdracht geheimen bevat, zoals wachtwoorden of als uw bestands-URI's gevoelig zijn.
timestamp	Optioneel	Wijzig deze waarde alleen om een nieuwe uitvoering van het script te activeren. Een geheel getal is acceptabel, zolang deze verschilt van de vorige waarde.
storageAccountName	Optioneel	De naam van het opslagaccount. Als u opslagreferenties opgeeft, moeten alle `fileUris` waarden URL's zijn voor Azure-blobs.
storageAccountKey	Optioneel	De toegangssleutel van het opslagaccount.
managedIdentity	Optioneel	De beheerde identiteit voor het downloaden van bestanden. Geldige waarden zijn `clientId` (optioneel, tekenreeks), de client-id van de beheerde identiteit en `objectId` (optioneel, tekenreeks), de object-id van de beheerde identiteit.

Openbare instellingen worden in duidelijke tekst verzonden naar de virtuele machine waarop het script wordt uitgevoerd. Beveiligde instellingen worden versleuteld via een sleutel die alleen bekend is bij Azure en de VM. De instellingen worden opgeslagen op de virtuele machine terwijl ze zijn verzonden. Als de instellingen zijn versleuteld, worden ze opgeslagen op de virtuele machine. Het certificaat dat wordt gebruikt om de versleutelde waarden te ontsleutelen, wordt opgeslagen op de virtuele machine. Het certificaat wordt ook gebruikt voor het ontsleutelen van instellingen, indien nodig, tijdens runtime.

Het gebruik van openbare instellingen kan handig zijn voor foutopsporing, maar we raden u aan beveiligde instellingen te gebruiken.

U kunt de volgende waarden instellen in openbare of beveiligde instellingen. De extensie weigert configuraties waarbij deze waarden zijn ingesteld in zowel openbare als beveiligde instellingen.

commandToExecute
fileUris

Eigenschap: managedIdentity

Notitie

Deze eigenschap moet alleen worden opgegeven in beveiligde instellingen.

De aangepaste scriptextensie, versie 1.10 en hoger, ondersteunt beheerde identiteiten voor het downloaden van bestanden uit URL's die zijn opgegeven in de fileUris instelling. Met de eigenschap kan de aangepaste scriptextensie toegang krijgen tot privé-blobs of containers van Azure Storage zonder dat de gebruiker geheimen moet doorgeven, zoals SAS-tokens of opslagaccountsleutels.

Als u deze functie wilt gebruiken, voegt u een door het systeem toegewezen of door de gebruiker toegewezen identiteit toe aan de VM of virtuele-machineschaalset waarop de aangepaste scriptextensie wordt uitgevoerd. Verdeel vervolgens de beheerde identiteit toegang tot de Azure Storage-container of -blob.

Als u de door het systeem toegewezen identiteit op de doel-VM of virtuele-machineschaalset wilt gebruiken, stelt u deze in managedidentity op een leeg JSON-object.

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

Als u de door de gebruiker toegewezen identiteit wilt gebruiken op de doel-VM of virtuele-machineschaalset, configureert u managedidentity deze met de client-id of de object-id van de beheerde identiteit.

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

Notitie

De managedIdentity eigenschap mag niet worden gebruikt in combinatie met de storageAccountName of storageAccountKey eigenschap.

Sjabloonimplementatie

U kunt Azure VM-extensies implementeren met behulp van Azure Resource Manager-sjablonen. Het JSON-schema dat in de vorige sectie wordt beschreven, kan worden gebruikt in een Azure Resource Manager-sjabloon om de aangepaste scriptextensie uit te voeren tijdens de implementatie van de sjabloon. In de volgende voorbeelden ziet u hoe u de aangepaste scriptextensie gebruikt:

PowerShell-implementatie

U kunt de Set-AzVMCustomScriptExtension opdracht gebruiken om de aangepaste scriptextensie toe te voegen aan een bestaande virtuele machine. Zie Set-AzVMCustomScriptExtension voor meer informatie.

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

Voorbeelden

Meerdere scripts gebruiken

In dit voorbeeld worden drie scripts gebruikt om uw server te bouwen. De commandToExecute eigenschap roept het eerste script aan. Vervolgens hebt u opties voor hoe de anderen worden aangeroepen. U kunt bijvoorbeeld een leadscript hebben waarmee de uitvoering wordt beheerd, met de juiste foutafhandeling, logboekregistratie en statusbeheer. De scripts worden gedownload naar de lokale computer die moet worden uitgevoerd.

In 1_Add_Tools.ps1 roept u bijvoorbeeld 2_Add_Features.ps1 aan door het script toe te voegen.\2_Add_Features.ps1. Herhaal dit proces voor de andere scripts die u in $settingsdefinieert.

$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;

In dit voorbeeld kunt u een lokale Server Message Block-server (SMB) gebruiken voor uw scriptlocatie. U hoeft dan geen andere instellingen op te geven, behalve 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

Een aangepast script meer dan één keer uitvoeren met behulp van de CLI

De handler voor aangepaste scriptextensie voorkomt dat een script opnieuw wordt uitgevoerd als dezelfde instellingen zijn doorgegeven. Dit gedrag voorkomt onbedoeld opnieuw uitvoeren, wat onverwacht gedrag kan veroorzaken als het script niet idempotent is. Als u wilt controleren of de handler de herrunning heeft geblokkeerd, bekijkt C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*u . Zoeken naar een waarschuwing zoals deze:

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

Als u de aangepaste scriptextensie meerdere keren wilt uitvoeren, kunt u dit alleen onder deze voorwaarden doen:

De parameter van Name de extensie is hetzelfde als de vorige implementatie van de extensie.
U hebt de configuratie bijgewerkt. U kunt een dynamische eigenschap toevoegen aan de opdracht, zoals een tijdstempel. Als de handler een wijziging in de configuratie-instellingen detecteert, wordt deze wijziging als expliciete wens beschouwd om het script opnieuw uit te voert.

U kunt de eigenschap ForceUpdateTag ook instellen op true.

Invoke-WebRequest gebruiken

Als u Invoke-WebRequest in uw script gebruikt, moet u de parameter -UseBasicParsingopgeven. Als u de parameter niet opgeeft, krijgt u de volgende fout bij het controleren van de gedetailleerde status:

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.

Virtuele-machineschaalsets

Als u de aangepaste scriptextensie implementeert vanuit Azure Portal, hebt u geen controle over het verlopen van het SAS-token voor toegang tot het script in uw opslagaccount. De eerste implementatie werkt, maar wanneer het SAS-token van het opslagaccount verloopt, mislukt elke volgende schaalbewerking omdat de aangepaste scriptextensie geen toegang meer heeft tot het opslagaccount.

U wordt aangeraden PowerShell, de Azure CLI of een Azure Resource Manager-sjabloon te gebruiken wanneer u de aangepaste scriptextensie implementeert op een virtuele-machineschaalset. Op deze manier kunt u ervoor kiezen om een beheerde identiteit te gebruiken of direct controle te hebben over de vervaldatum van het SAS-token voor toegang tot het script in uw opslagaccount, zolang u dat nodig hebt.

Problemen met en ondersteuning oplossen

U kunt gegevens ophalen over de status van extensie-implementaties vanuit Azure Portal en met behulp van de Azure PowerShell-module. Voer de volgende opdracht uit om de implementatiestatus van extensies voor een VIRTUELE machine te zien:

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

Extensie-uitvoer wordt vastgelegd in bestanden die worden gevonden in de volgende map op de virtuele doelmachine:

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

De opgegeven bestanden worden gedownload naar de volgende map op de virtuele doelmachine:

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

In het voorgaande pad <n> is een decimaal geheel getal dat kan veranderen tussen uitvoeringen van de extensie. De 1.* waarde komt overeen met de werkelijke, huidige typeHandlerVersion waarde van de extensie. De werkelijke map kan bijvoorbeeld zijn C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

Wanneer u de commandToExecute opdracht uitvoert, stelt de extensie deze map in, bijvoorbeeld als ...\Downloads\2de huidige werkmap. Met dit proces kan het gebruik van relatieve paden de bestanden vinden die zijn gedownload met behulp van de fileURIs eigenschap. Hier volgen voorbeelden van gedownloade bestanden:

URI in `fileUris`	Relatieve downloadlocatie	Absolute downloadlocatie
`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 absolute mappaden veranderen gedurende de levensduur van de virtuele machine, maar niet binnen één uitvoering van de aangepaste scriptextensie.

Omdat het absolute downloadpad na verloop van tijd kan variëren, is het beter om waar mogelijk relatieve script-/bestandspaden in de commandToExecute tekenreeks te kiezen. Voorbeeld:

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

Padinformatie na het eerste URI-segment wordt bewaard voor bestanden die worden gedownload met behulp van de fileUris eigenschappenlijst. Zoals wordt weergegeven in de eerdere tabel, worden gedownloade bestanden toegewezen aan downloadsubmappen om de structuur van de fileUris waarden weer te geven.

Ondersteuning

Als u hulp nodig hebt bij een deel van dit artikel, neemt u contact op met de Azure-experts bij de ondersteuning van de Azure-community.
Als u een ondersteuning voor Azure-incident wilt indienen, gaat u naar de ondersteuning voor Azure site en selecteert u Ondersteuning krijgen.
Lees de veelgestelde vragen over microsoft ondersteuning voor Azure voor informatie over het gebruik van ondersteuning voor Azure.

Aangepaste scriptextensie voor Windows

Vereisten

Ondersteunde Windows-besturingssystemen

Scriptlocatie

Verbinding met internet

Tips

Extensieschema

Eigenschapswaarden

Details van eigenschapswaarde

Eigenschap: managedIdentity

Sjabloonimplementatie

PowerShell-implementatie

Voorbeelden

Meerdere scripts gebruiken

Scripts uitvoeren vanaf een lokale share

Een aangepast script meer dan één keer uitvoeren met behulp van de CLI

Invoke-WebRequest gebruiken

Virtuele-machineschaalsets

Problemen met en ondersteuning oplossen

Ondersteuning

Aanvullende resources