Aufgabendefinitionen für EC2 Startaufgaben von Launch v2

Jede Aufgabe, die EC2 Launch v2 während des Starts oder Starts ausführt, hat ihre eigenen Eigenschaften und Anforderungen. Zu den Aufgabendetails gehören Einstellungen dafür, wie oft eine Aufgabe ausgeführt wird – einmal oder immer –, in welcher Phase des Startvorgangs des Agenten sie ausgeführt wird, Syntax und Beispiele für YAML-Dokumente. Weitere Informationen finden Sie in den Aufgabendetails in dieser Referenz.

activateWindows

Aktiviert Windows für eine Reihe von AWS KMS Servern. Die Aktivierung wird übersprungen, wenn die Instanz als Bring-Your-Own-License (BYOL) erkannt wird.

Häufigkeit - einmal

AllowedStages — [PreReady]

Eingaben —

activation: (Zuordnung)

type: (Zeichenfolge) Aktivierungstyp, der verwendet werden soll, auf amazon gesetzt

Beispiel

task: activateWindows
  inputs:
    activation:
    type: amazon

enableJumboFrames

Aktiviert Jumbo Frames, die die Maximum Transmission Unit (MTU) des Netzwerkadapters erhöhen. Weitere Informationen finden Sie unter Jumbo-Frames (9001 MTU).

Häufigkeit — immer

AllowedStages — [PostReady, UserData]

Eingaben — keine

Beispiel

task: enableJumboFrames

enableOpenSsh

Aktiviert Windows OpenSSH und fügt den öffentlichen Schlüssel für die Instance dem Ordner für autorisierte Schlüssel hinzu.

Häufigkeit - einmal

AllowedStages — [PreReady, UserData]

Eingaben — keine

Beispiel

Im folgenden Beispiel wird gezeigt, wie OpenSSH für eine Instance aktiviert und der öffentliche Schlüssel für die Instance dem Ordner für autorisierte Schlüssel hinzugefügt wird. Diese Konfiguration funktioniert nur auf Instances, auf denen Windows Server 2019 ausgeführt wird.

task: enableOpenSsh

executeProgram

Führt ein Programm mit optionalen Argumenten und einer angegebenen Häufigkeit aus.

Phasen: Sie können die Aufgabe executeProgram während der Phasen PreReady, PostReady und UserData ausführen.

Frequenz: konfigurierbar, siehe Eingänge.

Eingaben

Dieser Abschnitt enthält ein oder mehrere Programme, mit denen die executeProgram-Aufgabe ausgeführt werden kann (Eingaben). Jede Eingabe kann die folgenden konfigurierbaren Einstellungen enthalten:

Frequenz (Zeichenfolge)

(Erforderlich) Geben Sie genau einen der folgenden Werte an:

• once

• always

Pfad (Zeichenfolge)

(Erforderlich) Der Dateipfad für die auszuführende Datei.

Argumente (Liste von Zeichenfolgen)

(Optional) Eine durch Kommas getrennte Liste von Argumenten, die dem Programm als Eingabe zur Verfügung gestellt werden sollen.

runAs (Zeichenfolge)

(Erforderlich) Muss auf localSystem gesetzt sein

Output

Alle Aufgaben schreiben Logfile-Einträge in die agent.log-Datei. Zusätzliche Ausgaben der Aufgabe executeProgram werden wie folgt separat in einem dynamisch benannten Ordner gespeichert:

%LocalAppData%\Temp\EC2Launch#########\outputfilename.tmp

Der genaue Pfad zu den Ausgabedateien ist in der agent.log-Datei enthalten, zum Beispiel:

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp

Ausgabedateien für die Aufgabe executeProgram

ExecuteProgramInputs.tmp

Enthält den Pfad für die ausführbare Datei und alle Eingabeparameter, die die Aufgabe executeProgram bei der Ausführung an sie übergibt.

Output.tmp

Enthält die Laufzeitausgabe des Programms, das die Aufgabe executeProgram ausführt.

