Zarządzanie skryptami wstępnymi i końcowymi

Skrypty wstępne i końcowe to elementy Runbook uruchamiane na koncie usługi Azure Automation przed (przed zadaniem) i po (po zadaniu) wdrożeniu aktualizacji. Skrypty wstępne i końcowe są uruchamiane w kontekście platformy Azure, a nie lokalnie. Skrypty wstępne są uruchamiane na początku wdrożenia aktualizacji. W systemie Windows skrypty końcowe są uruchamiane na zakończenie wdrażania i po każdym skonfigurowanym ponownym rozruchu. W przypadku systemu Linux skrypty końcowe są wykonywane po zakończeniu wdrażania, a nie po ponownym rozruchu maszyny.

Wymagania dotyczące skryptu początkowego i końcowego

Aby element Runbook był używany jako skrypt wstępny lub post-script, należy zaimportować go na konto usługi Automation i opublikować element Runbook.

Obecnie tylko elementy Runbook programu PowerShell 5.1 i Python 2 są obsługiwane jako skrypty wstępne/post. Inne typy elementów Runbook, takie jak Python 3, Graficzne, Przepływ pracy programu PowerShell, graficzny przepływ pracy programu PowerShell nie są obecnie obsługiwane jako skrypty wstępne/post.

Parametry skryptu wstępnego i po skrycie

Podczas konfigurowania skryptów wstępnych i po skryptach można przekazać parametry tak samo jak planowanie elementu Runbook. Parametry są definiowane w momencie tworzenia wdrożenia aktualizacji. Skrypty wstępne i skrypty końcowe obsługują następujące typy:

• [char]
• [bajt]
• [int]
• [long]
• [dziesiętny]
• [pojedynczy]
• [double]
• [DateTime]
• [ciąg]

Parametry elementu Runbook wstępnego skryptu i post-script nie obsługują typów logicznych, obiektów ani tablic. Te wartości powodują niepowodzenie elementów Runbook.

Jeśli potrzebujesz innego typu obiektu, możesz rzutować go na inny typ z własną logiką w elemecie Runbook.

Oprócz standardowych parametrów SoftwareUpdateConfigurationRunContext elementu Runbook udostępniany jest parametr (ciąg JSON). Jeśli zdefiniujesz parametr w elemecie Runbook przed skryptem lub po skryfcie, zostanie on automatycznie przekazany przez wdrożenie aktualizacji. Parametr zawiera informacje o wdrożeniu aktualizacji, który jest podzbiorem informacji zwracanych przez interfejs API SoftwareUpdateconfigurations. Poniższe sekcje definiują skojarzone właściwości.

Właściwości SoftwareUpdateConfigurationRunContext

