Egyéniszkript-bővítmény Windows rendszerre
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
ésstorageAccountKey
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 storageAccountName
storageAccountKey
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 storageAccountName
storageAccountKey
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:
- Virtuálisgép-bővítmények üzembe helyezése Azure Resource Manager-sablonokkal
- Kétrétegű alkalmazás üzembe helyezése Windows és Azure SQL Database rendszeren
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\2
lehet 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\2
az 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
Ha segítségre van szüksége a cikk bármely részével kapcsolatban, forduljon az Azure-szakértőkhöz az Azure közösségi támogatási szolgálatánál.
Ha Azure-támogatás incidenst szeretne beszedni, lépjen a Azure-támogatás webhelyre, és válassza a Támogatás kérése lehetőséget.
A Azure-támogatás használatáról a Microsoft Azure-támogatás gyakori kérdéseiben olvashat.