Egyéniszkript-bővítmény Windows rendszerre

  • Cikk

Az egyéni szkriptbővítmény szkripteket tölt le és futtat azure-beli virtuális gépeken. Ezt a bővítményt az üzembe helyezés utáni konfigurációhoz, a szoftvertelepítéshez vagy bármely más konfigurációs vagy felügyeleti feladathoz használhatja. Letöltheti a szkripteket az Azure Storage-ból vagy a GitHubról, vagy a bővítmény futtatókörnyezetében az Azure Portalra is elküldheti őket.

Az egyéni szkriptbővítmény integrálható az Azure Resource Manager-sablonokkal. Futtathatja az Azure CLI, az Azure PowerShell, az Azure Portal vagy az Azure Virtual Machines REST API használatával is.

Ez a cikk azt ismerteti, hogyan használhatja az egyéni szkriptbővítményt az Azure PowerShell-modul és az Azure Resource Manager-sablonok használatával. A windowsos rendszerek hibaelhárítási lépéseit is tartalmazza.

Előfeltételek

Feljegyzés

Ne használja az egyéni szkriptbővítményt a paraméterével megegyező virtuális géppel való futtatáshoz Update-AzVM . A bővítmény várni fog magára.

Támogatott windowsos operációs rendszerek

Windows operációs rendszer x64
Windows 10 rendszer esetén Támogatott
Windows 11 Támogatott
Windows Server 2008 SP2 Támogatott
Windows Server 2008 R2 Támogatott
Windows Server 2012, Támogatott
Windows Server 2012 R2 Támogatott
Windows Server 2016 Támogatott
Windows Server 2016 Core Támogatott
Windows Server 2019 Támogatott
Windows Server 2019 Core Támogatott
Windows Server 2022 Támogatott
Windows Server 2022 Core Támogatott

Szkript helye

Beállíthatja, hogy a bővítmény az Azure Blob Storage hitelesítő adatait használja, hogy hozzáférhessen az Azure Blob Storage-hoz. A szkript helye bárhol lehet, amíg a virtuális gép erre a végpontra tud irányítani, például a GitHubra vagy egy belső fájlkiszolgálóra.

Internetkapcsolat

Ha külsőleg szeretne letölteni egy szkriptet, például a GitHubról vagy az Azure Storage-ból, meg kell nyitnia más tűzfal- vagy hálózati biztonsági csoport (NSG) portokat. Ha például a szkript az Azure Storage-ban található, engedélyezheti a hozzáférést a Storage Azure NSG-szolgáltatáscímkék használatával.

Az egyéni szkriptbővítmény nem tudja megkerülni a tanúsítványérvényesítést. Ha biztonságos helyről tölt le például egy önaláírt tanúsítványt, olyan hibákat kaphat, mint például a távoli tanúsítvány érvénytelen az érvényesítési eljárás szerint. Győződjön meg arról, hogy a tanúsítvány megfelelően van telepítve a virtuális gépen található megbízható legfelső szintű hitelesítésszolgáltatók tárolójában.

Ha a szkript helyi kiszolgálón található, előfordulhat, hogy más tűzfal- vagy NSG-portokat is meg kell nyitnia.