Właściwość	Pisz	Opis
SoftwareUpdateConfigurationName	Ciąg	Nazwa konfiguracji aktualizacji oprogramowania.
SoftwareUpdateConfigurationRunId	Identyfikator GUID	Unikatowy identyfikator przebiegu.
SoftwareUpdateConfiguration Ustawienia		Kolekcja właściwości związanych z konfiguracją aktualizacji oprogramowania.
SoftwareUpdateConfiguration Ustawienia. Operatingsystem	Int	Systemy operacyjne przeznaczone dla wdrożenia aktualizacji. 1 = Windows i 2 = Linux
SoftwareUpdateConfiguration Ustawienia. Długość	Przedział czasu (HH:MM:SS)	Maksymalny czas trwania wdrożenia aktualizacji jest uruchamiany zgodnie PT[n]H[n]M[n]S z ISO8601; nazywany również oknem obsługi. Przykład: 02:00:00
SoftwareUpdateConfiguration Ustawienia. Konfiguracja systemu Windows		Kolekcja właściwości związanych z komputerami z systemem Windows.
SoftwareUpdateConfiguration Ustawienia. WindowsConfiguration.excludedKbNumbers	Ciąg	Przestrzeń oddzielona listą baz danych wykluczonych z wdrożenia aktualizacji.
SoftwareUpdateConfiguration Ustawienia. WindowsConfiguration.includedKbNumbers	Ciąg	Rozdzielona spacją lista baz danych dołączonych do wdrożenia aktualizacji.
SoftwareUpdateConfiguration Ustawienia. WindowsConfiguration.UpdateCategories	Integer	1 = "Krytyczne"; 2 = "Zabezpieczenia" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definicja" 64 = "Narzędzia" 128 = "Aktualizacje"
SoftwareUpdateConfiguration Ustawienia. WindowsConfiguration.rebootSetting	Ciąg	Ustawienia ponownego uruchamiania wdrożenia aktualizacji. Wartości to IfRequired, , NeverAlways
SoftwareUpdateConfiguration Ustawienia. Konfiguracja systemu Linux		Kolekcja właściwości związanych z komputerami z systemem Linux.
SoftwareUpdateConfiguration Ustawienia. LinuxConfiguration.IncludedPackageClassifications	Integer	0 = "Niesklasyfikowane" 1 = "Krytyczne" 2 = "Zabezpieczenia" 4 = "Inne"
SoftwareUpdateConfiguration Ustawienia. LinuxConfiguration.IncludedPackageNameMasks	Ciąg	Rozdzielona spacją lista nazw pakietów dołączonych do wdrożenia aktualizacji.
SoftwareUpdateConfiguration Ustawienia. LinuxConfiguration.ExcludedPackageNameMasks	Ciąg	Rozdzielona spacją lista nazw pakietów, które są wykluczone z wdrożenia aktualizacji.
SoftwareUpdateConfiguration Ustawienia. LinuxConfiguration.RebootSetting	Ciąg	Ustawienia ponownego uruchamiania wdrożenia aktualizacji. Wartości to IfRequired, , NeverAlways
SoftwareUpdateConfiguation Ustawienia. AzureVirtualMachines	Tablica ciągów	Lista identyfikatorów resourceId dla maszyn wirtualnych platformy Azure we wdrożeniu aktualizacji.
SoftwareUpdateConfiguration Ustawienia. NonAzureComputerNames	Tablica ciągów	Lista nazw FQDN komputerów spoza platformy Azure we wdrożeniu aktualizacji.

Poniższy przykład to ciąg JSON przekazany do właściwości SoftwareUpdateConfiguration Ustawienia dla komputera z systemem Linux:

"SoftwareUpdateConfigurationSettings": {
     "OperatingSystem": 2,
     "WindowsConfiguration": null,
     "LinuxConfiguration": {
         "IncludedPackageClassifications": 7,
         "ExcludedPackageNameMasks": "fgh xyz",
         "IncludedPackageNameMasks": "abc bin*",
         "RebootSetting": "IfRequired"
     },
     "Targets": {
         "azureQueries": null,
         "nonAzureQueries": ""
     },
     "NonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
     ],
     "AzureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/resourceGroupName/providers/Microsoft.Compute/virtualMachines/vm-01"
     ],
     "Duration": "02:00:00",
     "PSComputerName": "localhost",
     "PSShowComputerName": true,
     "PSSourceJobInstanceId": "2477a37b-5262-4f4f-b636-3a70152901e9"
 }

Poniższy przykład to ciąg JSON przekazany do właściwości SoftwareUpdateConfiguration Ustawienia dla komputera z systemem Windows:

"SoftwareUpdateConfigurationRunContext": {
    "SoftwareUpdateConfigurationName": "sampleConfiguration",
    "SoftwareUpdateConfigurationRunId": "00000000-0000-0000-0000-000000000000",
    "SoftwareUpdateConfigurationSettings": {
      "operatingSystem": "Windows",
      "duration": "02:00:00",
      "windows": {
        "excludedKbNumbers": [
          "168934",
          "168973"
        ],
        "includedUpdateClassifications": "Critical",
        "rebootSetting": "IfRequired"
      },
      "azureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-01",
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-02",
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-03"
      ],
      "nonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
      ]
    }
  }

Pełny przykład ze wszystkimi właściwościami można znaleźć pod adresem: Pobieranie konfiguracji aktualizacji oprogramowania według nazwy.

Uwaga

Obiekt SoftwareUpdateConfigurationRunContext może zawierać zduplikowane wpisy dla maszyn. Może to spowodować wielokrotne uruchamianie skryptów wstępnych i po skryptach na tym samym komputerze. Aby obejść to zachowanie, użyj polecenia Sort-Object -Unique , aby wybrać tylko unikatowe nazwy maszyn wirtualnych.

Używanie skryptu wstępnego lub skryptu po wdrożeniu

Aby użyć skryptu wstępnego lub skryptu po wdrożeniu aktualizacji, zacznij od utworzenia wdrożenia aktualizacji. Wybierz pozycję Wstępne skrypty i skrypty po. Ta akcja powoduje otwarcie strony Wybieranie skryptów wstępnych i po skry skryptach .