Err.tmp

Enthält die Laufzeit-Fehlermeldungen des Programms, das die Aufgabe executeProgram ausführt.

Beispiele

Die folgenden Beispiele zeigen, wie eine ausführbare Datei aus einem lokalen Verzeichnis auf einer Instance mit der Aufgabe executeProgram ausgeführt wird.

Beispiel 1: Setup Executable mit einem Argument

Dieses Beispiel zeigt eine executeProgram-Aufgabe, die eine Setup Executable im Modus „Quiet“ ausführt.

task: executeProgram
  inputs:
    - frequency: always
      path: C:\Users\Administrator\Desktop\setup.exe
      arguments: ['-quiet']

Beispiel 2: VLC-Executable mit zwei Argumenten

Dieses Beispiel zeigt eine executeProgram-Aufgabe, die eine VLC-Executable-Datei mit zwei als Eingabeparameter übergebenen Argumenten ausführt.

task: executeProgram
  inputs:
    - frequency: always
      path: C:\vlc-3.0.11-win64.exe 
      arguments: ['/L=1033','/S']
      runAs: localSystem

executeScript

Führt ein Skript mit optionalen Argumenten und einer angegebenen Häufigkeit aus. Das Verhalten des Skripts hängt davon ab, in welchem Modus der Agent die Skripte ausführt – inline oder getrennt.

Inline (Standard)

Der EC2 Launch v2-Agent führt die Skripts nacheinander aus ()detach: false. Dies ist die Standardeinstellung.

Anmerkung

Wenn Ihr Inline-Skript einen reset- oder sysprep-Befehl ausgibt, wird es sofort ausgeführt und setzt den Agenten zurück. Die aktuelle Aufgabe wird beendet, dann wird der Agent heruntergefahren, ohne weitere Aufgaben auszuführen.

Wenn beispielsweise auf die Aufgabe, die den Befehl ausgibt, eine startSsm-Aufgabe folgen würde (die standardmäßig nach der Ausführung der Benutzerdaten enthalten ist), wird die Aufgabe nicht ausgeführt und der Systems-Manager-Service nicht gestartet.

Detached (Getrennt)

Der EC2 Launch v2-Agent führt Skripts gleichzeitig mit anderen Aufgaben aus (detach: true).

Anmerkung

Wenn Ihr abgetrenntes Skript einen reset- oder sysprep-Befehl ausgibt, warten diese Befehle, bis der Agent fertig ist, bevor sie ausgeführt werden. Aufgaben nach dem executeScript werden weiterhin ausgeführt.

Phasen: Sie können die Aufgabe executeScript während der Phasen PreReady, PostReady und UserData ausführen.

Frequenz: konfigurierbar, siehe Eingänge.

Eingaben

Dieser Abschnitt enthält ein oder mehrere Skripte, mit denen die executeScript-Aufgabe ausgeführt werden kann (Eingaben). Jede Eingabe kann die folgenden konfigurierbaren Einstellungen enthalten:

Frequenz (Zeichenfolge)

(Erforderlich) Geben Sie genau einen der folgenden Werte an:

• once

• always

Typ (Zeichenfolge)

(Erforderlich) Geben Sie genau einen der folgenden Werte an:

• batch

• powershell

Argumente (Liste von Zeichenfolgen)

(Optional) Eine Liste von Zeichenkettenargumenten, die an die Shell (nicht an das PowerShell Skript) übergeben werden sollen. Dieser Parameter wird nicht für type: batch unterstützt. Wenn keine Argumente übergeben werden, fügt EC2 Launch v2 standardmäßig das folgende Argument hinzu:-ExecutionPolicy Unrestricted.

Inhalt (Zeichenfolge)

(Erforderlich) Skriptinhalt.

runAs (Zeichenfolge)

(Erforderlich) Geben Sie genau einen der folgenden Werte an:

• admin

• localSystem

trennen (Boolean)

