Schemata, Features und Beispiele - AWS Systems Manager
Schema der Version 2.2Schema der Version 1.2Schema der Version 0.3Beispiele für die sichere ParameterverarbeitungBewährte Methoden für die Parametersicherheit

AWS Systems ManagerChange Managersteht neuen Kunden nicht mehr offen. Bestandskunden können den Service weiterhin wie gewohnt nutzen. Weitere Informationen finden Sie unter Änderung der AWS Systems ManagerChange Manager Verfügbarkeit.

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.

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
Funktion 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.

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.