Wybierz skrypt, którego chcesz użyć. W tym przykładzie używamy elementu Runbook UpdateManagement-TurnOnVms . Po wybraniu elementu Runbook zostanie otwarta strona Konfigurowanie skryptu . Wybierz pozycję Wstępny skrypt, a następnie wybierz przycisk OK.

Powtórz ten proces dla skryptu UpdateManagement-TurnOffVms . Jednak po wybraniu typu skryptu wybierz pozycję Post-Script(Post-Script).

Sekcja Wybrane elementy zawiera teraz wybrane skrypty. Jeden jest skryptem wstępnym, a drugi jest skryptem po:

Zakończ konfigurowanie wdrożenia aktualizacji.

Po zakończeniu wdrażania aktualizacji możesz przejść do pozycji Wdrożenia aktualizacji , aby wyświetlić wyniki. Jak widać, stan jest udostępniany dla skryptu wstępnego i skryptu końcowego:

Po wybraniu przebiegu wdrożenia aktualizacji zostaną wyświetlone dodatkowe szczegóły skryptów wstępnych i skryptów po. Zostanie udostępniony link do źródła skryptu w momencie uruchomienia.

Zatrzymywanie wdrożenia

Jeśli chcesz zatrzymać wdrożenie na podstawie skryptu wstępnego, musisz zgłosić wyjątek. Jeśli tego nie zrobisz, wdrożenie i skrypt końcowy będą nadal działać. Poniższy fragment kodu pokazuje, jak zgłosić wyjątek przy użyciu programu PowerShell.

#In this case, we want to terminate the patch job if any run fails.
#This logic might not hold for all cases - you might want to allow success as long as at least 1 run succeeds
foreach($summary in $finalStatus)
{
    if ($summary.Type -eq "Error")
    {
        #We must throw in order to fail the patch deployment.
        throw $summary.Summary
    }
}

W języku Python 2 obsługa wyjątków jest zarządzana w bloku try .

Interakcja z maszynami

Skrypty wstępne i końcowe są uruchamiane jako elementy Runbook na koncie usługi Automation, a nie bezpośrednio na maszynach we wdrożeniu. Zadania wstępne i końcowe również są uruchamiane w kontekście platformy Azure i nie mają dostępu do maszyn spoza platformy Azure. W poniższych sekcjach przedstawiono sposób bezpośredniej interakcji z maszynami, niezależnie od tego, czy są to maszyny wirtualne platformy Azure, czy maszyny spoza platformy Azure.

Interakcja z maszynami platformy Azure

Zadania wstępne i zadania końcowe są uruchamiane jako elementy Runbook i nie są uruchamiane natywnie na maszynach wirtualnych platformy Azure we wdrożeniu. Aby korzystać z maszyn wirtualnych platformy Azure, musisz mieć następujące elementy:

• Tożsamość zarządzana lub konto Uruchom jako
• Element Runbook, który chcesz uruchomić

Aby korzystać z maszyn platformy Azure, należy użyć polecenia cmdlet Invoke-AzVMRunCommand do interakcji z maszynami wirtualnymi platformy Azure. Aby zapoznać się z przykładem tego, jak to zrobić, zobacz przykładowy element Runbook Update Management — uruchamianie skryptu za pomocą polecenia Uruchom.

Interakcja z maszynami spoza platformy Azure

Zadania wstępne i zadania podrzędne po uruchomieniu w kontekście platformy Azure i nie mają dostępu do maszyn spoza platformy Azure. Aby wchodzić w interakcje z maszynami spoza platformy Azure, musisz mieć następujące elementy:

• Tożsamość zarządzana lub konto Uruchom jako
• Hybrydowy proces roboczy elementu Runbook zainstalowany na maszynie
• Element Runbook, który chcesz uruchomić lokalnie
• Nadrzędny element Runbook

Aby wchodzić w interakcje z maszynami spoza platformy Azure, nadrzędny element Runbook jest uruchamiany w kontekście platformy Azure. Ten element Runbook wywołuje podrzędny element Runbook za pomocą polecenia cmdlet Start-AzAutomationRunbook. Należy określić RunOn parametr i podać nazwę hybrydowego procesu roboczego elementu Runbook, dla którego skrypt ma zostać uruchomiony. Zobacz przykład rozwiązania Update Management elementu Runbook — uruchamianie skryptu lokalnie.

