Version de schéma 2.2 Version de schéma 1.2 Version de schéma 0.3

Schémas, fonctionnalités et exemples

AWS Systems Manager (SSM) les documents utilisent les versions de schéma suivantes.

Les documents de type Command peuvent utiliser la version de schéma 1.2, 2.0, et 2.2. Si vous utilisez des documents de schéma 1.2, nous vous recommandons de créer des documents qui utilisent la version de schéma 2.2.
Les documents de type Policy doivent utiliser la version de schéma 2.0 ou ultérieure.
Les documents de type Automation doivent utiliser la version de schéma 0.3.
Les documents de type Session doivent utiliser la version 1.0 du schéma.
Vous pouvez créer des documents dans JSON ouYAML.

Pour plus d'informations sur Session le schéma du document, consultezSchéma de document de session.

En utilisant la dernière version de schéma pour les documents Command et Policy, vous pouvez profiter des fonctions suivantes.

Fonctionnalités d'un document de version de schéma 2.2
Fonctionnalité	Détails
Modification du document	Les documents peuvent désormais être mis à jour. Avec la version 1.2, la mise à jour d'un document nécessitait qu'il soit enregistré sous un autre nom.
Gestion automatique des versions	Toute mise à jour d'un document crée une nouvelle version. Il ne s'agit pas d'une version de schéma, mais d'une version du document.
Version par défaut	Si vous disposez de plusieurs versions d'un document, vous pouvez spécifier la version qui est le document par défaut.
Séquençage	Les plug-ins ou étapes dans un document s'exécutent dans l'ordre que vous avez spécifié.
Support multiplateforme	La prise en charge multiplateforme vous permet de spécifier différents systèmes d'exploitation pour différents plug-ins au sein d'un même SSM document. Le support multiplateforme utilise le même paramètre `precondition` dans une étape.

Note

Vous devez maintenir AWS Systems Manager SSM Agent vos instances à jour avec la dernière version afin d'utiliser les nouvelles fonctionnalités de Systems Manager et les fonctionnalités SSM documentaires. Pour de plus amples informations, veuillez consulter Mise à jour de SSM Agent à l'aide de Run Command.

Le tableau suivant répertorie les différences entre les versions majeures du schéma.

Version 1.2	Version 2.2 (dernière version)	Détails
runtimeConfig	mainSteps	Dans la version 2.2, la section `mainSteps` remplace `runtimeConfig`. La section `mainSteps` permet à Systems Manager d'exécuter des étapes en séquence.
propriétés	inputs	Dans la version 2.2, la section `inputs` remplace la section `properties` . La section `inputs` accepte des paramètres pour les étapes.
commands	runCommand	Dans la version 2.2, la section `inputs` prend le paramètre `runCommand` au lieu du paramètre `commands`.
id	action	Dans la version 2.2, `Action` remplace `ID`. Il s'agit simplement d'une modification de nom.
ne s'applique pas	name	Dans la version 2.2, `name` est tout nom défini par l'utilisateur pour une étape.

Utilisation du paramètre de condition préalable

Avec la version 2.2 ou ultérieure du schéma, vous pouvez utiliser le precondition paramètre pour spécifier le système d'exploitation cible pour chaque plug-in ou pour valider les paramètres d'entrée que vous avez définis dans votre SSM document. Le precondition paramètre prend en charge le référencement des paramètres d'entrée de votre SSM document et platformType l'utilisation des valeurs de LinuxMacOS, etWindows. Seul l'opérateur StringEquals est pris en charge.

Pour les documents utilisant la version de schéma 2.2 ou une version ultérieure, si precondition n'est pas spécifié, chaque plugin est soit exécuté, soit ignoré en fonction de sa compatibilité avec le système d'exploitation. La compatibilité du plugin avec le système d'exploitation est évaluée avant la precondition. Pour les documents utilisant le schéma 2.0 ou antérieur, les plug-ins incompatibles entraînent une erreur.