(Optional) Der EC2 Launch v2-Agent führt standardmäßig Skripts nacheinander aus (detach: false). Um das Skript gleichzeitig mit anderen Aufgaben auszuführen, setzen Sie den Wert auf true (detach: true).

Anmerkung

Skript-Exitcodes (einschließlich 3010) haben keine Wirkung, wenn detach auf true festgelegt wird.

Output

Alle Aufgaben schreiben Logfile-Einträge in die agent.log-Datei. Zusätzliche Ausgaben von Skripten, die die Aufgabe executeScript ausführt, werden wie folgt separat in einem dynamisch benannten Ordner gespeichert:

%LocalAppData%\Temp\EC2Launch#########\outputfilename.ext

Der genaue Pfad zu den Ausgabedateien ist in der agent.log-Datei enthalten, zum Beispiel:

Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1
Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp
Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp

Ausgabedateien für die Aufgabe executeScript

UserScript.ext

Enthält das Skript, das die Aufgabe executeScript ausgeführt hat. Die Dateierweiterung hängt wie folgt von der Art des Skripts ab, das Sie im type-Parameter für die executeScript-Aufgabe angegeben haben:

• Wenn der Typ batch ist, dann ist die Dateierweiterung .bat.

• Wenn der Typ powershell ist, dann ist die Dateierweiterung .ps1.

Output.tmp

Enthält die Laufzeitausgabe des Skripts, das die Aufgabe executeScript ausführt.

Err.tmp

Enthält die Laufzeit-Fehlermeldungen des Skripts, das die Aufgabe executeScript ausführt.

Beispiele

Die folgenden Beispiele zeigen, wie Sie ein Inline-Skript mit der Aufgabe executeScript ausführen.

Beispiel 1: Hello World Ausgabetextdatei

Dieses Beispiel zeigt eine executeScript Aufgabe, die ein PowerShell Skript ausführt, um eine „Hello World“ -Textdatei auf dem C: Laufwerk zu erstellen.

task: executeScript
  inputs:
    - frequency: always
      type: powershell
      runAs: admin
      content: |-
        New-Item -Path 'C:\PowerShellTest.txt' -ItemType File
        Set-Content 'C:\PowerShellTest.txt' "Hello world"

Beispiel 2: Zwei Skripts ausführen

Dieses Beispiel zeigt, dass die Aufgabe executeScript mehr als ein Skript ausführen kann und der Skripttyp nicht unbedingt übereinstimmen muss.

Das erste Skript (type: powershell) schreibt eine Zusammenfassung der Prozesse, die derzeit auf der Instance ausgeführt werden, in eine Textdatei auf dem C:-Laufwerk.

Das zweite Skript (batch) schreibt die Systeminformationen in die Output.tmp-Datei.

task: executeScript
  inputs:
    - frequency: always
      type: powershell
      runAs: localSystem
      content: |
        Get-Process | Out-File -FilePath C:\Process.txt
    - frequency: always
      type: batch
      runAs: localSystem
      content: |
        systeminfo

Beispiel 3: Idempotenz-Systemkonfiguration mit Neustarts

Dieses Beispiel zeigt eine Aufgabe executeScript, die ein idempotentes Skript ausführt, um die folgende Systemkonfiguration mit einem Neustart zwischen den einzelnen Schritten durchzuführen:

• Den Computer umbenennen.

• Den Computer mit der Domain verbinden.

• Aktivieren von Telnet.

Das Skript stellt sicher, dass jede Operation nur einmal ausgeführt wird. Dies verhindert eine Neustartschleife und macht das Skript idempotent.

task: executeScript
  inputs:
    - frequency: always
      type: powershell
      runAs: localSystem
      content: |-
        $name = $env:ComputerName
        if ($name -ne $desiredName) {
          Rename-Computer -NewName $desiredName
          exit 3010
        }
        $domain = Get-ADDomain
        if ($domain -ne $desiredDomain) 
        {
          Add-Computer -DomainName $desiredDomain
          exit 3010
        }
        $telnet = Get-WindowsFeature -Name Telnet-Client
        if (-not $telnet.Installed)
        {
          Install-WindowsFeature -Name "Telnet-Client"
          exit 3010 
        }