Tippek

  • A kimenet csak az utolsó 4096 bájtra korlátozódik.
  • A karakterek védőkarakterrel (escape) való feloldása segít a sztringek megfelelő elemzésében. A fájl elérési útjainak kezelésekor például mindig két fordított perjelre van szükség egyetlen literális fordított perjel feloldásához. Minta: {"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
  • A bővítmény meghibásodásai legnagyobb arányban a szkriptben található szintaktikai hibák miatt jelentkeznek. Ellenőrizze, hogy a szkript hiba nélkül fut-e. A hibák keresésének megkönnyítése érdekében további naplózást végezhet a szkriptbe.
  • Írjon olyan szkripteket, amelyek nem okoznak változásokat a rendszerben, hogy többszöri futtatásuk véletlenül se okozzon rendszerváltozást.
  • Gondoskodjon arról, hogy a szkriptek futtatásához ne legyen szükség felhasználói beavatkozásra.
  • A szkript 90 percig futhat. Ha egy szkript ennél tovább fut, az a bővítmény üzembe helyezésének a meghiúsulását eredményezi.
  • A szkript ne váltson ki újraindításokat. Ez a művelet problémákat okoz más telepített bővítményekkel kapcsolatban, és a bővítmény nem folytatódik az újraindítás után.
  • Ha egy szkript újraindítást vált ki az alkalmazások telepítése és a szkriptek futtatása előtt, ütemezze az újraindítást egy ütemezett Windows-feladattal, vagy olyan eszközökkel, mint a DSC, a Chef vagy a Puppet bővítmény.
  • Ne futtasson olyan szkriptet, amely a VM-ügynök leállítását vagy frissítését okozza. Előfordulhat, hogy a bővítmény átmeneti állapotban marad, és időtúllépéshez vezet.
  • A bővítmény egy szkriptet csak egyszer futtat. Ha egy szkriptet minden indításkor futtatni szeretne, hozzon létre egy ütemezett Windows-feladatot a bővítménnyel.
  • Ha ütemezni szeretné, hogy mikor fusson egy szkript, hozzon létre egy ütemezett Windows-feladatot a bővítménnyel.
  • Amikor a szkript fut, az Azure portálon vagy a CLI-n a bővítmény átmeneti állapotát fogja látni. Ha gyakoribb állapotfrissítést szeretne egy futó szkripthez, hozza létre a saját megoldását.
  • Az egyéni szkriptek futtatására szolgáló bővítmény nem biztosít natív támogatást a proxykiszolgálókhoz. Használhat azonban olyan fájlátviteli eszközt, például Invoke-WebRequest, amely támogatja a proxykiszolgálókat a szkriptben.
  • Vegye figyelembe, hogy vannak olyan nem alapértelmezett könyvtárhelyek, amelyekre a szkriptjei és a parancsai támaszkodhatnak. Alakítsa ki a helyzet kezeléséhez szükséges logikát.
  • Az egyéni szkriptbővítmény a LocalSystem fiók alatt fut.
  • Ha a(z) storageAccountName és storageAccountKey a tulajdonságokat szeretné használni, ezeket a tulajdonságokat a következőbe kell csoportosítaniprotectedSettings.
  • A bővítmények csak egy verzióját alkalmazhatja a virtuális gépre. Egy második egyéni szkript futtatásához frissítheti a meglévő bővítményt egy új konfigurációval. Másik lehetőségként eltávolíthatja az egyéni szkriptbővítményt, és újra alkalmazhatja a frissített szkripttel

Bővítményséma

Az egyéni szkriptbővítmény konfigurációja olyan dolgokat határoz meg, mint a szkript helye és a futtatandó parancs. Ezt a konfigurációt konfigurációs fájlokban tárolhatja, megadhatja a parancssorban, vagy megadhatja egy Azure Resource Manager-sablonban.

Bizalmas adatokat védett konfigurációban tárolhat, amely titkosítva van, és csak a virtuális gépen belül fejthető vissza. A védett konfiguráció akkor hasznos, ha a végrehajtási parancs olyan titkos kódokat tartalmaz, mint például a jelszó vagy a közös hozzáférésű jogosultságkód (SAS) fájlhivatkozása. Példa:

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

Feljegyzés

A managedIdentity tulajdonság nem használható a storageAccountNamestorageAccountKey tulajdonsággal együtt.

Egy bővítménynek egyszerre csak egy verziója telepíthető egy virtuális gépre. Ha ugyanazon virtuális géphez kétszer ad meg egyéni szkriptet ugyanabban az Azure Resource Manager-sablonban, az sikertelen.

Ezt a sémát a virtuálisgép-erőforráson belül vagy önálló erőforrásként is használhatja. Ha ezt a bővítményt önálló erőforrásként használják az Azure Resource Manager-sablonban, az erőforrás nevének virtualMachineName/extensionName formátumban kell lennie.

Tulajdonságértékek

Név Érték vagy példa Adattípus
apiVersion 2015-06-15 dátum:
Publisher Microsoft.Compute húr
típus CustomScriptExtension húr
typeHandlerVersion 1.10 egész
fileUris https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1 array
időbélyeg 123456789 32 bites egész szám
commandToExecute powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 húr
storageAccountName examplestorageacct húr
storageAccountKey TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg== húr
managedIdentity { }vagy { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }{ "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" } JSON-objektum

Feljegyzés

Ezek a tulajdonságnevek megkülönböztetik a kis- és nagybetűket. Az üzembe helyezési problémák elkerülése érdekében használja az itt látható neveket.

Tulajdonságérték részletei

Tulajdonság Nem kötelező vagy kötelező Részletek
fileUris Választható A letöltendő fájlok URL-címei. Ha az URL-címek bizalmasak, például kulcsokat tartalmaznak, ezt a mezőt meg kell adni a következőben protectedSettings: .
commandToExecute Szükséges A futtatandó belépési pont szkriptje. Ezt a tulajdonságot akkor használja, ha a parancs titkos kódokat, például jelszavakat tartalmaz, vagy ha a fájl URI-jai bizalmasak.
időbélyeg Választható Ezt az értéket csak úgy módosíthatja, hogy elindítsa a szkript újrafuttatását. Minden egész szám elfogadható, ha eltér az előző értéktől.
storageAccountName Választható A tárfiók neve. Ha tárolási hitelesítő adatokat ad meg, az összes fileUris értéknek URL-címnek kell lennie az Azure-blobokhoz.
storageAccountKey Választható A tárfiók hozzáférési kulcsa.
managedIdentity Választható A fájlok letöltéséhez használt felügyelt identitás . Az érvényes értékek clientId (nem kötelező, sztring), amely a felügyelt identitás ügyfél-azonosítója, és objectId (nem kötelező, sztring), amely a felügyelt identitás objektumazonosítója.

A nyilvános beállításokat a rendszer világos szövegben küldi el annak a virtuális gépnek, ahol a szkript fut. A védett beállítások titkosítva vannak egy olyan kulccsal, amely csak az Azure és a virtuális gép számára ismert. A rendszer az elküldött beállításokat a virtuális gépre menti. Vagyis ha a beállítások titkosítva lettek, a rendszer titkosítva menti őket a virtuális gépen. A titkosított értékek visszafejtéséhez használt tanúsítvány a virtuális gépen van tárolva. A tanúsítvány a beállítások futásidőben történő visszafejtésére is használható, ha szükséges.

A nyilvános beállítások használata hasznos lehet a hibakereséshez, de javasoljuk, hogy használjon védett beállításokat.

A következő értékeket nyilvános vagy védett beállításokban állíthatja be. A bővítmény elutasít minden olyan konfigurációt, amelyben ezek az értékek nyilvános és védett beállításokban is be vannak állítva.

  • commandToExecute
  • fileUris

Tulajdonság: managedIdentity

Feljegyzés

Ezt a tulajdonságot csak védett beállításokban kell megadni.

Az 1.10-es és újabb verziójú egyéni szkriptbővítmény támogatja a felügyelt identitásokat a fájloknak a fileUris beállításban megadott URL-címekről való letöltéséhez. A tulajdonság lehetővé teszi, hogy az egyéni szkriptbővítmény hozzáférjen az Azure Storage privát blobjaihoz vagy tárolóihoz anélkül, hogy a felhasználónak titkos kulcsokat, például SAS-jogkivonatokat vagy tárfiókkulcsokat kellene átadnia.

A funkció használatához adjon hozzá egy rendszer által hozzárendelt vagy felhasználó által hozzárendelt identitást ahhoz a virtuális géphez vagy virtuálisgép-méretezési csoporthoz, amelyen az egyéni szkriptbővítmény fut. Ezután adjon hozzáférést a felügyelt identitásnak az Azure Storage-tárolóhoz vagy -blobhoz.

Ha a cél virtuális gépen vagy virtuálisgép-méretezési csoportban a rendszer által hozzárendelt identitást szeretné használni, állítson be managedidentity egy üres JSON-objektumot.

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

Ha a felhasználó által hozzárendelt identitást szeretné használni a cél virtuális gépen vagy virtuálisgép-méretezési csoportban, konfigurálja managedidentity a felügyelt identitás ügyfél-azonosítójával vagy objektumazonosítójával.

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

Feljegyzés

A managedIdentity tulajdonság nem használható a storageAccountNamestorageAccountKey tulajdonsággal együtt.

Sablonalapú telepítés

Azure-beli virtuálisgép-bővítményeket Azure Resource Manager-sablonokkal helyezhet üzembe. Az előző szakaszban részletezett JSON-séma egy Azure Resource Manager-sablonban használható az egyéni szkriptbővítmény futtatásához a sablon üzembe helyezése során. Az alábbi minták az egyéni szkriptbővítmény használatát mutatják be:

A PowerShell telepítése

A parancs használatával Set-AzVMCustomScriptExtension hozzáadhatja az egyéni szkriptbővítményt egy meglévő virtuális géphez. További információ: Set-AzVMCustomScriptExtension.

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

Példák

Több szkript használata

Ez a példa három szkriptet használ a kiszolgáló létrehozásához. A commandToExecute tulajdonság meghívja az első szkriptet. Ezután lehetősége van arra, hogy a többieket meghívja. Létrehozhat például egy érdeklődőszkriptet, amely szabályozza a végrehajtást, a megfelelő hibakezeléssel, naplózással és állapotkezeléssel. A szkripteket a rendszer letölti a helyi gépre a futtatáshoz.

A 1_Add_Tools.ps1-ben például meghívhatja a 2_Add_Features.ps1-et a szkripthez való hozzáadással.\2_Add_Features.ps1. Ismételje meg ezt a folyamatot az ön által definiált többi szkript esetében $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;

Szkriptek futtatása helyi megosztásból

Ebben a példában érdemes lehet egy helyi kiszolgálói üzenetblokkoló (SMB) kiszolgálót használni a szkript helyéhez. Ezután nem kell más beállításokat megadnia, kivéve 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

Egyéni szkript többszöri futtatása a parancssori felület használatával

Az egyéni szkriptbővítmény-kezelő megakadályozza a szkriptek újrafuttatását, ha pontosan ugyanazokat a beállításokat adták meg. Ez a viselkedés megakadályozza a véletlen újrafuttatást, ami váratlan viselkedést okozhat, ha a szkript nem idempotens. Annak ellenőrzéséhez, hogy a kezelő letiltotta-e az újrafuttatást, tekintse meg a következőt C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*: . Az alábbihoz hasonló figyelmeztetés keresése:

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

Ha többször szeretné futtatni az egyéni szkriptbővítményt, ezt csak az alábbi feltételek mellett teheti meg:

  • A bővítmény paramétere Name megegyezik a bővítmény előző üzembe helyezésével.
  • Frissítette a konfigurációt. Dinamikus tulajdonságot is hozzáadhat a parancshoz, például időbélyeget. Ha a kezelő változást észlel a konfigurációs beállításokban, úgy véli, hogy a módosítás explicit szándék a szkript újrafuttatására.

Másik lehetőségként beállíthatja a ForceUpdateTag tulajdonságot true.

Az Invoke-WebRequest használata

Ha az Invoke-WebRequest parancsprogramot használja a szkriptben, meg kell adnia a paramétert-UseBasicParsing. Ha nem adja meg a paramétert, a részletes állapot ellenőrzésekor a következő hibaüzenet jelenik meg:

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

Ha az Egyéni szkriptbővítményt az Azure Portalról telepíti, akkor nem tudja szabályozni az SAS-jogkivonat lejáratát a tárfiókban lévő szkript eléréséhez. A kezdeti üzembe helyezés működik, de amikor a tárfiók SAS-jogkivonata lejár, minden további skálázási művelet meghiúsul, mert az egyéni szkriptbővítmény már nem fér hozzá a tárfiókhoz.

Javasoljuk, hogy a PowerShellt, az Azure CLI-t vagy egy Azure Resource Manager-sablont használjon az egyéni szkriptbővítmény virtuálisgép-méretezési csoporton való üzembe helyezésekor. Így dönthet úgy, hogy felügyelt identitást használ, vagy a tárfiókban lévő szkript eléréséhez közvetlenül szabályozhatja az SAS-jogkivonat lejáratát, amíg szüksége van rá.

Hibaelhárítás és támogatás

A bővítménytelepítések állapotával kapcsolatos adatokat az Azure Portalról és az Azure PowerShell-modul használatával kérdezheti le. A virtuális gépek bővítményeinek üzembehelyezési állapotának megtekintéséhez futtassa a következő parancsot:

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

A bővítménykimenet a cél virtuális gép következő mappájában található fájlokba lesz naplózva:

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

A megadott fájlok a cél virtuális gép következő mappájába lesznek letöltve:

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

Az előző elérési út egy decimális egész szám, <n> amely a bővítmény végrehajtása között változhat. Az 1.* érték megegyezik a bővítmény tényleges, aktuális typeHandlerVersion értékével. A tényleges könyvtár C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2lehet például .

A parancs futtatásakor a commandToExecute bővítmény ezt a könyvtárat állítja be például ...\Downloads\2az aktuális munkakönyvtárként. Ez a folyamat lehetővé teszi relatív elérési utak használatát a tulajdonság használatával letöltött fájlok megkereséséhez fileURIs . Íme néhány példa a letöltött fájlokra:

URI a következőben: fileUris Relatív letöltési hely Abszolút letöltési hely
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

Az abszolút könyvtár elérési útjai a virtuális gép élettartama alatt változnak, de az egyéni szkriptbővítmény egyetlen végrehajtásán belül nem.

Mivel az abszolút letöltési útvonal idővel változhat, érdemes a sztring relatív commandToExecute szkript-/fájlútvonalait választani, amikor csak lehetséges. Példa:

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

Az első URI-szegmenst követő elérésiút-információk megmaradnak a fileUris tulajdonságlistával letöltött fájlokhoz. Ahogy a korábbi táblázatban látható, a letöltött fájlok letöltő alkönyvtárakba vannak leképezve, hogy tükrözzék az fileUris értékek szerkezetét.

Támogatás