Schema der Version 2.2 Schema der Version 1.2 Schema der Version 0.3

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

Anmerkung

Sie müssen behalten AWS Systems Manager SSM Agent auf Ihren Instanzen, die mit der neuesten Version aktualisiert wurden, um neue Systems Manager Manager-Funktionen und SSM-Dokumentfunktionen zu verwenden. 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 Dokument mit Schemaversion 2.2 precondition nicht angegeben und das aws:runShellScript Plugin aufgeführt ist, wird der Schritt auf Linux-Instances ausgeführt, aber das System überspringt ihn Windows Server Instanzen, weil das aws:runShellScript nicht kompatibel ist mit Windows Server Instanzen. Wenn Sie jedoch für ein Dokument mit Schemaversion 2.0 das aws:runShellScript Plug-In angeben und das Dokument dann auf einem Windows Server Bei Instanzen schlägt die Ausführung fehl. 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.

Schema-Version 2.2 -Beispiel

Im folgenden Beispiel wird das aws:runPowerShellScript Plugin verwendet, um einen PowerShell Befehl auf den Zielinstanzen auszuführen.

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.

Schema der Version 2.2 State Manager Beispiel

Sie können das folgende SSM-Dokument verwenden mit State Manager, ein Tool im Systems Manager, um die Antivirensoftware ClamAV herunterzuladen und zu installieren. State Manager erzwingt eine bestimmte Konfiguration, was bedeutet, dass jedes Mal State Manager Die Verknüpfung wird ausgeführt, das System überprüft, ob die ClamAV-Software installiert ist. Falls nicht, State Manager führt dieses Dokument erneut aus.

Schema Version 2.2 - Bestandsbeispiel

Sie können das folgende SSM-Dokument verwenden mit State Manager um Inventar-Metadaten über Ihre Instances zu sammeln.

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/amzn-ami-hvm-x86_64-gp2 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
  imageId:
    type: String
    default: '{{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}'
    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.8
      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.8
      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

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Dokument-Komponenten

Datenelemente und Parameter

Schemata, Features und Beispiele

Anmerkung

Verwenden des Parameters „precondition“

Schema der Version 2.2

Top-Level-Elemente

Schema-Version 2.2 -Beispiel

Schema der Version 2.2 – Vorbedingungsparameterbeispielen

Schema der Version 2.2 State Manager Beispiel

Schema Version 2.2 - Bestandsbeispiel

Schema-Version 2.2 AWS-ConfigureAWSPackage-Beispiel

Anmerkung

Schema der Version 1.2

Schema-Version 1.2 aws:runShellScript-Beispiel

Schema der Version 0.3

Top-Level-Elemente

Beispiel für YAML-Automation-Runbook

Schema-Version 2.2 `AWS-ConfigureAWSPackage`-Beispiel

Schema-Version 1.2 `aws:runShellScript`-Beispiel