extendRootPartition

Erweitert das Stammvolume, um den gesamten verfügbaren Speicherplatz auf der Festplatte zu nutzen.

Häufigkeit - einmal

AllowedStages — [Boot]

Eingaben — keine

Beispiel

task: extendRootPartition

initializeVolume

Initialisiert leere Volumes, die an die Instance angefügt sind, sodass diese aktiviert und partitioniert werden. Der Startagent überspringt die Initialisierung, wenn er erkennt, dass das Volume nicht leer ist. Ein Volume gilt als leer, wenn die ersten 4 KiB des Volumes leer sind oder wenn das Volume kein von Windows erkennbares Laufwerkslayout aufweist.

Der Eingabeparameter wird letter immer angewendet, wenn diese Aufgabe ausgeführt wird, unabhängig davon, ob das Laufwerk bereits initialisiert ist.

Das initializeVolume führt die folgenden Aktionen aus.

• Setzen Sie die Festplattenattribute offline und readonly auf false.

• Erstellen Sie eine Partition. Wenn im Eingabeparameter partition kein Partitionstyp angegeben ist, gelten die folgenden Standardwerte:

  • Wenn die Festplattengröße kleiner als 2 TB ist, legen Sie den Partitionstyp auf mbr fest.

  • Wenn die Festplattengröße 2 TB oder größer ist, legen Sie den Partitionstyp auf gpt fest.

• Formatieren Sie das Volume als NTFS.

• Legen Sie die Volume-Bezeichnung wie folgt fest:

  • Verwenden Sie den Wert des Eingabeparameters name, falls angegeben.

  • Wenn es sich um ein kurzlebiges Volume handelt und kein Name angegeben wurde, legen Sie die Volume-Bezeichnung auf Temporary Storage Z fest.

• Wenn das Volume kurzlebig ist (SSD oder HDD – nicht Amazon EBS), erstellen Sie im Stammverzeichnis des Volumes eine Important.txt-Datei mit dem folgenden Inhalt:

  This is an 'Instance Store' disk and is provided at no additional charge.
  
  *This disk offers increased performance since it is local to the host
  *The number of Instance Store disks available to an instance vary by instance type
  *DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY
  
  For more information, please refer to: Instanzspeicher temporärer Blockspeicher für  EC2  Instances.

• Legen Sie den Laufwerkbuchstaben auf den im Eingabeparameter letter angegebenen Wert fest.

Phasen: Sie können die Aufgabe initializeVolume während der Phasen PostReady und UserData ausführen.

Häufigkeit: immer.

Eingaben

Sie können Laufzeitparameter wie folgt konfigurieren:

Geräte (Liste der Zuordnungen)

(Bedingt) Konfiguration für jedes Gerät, das vom Startagenten initialisiert wird. Dies ist erforderlich, wenn der Eingabeparameter initialize auf devices festgelegt ist.

• Gerät (Zeichenfolge, erforderlich) – Identifiziert das Gerät während der Instance-Erstellung. Beispiel: xvdb, xvdf oder \dev\nvme0n1.

• Buchstabe (Zeichenfolge, optional) – Ein Zeichen. Der Laufwerkbuchstabe, der zugewiesen werden soll.

• Name (Zeichenfolge, optional) – Der zuzuweisende Volume-Name.

• Partition (Zeichenfolge, optional) – Geben Sie einen der folgenden Werte für den Typ der zu erstellenden Partition an oder lassen Sie den Startagenten basierend auf der Volume-Größe als Standard festlegen:

  • mbr

  • gpt

initialisieren (Zeichenfolge)

(Erforderlich) Geben Sie genau einen der folgenden Werte an:

• all

• devices

Beispiele

Die folgenden Beispiele zeigen Beispiele für Eingabekonfigurationen für die initializeVolume-Aufgabe.

