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 dieses Typs Session müssen die Schemaversion 1.0 verwenden.
Sie können Dokumente in JSON oder erstellenYAML.

Weitere Informationen zum Session Dokumentschema finden Sie unterSchema 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	Plug-ins oder Schritte in einem Dokument werden in der Reihenfolge ausgeführt, die Sie angegeben haben.
Unterstützung für plattformübergreifende Anweisungen	Die plattformübergreifende Unterstützung ermöglicht es Ihnen, verschiedene Betriebssysteme für verschiedene Plugins innerhalb desselben SSM Dokuments anzugeben. Plattformübergreifende Anweisungen verwenden in einem Schritt den Parameter `precondition`.

Anmerkung

Sie müssen Ihre Instanzen 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“

Mit Schemaversion 2.2 oder höher können Sie den precondition Parameter verwenden, um das Zielbetriebssystem für jedes Plugin anzugeben oder um Eingabeparameter zu überprüfen, die Sie in Ihrem SSM Dokument definiert haben. Der precondition Parameter unterstützt das Verweisen auf die Eingabeparameter Ihres SSM Dokuments und die platformType Verwendung von Werten von LinuxMacOS, undWindows. Nur der StringEquals-Operator wird unterstützt.

Wenn bei Dokumenten in Schema-Version 2.2 oder höher precondition nicht angegeben ist, werden Plug-ins entweder ausgeführt oder übersprungen, je nachdem, ob das Plug-in 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 Plug-ins 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. Ein Beispiel für den Parameter precondition in einem SSM Dokument finden Sie weiter unten in diesem Abschnitt.

Schema der Version 2.2

Top-Level-Elemente

Das folgende Beispiel zeigt die Elemente der obersten Ebene eines SSM Dokuments, das Schemaversion 2.2 verwendet.

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. Das bedeutet, dass Sie in einem einzigen SSM Dokument verschiedene 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 den precondition Parameter auch verwenden, um Eingabeparameter zu überprüfen, die Sie in Ihrem SSM Dokument definiert haben. Dies sehen Sie im zweiten der folgenden Beispiele.

Schema-Version 2.2 State Manager-Beispiel

Sie können das folgende SSM Dokument mit State Manager einer Funktion von Systems Manager verwenden, um die ClamAV-Antivirensoftware herunterzuladen und zu installieren. State Managererzwingt eine bestimmte Konfiguration, was bedeutet, dass das System jedes Mal, wenn die State Manager Assoziation ausgeführt wird, überprüft, ob die ClamAV-Software installiert ist. Ist dies nicht der Fall, führt State Manager dieses Dokument erneut aus.

Schema Version 2.2 - Bestandsbeispiel

Sie können das folgende SSM Dokument verwenden, State Manager um Inventar-Metadaten über Ihre Instanzen 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 runtimeConfigAbschnitt enthält das aws:runShellScript Plugin.


{
    "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

Das folgende Beispiel zeigt die Elemente der obersten Ebene eines Automatisierungs-Runbooks der Schemaversion 0.3 im JSON Format.


{
    "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
        }
    }
}

YAMLBeispiel für ein Automatisierungs-Runbook

Das folgende Beispiel zeigt den Inhalt eines Automatisierungs-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-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

YAMLBeispiel für ein Automatisierungs-Runbook

Schema-Version 2.2 `AWS-ConfigureAWSPackage`-Beispiel

Schema-Version 1.2 `aws:runShellScript`-Beispiel