Aangepaste scriptextensie voor Windows

Artikel
08/08/2022
12 minuten om te lezen

Met de aangepaste scriptextensie worden scripts gedownload en uitgevoerd op virtuele Azure-machines (VM's). Deze extensie is handig 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 de Azure Portal geven.

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

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 VM als de parameter, omdat deze wacht op zichzelf.

Besturingssysteem

De aangepaste scriptextensie voor Windows wordt uitgevoerd op deze ondersteunde besturingssystemen:

Windows Server 2008 R2
Windows Server 2012
Windows Server 2012 R2
Windows 10
Windows Server 2016
Windows Server 2016 Core
Windows Server 2019
Windows Server 2019 Core
Windows Server 2022
Windows Server 2022 Core
Windows 11

Scriptlocatie

U kunt de extensie instellen om uw Azure Blob Storage referenties te gebruiken, 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).

Internetconnectiviteit

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

De aangepaste scriptextensie heeft geen manier om certificaatvalidatie te omzeilen. Dus 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 extra firewall- of NSG-poorten openen.

Tips en trucs

De meeste fouten voor deze extensie worden veroorzaakt door syntaxisfouten in het script. Test of het script zonder fouten wordt uitgevoerd. Plaats extra logboekregistratie in het script om fouten gemakkelijker te vinden.
Schrijf scripts die idempotent zijn, zodat het uitvoeren van scripts meerdere keren per ongeluk geen systeemwijzigingen veroorzaakt.
Zorg ervoor dat de scripts geen gebruikersinvoer nodig hebben wanneer ze worden uitgevoerd.
Het script mag 90 minuten worden uitgevoerd. Een langere periode leidt tot een mislukte inrichting van de extensie.
Voeg geen opdrachten voor opnieuw opstarten aan het script toe. Deze actie veroorzaakt problemen met andere extensies die worden geïnstalleerd en de extensie wordt niet voortgezet na het opnieuw opstarten.
Als u een script hebt dat een herstart veroorzaakt voordat u toepassingen installeert en scripts uitvoert, plant u het opnieuw opstarten met behulp van een geplande Windows-taak of met behulp van hulpprogramma's zoals DSC-, Chef- of Puppet-extensies.
Voer geen script uit waardoor de VM-agent wordt gestopt of bijgewerkt. Het kan de extensie in een overgangsstatus laten staan en leiden tot een time-out.
Met de extensie wordt slechts eenmaal een script uitgevoerd. Als u bij elk opstarten een script wilt uitvoeren, gebruikt u de extensie om een geplande Windows-taak te maken.
Als u wilt plannen wanneer een script wordt uitgevoerd, gebruikt u de extensie om een geplande Windows-taak te maken.
Wanneer het script wordt uitgevoerd, ziet u alleen de extensiestatus 'overgang' vanuit de Azure Portal of CLI. Als u vaker statusupdates voor een actief script wilt uitvoeren, moet u uw eigen oplossing maken.
De aangepaste scriptextensie biedt geen systeemeigen ondersteuning voor proxyservers. U kunt echter een hulpprogramma voor bestandsoverdracht gebruiken dat proxyservers in uw script ondersteunt, zoals Invoke-WebRequest.
Houd rekening met niet-standaardmaplocaties waarop uw scripts of opdrachten mogelijk afhankelijk zijn. 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 worden gekoppeld aan protectedSettings.

Extensieschema

De configuratie van de aangepaste scriptextensie geeft zaken op zoals 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 wordt ontsleuteld binnen de virtuele machine. De beveiligde configuratie is handig wanneer de uitvoeringsopdracht geheimen bevat, zoals een wachtwoord of sas-bestandsreferentie (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 eigenschap of storageAccountKey eigenschap.

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

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

Eigenschapswaarden

Name	Waarde of voorbeeld	Gegevenstype
`apiVersion`	`2015-06-15`	date
`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

Eigenschap	Optioneel of vereist	Details
`fileUris`	Optioneel	URL's voor bestanden die moeten worden gedownload. Als URL's gevoelig zijn (bijvoorbeeld 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: `clientId` (optioneel, tekenreeks): de client-id van de beheerde identiteit. `objectId` (optioneel, tekenreeks): de object-id van de beheerde identiteit.

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

commandToExecute
fileUris

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

Openbare instellingen worden verzonden in duidelijke tekst naar de VM 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 op de VIRTUELE machine opgeslagen. Het certificaat wordt ook gebruikt voor het ontsleutelen van instellingen (indien nodig) tijdens runtime.

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. Hiermee heeft de aangepaste scriptextensie toegang tot persoonlijke Azure Storage-blobs of containers zonder dat de gebruiker geheimen moet doorgeven, zoals SAS-tokens of opslagaccountsleutels.

Als u deze functie wilt gebruiken, moet de gebruiker een door het systeem toegewezen of door de gebruiker toegewezen identiteit toevoegen aan de VM of virtuele-machineschaalset waarop de aangepaste scriptextensie naar verwachting wordt uitgevoerd. De gebruiker moet vervolgens de beheerde identiteit toegang verlenen 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.

Voorbeeld:

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

Voorbeelden:

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

Aanvullende voorbeelden

Meerdere scripts gebruiken

In dit voorbeeld gebruikt u drie scripts 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 hoofdscript hebben waarmee de uitvoering wordt beheerd, met de juiste foutafhandeling, logboekregistratie en statusbeheer. De scripts worden gedownload naar de lokale computer voor uitvoering.

In 1_Add_Tools.ps1roept u bijvoorbeeld 2_Add_Features.ps1 aan door het script toe te voegen .\2_Add_Features.ps1 . U herhaalt 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 wilt u mogelijk een lokale SMB-server (Server Message Block) 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. U kunt controleren of de handler het opnieuw uitvoeren heeft geblokkeerd door te kijken naar C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension<HandlerVersion>\CustomScriptHandler.log en een waarschuwing zoals deze te zoeken:

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 om het script opnieuw uit te proberen.

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 de Azure Portal, hebt u geen controle over het verlopen van het SAS-token voor toegang tot het script in uw opslagaccount. Het resultaat is dat 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 directe controle te hebben over de vervaldatum van het SAS-token voor toegang tot het script in uw opslagaccount zolang u dat nodig hebt.

Problemen oplossen en ondersteuning

U kunt gegevens ophalen over de status van extensie-implementaties uit de Azure Portal en met behulp van de module Azure PowerShell. 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 zijn 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 (bijvoorbeeld ...\Downloads\2) in als de huidige werkmap. Met dit proces kan het gebruik van relatieve paden de bestanden vinden die via de fileURIs eigenschap zijn gedownload. 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 in de loop van de tijd kan variëren, is het beter om waar mogelijk te kiezen voor relatieve script-/bestandspaden in de commandToExecute tekenreeks. Bijvoorbeeld:

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

Padinformatie na het eerste URI-segment wordt bewaard voor bestanden die worden gedownload via 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, kunt u contact opnemen met de Azure-experts bij de ondersteuning van de Azure-community.

U kunt ook een ondersteuning voor Azure incident maken. Ga naar de ondersteuning voor Azure site en selecteer 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

Besturingssysteem

Scriptlocatie

Internetconnectiviteit

Tips en trucs

Extensieschema

Eigenschapswaarden

Details van eigenschapswaarde

Eigenschap: managedIdentity

Sjabloonimplementatie

PowerShell-implementatie

Aanvullende 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 oplossen en ondersteuning

Ondersteuning