Beispiel 1: Initialisieren von zwei Volumes auf einer Instance

Dieses Beispiel zeigt eine initializeVolume-Aufgabe, die zwei sekundäre Volumes auf einer Instance initialisiert. Das Gerät mit dem Namen DataVolume2 im Beispiel ist kurzlebig.

task: initializeVolume
inputs:
  initialize: devices
  devices:
  - device: xvdb
    name: DataVolume1
    letter: D
    partition: mbr
  - device: /dev/nvme0n1
    name: DataVolume2
    letter: E
    partition: gpt

Beispiel 2: Initialisieren von EBS-Volumes, die an eine Instance angefügt sind

Dieses Beispiel zeigt eine initializeVolume-Aufgabe, die alle leeren EBS-Volumes initialisiert, die an die Instance angefügt sind.

task: initializeVolume
inputs:
  initialize: all

optimizeEna

Optimiert ENA-Einstellungen basierend auf dem aktuellen Instance-Typ. Möglicherweise wird die Instance neu gestartet.

Häufigkeit — immer

AllowedStages — [PostReady, UserData]

Eingaben — keine

Beispiel

task: optimizeEna

setAdminAccount

Legt Attribute für das Standardadministratorkonto fest, das auf dem lokalen Computer erstellt wird.

Häufigkeit - einmal

AllowedStages — [PreReady]

Eingaben —

name: (Zeichenfolge) Name des Administratorkontos

password: (Zuordnung)

type: (Zeichenfolge) Strategie zum Setzen des Passworts, entweder als static, random oder doNothing

data: (Zeichenfolge) speichert Daten, wenn das Feld type statisch ist

Beispiel

task: setAdminAccount
inputs:
  name: Administrator
  password:
  type: random

setDnsSuffix

Fügt DNS-Suffixe zur Liste der Suchsuffixe hinzu. Nur Suffixe, die noch nicht vorhanden sind, werden der Liste hinzugefügt. Weitere Informationen zur Einrichtung von DNS-Suffixen durch Start-Agenten finden Sie unter Konfigurieren Sie das DNS-Suffix für EC2 Windows-Startagenten.

Häufigkeit — immer

AllowedStages — [PreReady]

Eingaben —

suffixes: (Liste von Zeichenfolgen) Liste mit einem oder mehreren gültigen DNS-Suffixen; gültige Substitutionsvariablen sind $REGION und $AZ

Beispiel

task: setDnsSuffix
inputs:
  suffixes:
  - $REGION.ec2-utilities.amazonaws.com

setHostName

Legt den Hostnamen des Computers auf eine benutzerdefinierte Zeichenfolge oder, falls nicht hostName angegeben, auf die private IPv4 Adresse fest.

Häufigkeit — immer

AllowedStages — [PostReady, UserData]

Eingaben —

hostName: (Zeichenfolge) optionaler Host-Name, der wie folgt formatiert werden muss.

• Muss 15 Zeichen oder weniger haben

• Muss nur alphanumerische (a-z, A-Z, 0-9) und Bindestriche (-) enthalten.

• Darf nicht ausschließlich aus numerischen Zeichen bestehen.

reboot: (boolescher Wert) gibt an, ob ein Neustart zulässig ist, wenn der Hostname geändert wird

Beispiel

task: setHostName
inputs:
  reboot: true

setWallpaper

Erstellt die Verknüpfungsdatei setwallpaper.lnk im Startup-Ordner jedes vorhandenen Benutzers, mit Ausnahme von Default User. Diese Verknüpfungsdatei wird ausgeführt, wenn sich der Benutzer nach dem Start der Instance zum ersten Mal anmeldet. Hiermit wird die Instance mit einem benutzerdefinierten Hintergrundbild eingerichtet, auf dem die Instance-Attribute zu sehen sind.

Der Pfad der Verknüpfungsdatei lautet:

$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk

Anmerkung

