• Das AWS Systems Manager CloudWatch Dashboard wird nach dem 30. April 2026 nicht mehr verfügbar sein. Kunden können weiterhin die CloudWatch Amazon-Konsole verwenden, um ihre CloudWatch Amazon-Dashboards anzusehen, zu erstellen und zu verwalten, so wie sie es heute tun. Weitere Informationen finden Sie in der [Amazon CloudWatch Dashboard-Dokumentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Schemata, Features und Beispiele
AWS Systems Manager (SSM) -Dokumente verwenden die folgenden Schemaversionen.
+ Dokumente des Typs `Command` können die Schema-Versionen 1.2, 2.0 und 2.2 verwenden. Wenn Sie Schema 1.2-Dokumente verwenden, empfehlen wir, dass Sie Dokumente erstellen, die Schema-Version 2.2 verwenden.
+ Dokumente des Typs `Policy` müssen Schema-Version 2.0 oder höher verwenden.
+ Dokumente des Typs `Automation` müssen Schema-Version 0.3 verwenden.
+ Dokumente des Typs `Session` müssen Schema-Version 1.0 verwenden.
+ Sie können Dokumente im JSON- oder YAML-Format erstellen.
Weitere Informationen zu `Session`-Dokumentschemas finden Sie unter [Schema des Sitzungsdokuments](session-manager-schema.md).
Durch die Verwendung der neuesten Schema-Version `Command`- und `Policy`-Dokumente können Sie die folgenden Features nutzen.
**Features für Schema-Version 2.2-Dokumente**
| Feature | Details |
| --- | --- |
| Dokumentbearbeitung | Dokumente können jetzt aktualisiert werden. Bei Version 1.2 mussten aktualisierte Dokument unter einem anderen Namen gespeichert werden. |
| Automatisches Versioning | Bei jeder Änderung an einem Dokument wird eine neue Version erstellt. Dies ist kein Schema-Version, sondern eine Version des Dokuments. |
| Standardversion | Wenn Sie mehrere Versionen eines Dokuments haben, können Sie festlegen, welche Version das Standarddokument ist. |
| Sequenzierung | Plugins oder *Schritte* in einem Dokument werden in der Reihenfolge ausgeführt, die Sie angegeben haben. |
| Unterstützung für plattformübergreifende Anweisungen | Die Unterstützung für plattformübergreifende Anweisungen ermöglicht die Angabe unterschiedlicher Betriebssysteme für verschiedene Plugins innerhalb desselben SSM-Dokuments. Plattformübergreifende Anweisungen verwenden in einem Schritt den Parameter `precondition`. |
| Parameterinterpolation | Interpolation bedeutet, einen Variablenwert in einer Zeichenfolge einzufügen oder zu ersetzen. Sie füllen sozusagen eine Lücke mit Werten, bevor die Zeichenfolge verwendet wird. Im Zusammenhang mit SSM-Dokumenten ermöglicht die Parameterinterpolation, Zeichenfolgeparameter vor der Befehlsausführung in Umgebungsvariablen zu interpolieren, was mehr Schutz vor Befehlseinschleusungen bietet. Wenn diese Option auf `ENV_VAR` gesetzt ist, erstellt der Agent eine Umgebungsvariable mit dem Namen `SSM_parameter-name`, die den Wert des Parameters enthält. |
**Anmerkung**
Sie müssen Ihre Instanzen mit der neuesten Version AWS Systems Manager SSM Agent auf dem neuesten Stand halten, um die neuen Systems Manager Manager-Funktionen und SSM-Dokumentfunktionen nutzen zu können. Weitere Informationen finden Sie unter [Aktualisierung von SSM Agent mithilfe von Run Command](run-command-tutorial-update-software.md#rc-console-agentexample).
In der folgenden Tabelle finden Sie die Unterschiede zwischen de Schema-Hauptversionen.
****
| Version 1.2 | Version 2.2 (neueste Version) | Details |
| --- | --- | --- |
| runtimeConfig | mainSteps | In Version 2.2 ersetzt der Abschnitt `mainSteps` `runtimeConfig`. Im Abschnitt `mainSteps` erlaubt Systems Manager das Ausführen von nacheinander folgenden Schritten. |
| Eigenschaften | inputs | In Version 2.2 ersetzt der Abschnitt `inputs` den Abschnitt `properties`. Der Abschnitt `inputs` nimmt Parameter für Schritte entgegen. |
| commands | runCommand | In Version 2.2 ersetzt im Abschnitt `inputs` der Parameter `runCommand` den Parameter `commands`. |
| id | action | In Version 2.2 ersetzt `Action` `ID`. Dies ist lediglich eine Umbenennung. |
| n.v. | Name | In Version 2.2 ist `name` ein benutzerdefinierter Name für einen Schritt. |
**Verwenden des Parameters „precondition“**
Bei Schema-Version 2.2 oder neuer können Sie mithilfe des Parameters `precondition` das Zielbetriebssystem für jedes Plugin angeben oder um Eingabeparameter zu validieren, die Sie in Ihrem SSM-Dokument definiert haben. Der `precondition`-Parameter unterstützt die Referenzierung der Eingabeparameter Ihres SSM-Dokuments und `platformType` unter Verwendung von Werten von `Linux`, `MacOS` und `Windows`. Nur der `StringEquals`-Operator wird unterstützt.
Wenn bei Dokumenten in Schema-Version 2.2 oder höher `precondition` nicht angegeben ist, werden Plugins entweder ausgeführt oder übersprungen, je nachdem, ob das Plugin mit dem jeweiligen Betriebssystem kompatibel ist. Plugin-Kompatibilität mit dem Betriebssystem wird vor der `precondition` ausgewertet. Bei Dokumenten, die Schema-Version 2.0 oder eine frühere Version verwenden, wird bei nicht kompatiblen Plugins ein Fehler ausgelöst.
Wenn beispielsweise in einem Schema-Version 2.2-Dokument `precondition` nicht angegeben ist und das `aws:runShellScript`-Plugin zur Ausführung aufgelistet ist, wird der Schritt auf Linux-Instances ausgeführt, aber auf Windows Server-Instances übersprungen, da `aws:runShellScript` nicht kompatibel mit Windows Server-Instances ist. Bei Schema-Version 2.0 Dokumenten schlägt jedoch die Ausführung fehl, wenn Sie das `aws:runShellScript`-Plugin angeben und dann das Dokument auf einer Windows Server-Instance ausführen. Weiter hinten in diesem Abschnitt finden Sie ein Beispiel der Vorbedingungsparameter in SSM-Dokumenten.
## Schema der Version 2.2
**Top-Level-Elemente**
Das folgende Beispiel zeigt die Elemente der obersten Ebene eines SSM-Dokuments bei Verwendung von Schema-Version 2.2.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**Schema-Version 2.2 -Beispiel**
Im folgenden Beispiel wird das `aws:runPowerShellScript` Plugin verwendet, um einen PowerShell Befehl auf den Zielinstanzen auszuführen.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**Schema der Version 2.2 – Vorbedingungsparameterbeispielen**
Schema-Version 2.2 bietet Unterstützung für plattformübergreifende Aktionen. Dies bedeutet, dass Sie in einem SSM-Dokument unterschiedliche Betriebssysteme für verschiedene Plugins angeben können. Plattformübergreifende Aktionen werden durch den Parameter `precondition` in einem Schritt aufgerufen, wie in dem folgenden Beispiel dargestellt. Sie können auch den `precondition`-Parameter verwenden, um Eingabeparameter zu validieren, die Sie in Ihrem SSM-Dokument definiert haben. Dies sehen Sie im zweiten der folgenden Beispiele.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**Interpolationsbeispiel für Schemaversion 2.2 mit SSM Agent-Versionen vor 3.3.2746.0**
In SSM Agent-Versionen vor 3.3.2746.0 ignoriert der Agent den `interpolationType`-Parameter und ersetzt stattdessen einfach die Zeichenfolge. Wenn Sie `SSM_parameter-name` referenzieren, müssen Sie dies explizit festlegen. Im folgenden Beispiel für Linux wird explizit auf die Umgebungsvariable `SSM_Message` verwiesen.
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**Anmerkung**
`allowedPattern` ist streng genommen nicht erforderlich, wenn ein SSM-Dokument keine doppelten Klammern verwendet: `{{ }}`
**Schema-Version 2.2 State Manager-Beispiel**
Sie können das folgende SSM-Dokument mit State Manager nutzen, einem Tool in Systems Manager, um die ClamAV-Antivirensoftware herunterzuladen und zu installieren. State Manager erzwingt eine bestimmte Konfiguration, d. h. jedes Mal, wenn die State Manager-Zuordnung ausgeführt wird, prüft das System, ob die ClamAV-Software installiert ist. Ist dies nicht der Fall, führt State Manager dieses Dokument erneut aus.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**Schema Version 2.2 - Bestandsbeispiel**
Sie können das folgende SSM-Dokument mit State Manager verwenden, um Bestandsmetadaten zu Ihren Instances zu erfassen.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Software Inventory Policy Document.
parameters:
applications:
type: String
default: Enabled
description: "(Optional) Collect data for installed applications."
allowedValues:
- Enabled
- Disabled
awsComponents:
type: String
default: Enabled
description: "(Optional) Collect data for AWS Components like amazon-ssm-agent."
allowedValues:
- Enabled
- Disabled
networkConfig:
type: String
default: Enabled
description: "(Optional) Collect data for Network configurations."
allowedValues:
- Enabled
- Disabled
windowsUpdates:
type: String
default: Enabled
description: "(Optional) Collect data for all Windows Updates."
allowedValues:
- Enabled
- Disabled
instanceDetailedInformation:
type: String
default: Enabled
description: "(Optional) Collect additional information about the instance, including
the CPU model, speed, and the number of cores, to name a few."
allowedValues:
- Enabled
- Disabled
customInventory:
type: String
default: Enabled
description: "(Optional) Collect data for custom inventory."
allowedValues:
- Enabled
- Disabled
mainSteps:
- action: aws:softwareInventory
name: collectSoftwareInventoryItems
inputs:
applications: "{{ applications }}"
awsComponents: "{{ awsComponents }}"
networkConfig: "{{ networkConfig }}"
windowsUpdates: "{{ windowsUpdates }}"
instanceDetailedInformation: "{{ instanceDetailedInformation }}"
customInventory: "{{ customInventory }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Software Inventory Policy Document.",
"parameters": {
"applications": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for installed applications.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"awsComponents": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for AWS Components like amazon-ssm-agent.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"networkConfig": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for Network configurations.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"windowsUpdates": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for all Windows Updates.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"instanceDetailedInformation": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect additional information about the instance, including\nthe CPU model, speed, and the number of cores, to name a few.",
"allowedValues": [
"Enabled",
"Disabled"
]
},
"customInventory": {
"type": "String",
"default": "Enabled",
"description": "(Optional) Collect data for custom inventory.",
"allowedValues": [
"Enabled",
"Disabled"
]
}
},
"mainSteps": [
{
"action": "aws:softwareInventory",
"name": "collectSoftwareInventoryItems",
"inputs": {
"applications": "{{ applications }}",
"awsComponents": "{{ awsComponents }}",
"networkConfig": "{{ networkConfig }}",
"windowsUpdates": "{{ windowsUpdates }}",
"instanceDetailedInformation": "{{ instanceDetailedInformation }}",
"customInventory": "{{ customInventory }}"
}
}
]
}
```
------
**Schema-Version 2.2 `AWS-ConfigureAWSPackage`-Beispiel**
Das folgende Beispiel zeigt das `AWS-ConfigureAWSPackage`-Dokument. Der Abschnitt `mainSteps` enthält das `aws:configurePackage`-Plugin im Schritt `action`.
**Anmerkung**
In Linux-Betriebssystemen werden nur die `AmazonCloudWatchAgent`- und `AWSSupport-EC2Rescue`-Pakete unterstützt.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Install or uninstall the latest version or specified version of an AWS
package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver,
AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.'
parameters:
action:
description: "(Required) Specify whether or not to install or uninstall the package."
type: String
allowedValues:
- Install
- Uninstall
name:
description: "(Required) The package to install/uninstall."
type: String
allowedPattern: "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
version:
type: String
description: "(Optional) A specific version of the package to install or uninstall."
mainSteps:
- action: aws:configurePackage
name: configurePackage
inputs:
name: "{{ name }}"
action: "{{ action }}"
version: "{{ version }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Install or uninstall the latest version or specified version of an AWS package. Available packages include the following: AWSPVDriver, AwsEnaNetworkDriver, AwsVssComponents, and AmazonCloudWatchAgent, and AWSSupport-EC2Rescue.",
"parameters": {
"action": {
"description":"(Required) Specify whether or not to install or uninstall the package.",
"type":"String",
"allowedValues":[
"Install",
"Uninstall"
]
},
"name": {
"description": "(Required) The package to install/uninstall.",
"type": "String",
"allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:package\\/[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$|^[a-zA-Z][a-zA-Z0-9\\-_]{0,39}$"
},
"version": {
"type": "String",
"description": "(Optional) A specific version of the package to install or uninstall."
}
},
"mainSteps":[
{
"action": "aws:configurePackage",
"name": "configurePackage",
"inputs": {
"name": "{{ name }}",
"action": "{{ action }}",
"version": "{{ version }}"
}
}
]
}
```
------
## Schema der Version 1.2
Das folgende Beispiel zeigt die Elemente der obersten Ebene eines Dokuments in Schema-Version 1.2.
```
{
"schemaVersion":"1.2",
"description":"A description of the SSM document.",
"parameters":{
"parameter 1":{
"one or more parameter properties"
},
"parameter 2":{
"one or more parameter properties"
},
"parameter 3":{
"one or more parameter properties"
}
},
"runtimeConfig":{
"plugin 1":{
"properties":[
{
"one or more plugin properties"
}
]
}
}
}
```
**Schema-Version 1.2 `aws:runShellScript`-Beispiel**
Das folgende Beispiel zeigt das `AWS-RunShellScript` SSM-Dokument. Der Abschnitt **runtimeConfig** bindet das Plugin `aws:runShellScript` ein.
```
{
"schemaVersion":"1.2",
"description":"Run a shell script or specify the commands to run.",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
},
"workingDirectory":{
"type":"String",
"default":"",
"description":"(Optional) The path to the working directory on your instance.",
"maxChars":4096
},
"executionTimeout":{
"type":"String",
"default":"3600",
"description":"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).",
"allowedPattern":"([1-9][0-9]{0,3})|(1[0-9]{1,4})|(2[0-7][0-9]{1,3})|(28[0-7][0-9]{1,2})|(28800)"
}
},
"runtimeConfig":{
"aws:runShellScript":{
"properties":[
{
"id":"0.aws:runShellScript",
"runCommand":"{{ commands }}",
"workingDirectory":"{{ workingDirectory }}",
"timeoutSeconds":"{{ executionTimeout }}"
}
]
}
}
}
```
## Schema der Version 0.3
**Top-Level-Elemente**
Im folgenden Beispiel werden die Elemente der obersten Ebene eines Automation-Runbook der Schema-Version 0.3im JSON-Format gezeigt.
```
{
"description": "document-description",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"parameter1": {
"type": "String",
"description": "parameter-1-description",
"default": ""
},
"parameter2": {
"type": "String",
"description": "parameter-2-description",
"default": ""
}
},
"variables": {
"variable1": {
"type": "StringMap",
"description": "variable-1-description",
"default": {}
},
"variable2": {
"type": "String",
"description": "variable-2-description",
"default": "default-value"
}
},
"mainSteps": [
{
"name": "myStepName",
"action": "action-name",
"maxAttempts": 1,
"inputs": {
"Handler": "python-only-handler-name",
"Runtime": "runtime-name",
"Attachment": "script-or-zip-name"
},
"outputs": {
"Name": "output-name",
"Selector": "selector.value",
"Type": "data-type"
}
}
],
"files": {
"script-or-zip-name": {
"checksums": {
"sha256": "checksum"
},
"size": 1234
}
}
}
```
**Beispiel für YAML-Automation-Runbook**
Das folgende Beispiel zeigt den Inhalt eines Automation-Runbooks im YAML-Format. In diesem funktionierenden Beispiel der Version 0.3 des Dokumentschemas wird auch die Verwendung von Markdown zur Formatierung von Dokumentbeschreibungen veranschaulicht.
```
description: >-
##Title: LaunchInstanceAndCheckState
-----
**Purpose**: This Automation runbook first launches an EC2 instance
using the AMI ID provided in the parameter ```imageId```. The second step of
this document continuously checks the instance status check value for the
launched instance until the status ```ok``` is returned.
##Parameters:
-----
Name | Type | Description | Default Value
------------- | ------------- | ------------- | -------------
assumeRole | String | (Optional) The ARN of the role that allows Automation to
perform the actions on your behalf. | -
imageId | String | (Optional) The AMI ID to use for launching the instance.
The default value uses the latest Amazon Linux AMI ID available. | {{
ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
description: >-
(Optional) The AMI ID to use for launching the instance. The default value
uses the latest released Amazon Linux AMI ID.
tagValue:
type: String
default: ' LaunchedBySsmAutomation'
description: >-
(Optional) The tag value to add to the instance. The default value is
LaunchedBySsmAutomation.
instanceType:
type: String
default: t2.micro
description: >-
(Optional) The instance type to use for the instance. The default value is
t2.micro.
mainSteps:
- name: LaunchEc2Instance
action: 'aws:executeScript'
outputs:
- Name: payload
Selector: $.Payload
Type: StringMap
inputs:
Runtime: python3.11
Handler: launch_instance
Script: ''
InputPayload:
image_id: '{{ imageId }}'
tag_value: '{{ tagValue }}'
instance_type: '{{ instanceType }}'
Attachment: launch.py
description: >-
**About This Step**
This step first launches an EC2 instance using the ```aws:executeScript```
action and the provided python script.
- name: WaitForInstanceStatusOk
action: 'aws:executeScript'
inputs:
Runtime: python3.11
Handler: poll_instance
Script: |-
def poll_instance(events, context):
import boto3
import time
ec2 = boto3.client('ec2')
instance_id = events['InstanceId']
print('[INFO] Waiting for instance status check to report ok', instance_id)
instance_status = "null"
while True:
res = ec2.describe_instance_status(InstanceIds=[instance_id])
if len(res['InstanceStatuses']) == 0:
print("Instance status information is not available yet")
time.sleep(5)
continue
instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
print('[INFO] Polling to get status of the instance', instance_status)
if instance_status == 'ok':
break
time.sleep(10)
return {'Status': instance_status, 'InstanceId': instance_id}
InputPayload: '{{ LaunchEc2Instance.payload }}'
description: >-
**About This Step**
The python script continuously polls the instance status check value for
the instance launched in Step 1 until the ```ok``` status is returned.
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
## Beispiele für die sichere Parameterverarbeitung
In den folgenden Beispielen wird die sichere Verarbeitung von Parametern mithilfe der Umgebungsvariable `interpolationType` gezeigt.
### Grundlegende sichere Befehlsausführung
Dieses Beispiel zeigt, wie ein Befehlsparameter sicher verarbeitet werden kann:
**Anmerkung**
`allowedPattern` ist in SSD-Dokumenten streng genommen nicht erforderlich, wenn sie keine doppelten Klammern enthalten: `{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### Verwenden von Parametern in interpretierten Sprachen
Dieses Beispiel zeigt die sichere Parameterverarbeitung in Python:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### Beispiel für die Abwärtskompatibilität
Dieses Beispiel zeigt, wie Sie Parameter sicher verarbeiten und die Abwärtskompatibilität wahren können:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**Anmerkung**
`allowedPattern` ist in SSD-Dokumenten streng genommen nicht erforderlich, wenn sie keine doppelten Klammern enthalten: `{{ }}`
## Bewährte Methoden für die Parametersicherheit
Folgen Sie diesen bewährten Methoden beim Verarbeiten von Parametern in SSM-Dokumenten:
+ **Interpolation von Umgebungsvariablen nutzen**: Verwenden Sie immer `interpolationType: "ENV_VAR"` für Zeichenfolgeparameter, die in der Befehlsausführung verwendet werden.
+ **Eingabevalidierung implementieren**: Verwenden Sie `allowedPattern`, um Parameterwerte auf sichere Muster zu beschränken.
+ **Legacy-Systeme**: Fügen Sie Fallback-Logik für ältere Versionen von SSM Agent hinzu, die die Interpolation von Umgebungsvariablen nicht unterstützen.
+ **Sonderzeichen maskieren**: Wenn Sie Parameterwerte in Befehlen verwenden, sollten Sie Sonderzeichen korrekt maskieren, um eine Interpretation durch die Shell zu verhindern.
+ **Parameterbereich einschränken**: Verwenden Sie die restriktivsten Parametermuster, die für Ihren Anwendungsfall möglich sind.