Par exemple, dans un document de version de schéma 2.2, si precondition n'est pas spécifié et que le plugin aws:runShellScript figure dans la liste, l'étape s'exécute sur les instances Linux, mais le système l'ignore sur les instances Windows Server, car le aws:runShellScript n'est pas compatible avec les instances Windows Server. Néanmoins, pour un document de version de schéma 2.0., si vous spécifiez le plug-in aws:runShellScript, puis exécutez le document sur des instances Windows Server, l'exécution échoue. Vous trouverez un exemple du paramètre de précondition dans un SSM document plus loin dans cette section.

Version de schéma 2.2

Éléments de niveau supérieur

L'exemple suivant montre les éléments de premier niveau d'un SSM document utilisant la version 2.2 du schéma.

Exemple de version de schéma 2.2

L'exemple suivant utilise le aws:runPowerShellScript plugin pour exécuter une PowerShell commande sur les instances cibles.

Exemples de paramètre de condition préalable dans la version de schéma 2.2

La version de schéma 2.2 fournit le support multiplateforme. Cela signifie qu'au sein d'un même SSM document, vous pouvez spécifier différents systèmes d'exploitation pour différents plugins. Le support multiplateforme utilise le même paramètre precondition dans une étape, tel que décrit dans l'exemple suivant. Vous pouvez également utiliser le precondition paramètre pour valider les paramètres d'entrée que vous avez définis dans votre SSM document. Cela apparaît dans le second des exemples suivants.

Exemple de version de schéma 2.2 State Manager

Vous pouvez utiliser le SSM document suivant avec State Manager une fonctionnalité de Systems Manager pour télécharger et installer le logiciel antivirus ClamAV. State Managerapplique une configuration spécifique, ce qui signifie que chaque fois que l'State Managerassociation est exécutée, le système vérifie si le logiciel ClamAV est installé. Si tel n'est pas le cas, State Manager réexécute ce document.

Exemple d'inventaire de version de schéma 2.2

Vous pouvez utiliser le SSM document suivant State Manager pour collecter des métadonnées d'inventaire concernant vos instances.

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

Exemple de version de schéma 2.2 `AWS-ConfigureAWSPackage`

L'exemple suivant présente le document AWS-ConfigureAWSPackage. La section mainSteps inclut le plugin aws:configurePackage à l'étape action.

Note

Sur les systèmes d'exploitation Linux, seuls les packages AmazonCloudWatchAgent et AWSSupport-EC2Rescue sont pris en charge.

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

Version de schéma 1.2

L'exemple suivant présente les éléments supérieurs d'un document de version de schéma 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"
            }
         ]
      }
   }
}

Exemple de version de schéma 1.2 `aws:runShellScript`

L'exemple suivant montre le AWS-RunShellScript SSM document. La runtimeConfigsection inclut le 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 }}"
                }
            ]
        }
    }
}

Version de schéma 0.3

Éléments de niveau supérieur

L'exemple suivant montre les éléments de haut niveau d'un runbook d'automatisation de la version 0.3 du schéma au 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
        }
    }
}

YAMLExemple de runbook d'automatisation

L'exemple suivant montre le contenu d'un runbook d'automatisation, au YAML format. Cet exemple fonctionnel de la version 0.3 du schéma de document illustre également l'utilisation de Markdown pour formater les descriptions de documents.


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

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Composants de document

Éléments de données et paramètres

Schémas, fonctionnalités et exemples

Note

Utilisation du paramètre de condition préalable

Version de schéma 2.2

Éléments de niveau supérieur

Exemple de version de schéma 2.2

Exemples de paramètre de condition préalable dans la version de schéma 2.2

Exemple de version de schéma 2.2 State Manager

Exemple d'inventaire de version de schéma 2.2

Exemple de version de schéma 2.2 AWS-ConfigureAWSPackage

Note

Version de schéma 1.2

Exemple de version de schéma 1.2 aws:runShellScript

Version de schéma 0.3

Éléments de niveau supérieur

YAMLExemple de runbook d'automatisation

Exemple de version de schéma 2.2 `AWS-ConfigureAWSPackage`

Exemple de version de schéma 1.2 `aws:runShellScript`