Wenn Sie die setWallpaper-Aufgabe entfernen, wird diese Verknüpfungsdatei nicht gelöscht. Weitere Informationen finden Sie unter Die Aufgabe setWallpaper ist nicht aktiviert, aber das Hintergrundbild wird beim Neustart zurückgesetzt.

Phasen: Sie können das Hintergrundbild während der Phasen PreReady und UserData konfigurieren.

Häufigkeit: always

Konfiguration des Hintergrundbilds

Sie können Ihr Hintergrundbild mit den folgenden Steuerelementen konfigurieren.

Eingaben

Von Ihnen bereitgestellte Eingabeparameter und Attribute, die Sie zum Konfigurieren Ihres Hintergrundbilds festlegen können:

Attribute (Liste von Zeichenfolgen)

(Optional) Sie können Ihrem Hintergrundbild eines oder mehrere der folgenden Attribute hinzufügen:

• architecture

• availabilityZone

• hostName

• instanceId

• instanceSize

• memory

• network

• privateIpAddress

• publicIpAddress

instanceTags

(Optional) Sie können genau eine der folgenden Optionen für diese Einstellung verwenden.

• AllTags(string) — Fügt alle Instanz-Tags zu Ihrem Hintergrundbild hinzu.

  instanceTags: AllTags

• instanceTags (Liste von Zeichenfolgen) – Geben Sie eine Liste mit Instance-Tag-Namen an, die Ihrem Hintergrundbild hinzugefügt werden sollen. Zum Beispiel:

  instanceTags:
    - Tag 1
    - Tag 2

Pfad (Zeichenfolge)

(Erforderlich) Der Dateinamenspfad der lokalen Bilddatei im .jpg-Format, die für Ihr Hintergrundbild verwendet werden soll.

Beispiel

Das folgende Beispiel zeigt Hintergrundkonfigurationseingaben, die den Dateipfad für das Hintergrundbild festlegen, zusammen mit Instance-Tags mit den Namen Tag 1 und Tag 2 und Attributen, die den Hostnamen, die Instance-ID und die privaten und öffentlichen IP-Adressen für die Instance enthalten.

task: setWallpaper
inputs:
  path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg
  attributes:
  - hostName
  - instanceId
  - privateIpAddress
  - publicIpAddress
instanceTags:
  - Tag 1
  - Tag 2

Anmerkung

Sie müssen Tags in Metadaten aktivieren, um Tags auf dem Hintergrundbild anzuzeigen. Weitere Informationen zu Instance-Tags und Metadaten finden Sie unter Zeigen Sie Tags für Ihre EC2 Instances mithilfe von Instanz-Metadaten an.

startSsm

Starten des Systems Manager-Services (SSM) nach Sysprep.

Häufigkeit — immer

AllowedStages — [PostReady, UserData]

Eingaben — keine

Beispiel

task: startSsm

sysprep

Setzt den Servicestatus zurück, aktualisiert unattend.xml, deaktiviert RDP und führt Sysprep aus. Diese Aufgabe wird erst ausgeführt, wenn alle anderen Aufgaben abgeschlossen sind.

Häufigkeit - einmal

AllowedStages — [UserData]

Eingaben —

clean: (boolescher Wert) bereinigt Instance-Protokolle vor dem Ausführen von Sysprep

shutdown: (boolescher Wert) fährt die Instance nach dem Ausführen von Sysprep herunter

Beispiel

task: sysprep
inputs:
clean: true
shutdown: true

writeFile

Schreibt eine Datei in ein Ziel.

Häufigkeit — siehe Eingaben

AllowedStages — [PostReady, UserData]

Eingaben —

frequency: (Zeichenfolge) once oder always

destination: (Zeichenfolge) Pfad, in den der Inhalt geschrieben werden soll

content: (Zeichenfolge) Text, der an das Ziel geschrieben werden soll

Beispiel

task: writeFile
inputs:
  - frequency: once
  destination: C:\Users\Administrator\Desktop\booted.txt
  content: Windows Has Booted