Przerywanie wdrażania poprawek

Jeśli skrypt wstępny zwraca błąd, możesz przerwać wdrożenie. W tym celu należy zgłosić błąd w skrycie dla dowolnej logiki, która stanowiłaby błąd.

if (<My custom error logic>)
{
    #Throw an error to fail the patch deployment.
    throw "There was an error, abort deployment"
}

W języku Python 2, jeśli chcesz zgłosić błąd, gdy wystąpi określony warunek, użyj instrukcji raise .

If (<My custom error logic>)
   raise Exception('Something happened.')

Przykłady

Przykłady skryptów wstępnych i po skryptach można znaleźć w organizacji usługi Azure Automation GitHub i Galeria programu PowerShell lub zaimportować je za pośrednictwem witryny Azure Portal. W tym celu na koncie usługi Automation w obszarze Automatyzacja procesów wybierz pozycję Galeria elementów Runbook. Użyj rozwiązania Update Management dla filtru.

Możesz też wyszukać je według nazwy skryptu, jak pokazano na poniższej liście:

• Update Management — włączanie maszyn wirtualnych
• Update Management — wyłączanie maszyn wirtualnych
• Update Management — lokalne uruchamianie skryptu
• Update Management — szablon skryptów wstępnych/post
• Update Management — uruchamianie skryptu za pomocą polecenia Uruchom

Ważne

Po zaimportowaniu elementów Runbook należy je opublikować przed ich zastosowaniem. W tym celu znajdź element Runbook na koncie usługi Automation, wybierz pozycję Edytuj, a następnie wybierz pozycję Publikuj.

Wszystkie przykłady są oparte na podstawowym szablonie zdefiniowanym w poniższym przykładzie. Ten szablon może służyć do tworzenia własnego elementu Runbook do użycia ze skryptami wstępnymi i skryptami końcowymi. Dołączono logikę niezbędną do uwierzytelniania za pomocą platformy Azure i obsługę parametru SoftwareUpdateConfigurationRunContext .

<#
.SYNOPSIS
 Barebones script for Update Management Pre/Post

.DESCRIPTION
  This script is intended to be run as a part of Update Management pre/post-scripts.
  It requires the Automation account's system-assigned managed identity.

.PARAMETER SoftwareUpdateConfigurationRunContext
  This is a system variable which is automatically passed in by Update Management during a deployment.
#>

param(
    [string]$SoftwareUpdateConfigurationRunContext
)

#region BoilerplateAuthentication
# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext
#endregion BoilerplateAuthentication

#If you wish to use the run context, it must be converted from JSON
$context = ConvertFrom-Json $SoftwareUpdateConfigurationRunContext
#Access the properties of the SoftwareUpdateConfigurationRunContext
$vmIds = $context.SoftwareUpdateConfigurationSettings.AzureVirtualMachines | Sort-Object -Unique
$runId = $context.SoftwareUpdateConfigurationRunId

Write-Output $context

#Example: How to create and write to a variable using the pre-script:
<#
#Create variable named after this run so it can be retrieved
New-AzAutomationVariable -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -Name $runId -Value "" -Encrypted $false
#Set value of variable
Set-AutomationVariable -Name $runId -Value $vmIds
#>

#Example: How to retrieve information from a variable set during the pre-script
<#
$variable = Get-AutomationVariable -Name $runId
#>

Jeśli chcesz, aby element Runbook był wykonywany przy użyciu tożsamości zarządzanej przypisanej przez system, pozostaw kod w stanie rzeczywistym. Jeśli wolisz użyć tożsamości zarządzanej przypisanej przez użytkownika, wykonaj:

1. Z wiersza 22 usuń $AzureContext = (Connect-AzAccount -Identity).contextelement ,
2. Zastąp go ciągiem $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, i
3. Wprowadź identyfikator klienta.

Uwaga

W przypadku niegraficznych elementów Runbook Add-AzAccount programu PowerShell i Add-AzureRMAccount są aliasami dla Połączenie-AzAccount. Możesz użyć tych poleceń cmdlet lub zaktualizować moduły na koncie usługi Automation do najnowszych wersji. Może być konieczne zaktualizowanie modułów, nawet jeśli właśnie utworzono nowe konto usługi Automation.

Następne kroki

Aby uzyskać szczegółowe informacje na temat zarządzania aktualizacjami, zobacz Zarządzanie aktualizacjami i poprawkami dla maszyn wirtualnych.