Versão 2.2 do esquema Versão 1.2 do esquema Versão 0.3 do esquema

Esquemas, atributos e exemplos

Os documentos do AWS Systems Manager (SSM) usam as versões de esquema a seguir.

Os documentos do tipo Command podem usar o esquema versão 1.2, 2.0 e 2.2. Se você usa documentos do esquema 1.2, recomendamos criar documentos que utilizem o esquema versão 2.2.
Os documentos do tipo Policy devem usar o esquema versão 2.0 ou posterior.
Os documentos do tipo Automation devem usar o esquema versão 0.3.
Os documentos do tipo Session devem usar o esquema versão 1.0.
Você pode criar documentos em JSON ou YAML.

Para obter mais informações sobre o esquema de documentos do Session, consulte Esquema do documento de sessão.

Ao usar a versão de esquema mais recentes para documentos Command e Policy, você poderá aproveitar os seguintes recursos.

Recursos de documentos da versão 2.2 do esquema
Atributo	Detalhes
Edição de documentos	Agora, documentos podem ser atualizados. Com a versão 1.2, qualquer atualização de um documento exigia que você o salvasse com um nome diferente.
Versionamento automático	Qualquer atualização de um documento cria uma nova versão. Esta não é uma versão de esquema, mas uma versão do documento.
Versão padrão	Se você possui várias versões de um documento, pode especificar qual delas é o documento padrão.
Sequenciamento	Os plugins ou as etapas em um documento são executados na ordem que você especificou.
Suporte entre plataformas	O suporte entre plataformas permite que você especifique diferentes sistemas operacionais para diferentes plugins dentro do mesmo documento do SSM. O suporte entre plataformas usa o parâmetro `precondition` dentro de uma etapa.

nota

Você deve manter o AWS Systems Manager SSM Agent atualizado em suas instâncias com a versão mais recente para usar os novos recursos do Systems Manager e os recursos de documento do SSM. Para ter mais informações, consulte Atualização do SSM Agent por meio de Run Command.

A tabela a seguir lista as diferenças entre as principais versões de esquema.

Versão 1.2	Versão 2.2 (versão mais recente)	Detalhes
runtimeConfig	mainSteps	Na versão 2.2, a seção `mainSteps` substitui `runtimeConfig`. O`mainSteps`A seção permite que o Systems Manager execute etapas em sequência.
propriedades	inputs	Na versão 2.2, a seção `inputs` substitui a seção `properties`. A seção `inputs` aceita parâmetros para as etapas.
comandos	runCommand	Na versão 2.2, a seção `inputs` usa o parâmetro `runCommand` em vez do parâmetro `commands`.
id	ação	Na versão 2.2, `Action` substitui `ID`. Esta é apenas uma mudança de nome.
não aplicável	name	Na versão 2.2, `name` é um nome definido pelo usuário para uma etapa.

Usar o parâmetro precondition

Com o esquema versão 2.2 ou superior, você pode usar o parâmetro precondition para especificar o sistema operacional de destino de cada plugin ou para validar parâmetros de entrada que você definiu em seu documento do SSM. Opreconditionsuporta referenciar os parâmetros de entrada do documento SSM, eplatformTypeusando valores deLinux,MacOS, eWindows. Somente aStringEqualsé suportado.

Para documentos que utilizam o esquema versão 2.2 ou posterior, se a precondition não for especificada, cada plugin será executado ou ignorado com base na compatibilidade do plugin com o sistema operacional. Compatibilidade de plugins com o sistema operacional é avaliada antes doprecondition. Para documentos que utilizam o esquema 2.0 ou anterior, os plugins incompatíveis geram um erro.

Por exemplo, em um documento com a versão 2.2 do esquema, se precondition não for especificado e o plugin aws:runShellScript estiver relacionado, a etapa será executada em instâncias do Linux, mas será ignorada pelo sistema em instâncias do Windows Server porque o aws:runShellScript não é compatível com instâncias do Windows Server. No entanto, para um documento de esquema versão 2.0, se você especificar o plugin aws:runShellScript e depois executar o documento em instâncias do Windows Server, a execução falhará. Você poderá ver um exemplo do parâmetro de pré-condição em um documento do SSM ainda nesta seção.

Versão 2.2 do esquema

Elementos de nível superior

O exemplo a seguir mostra os elementos de nível superior de um documento do SSM usando o esquema versão 2.2.

Exemplo de esquema versão 2.2 do

Veja como o exemplo a seguir usa o plugin aws:runPowerShellScript para executar um comando do PowerShell nas instâncias de destino.

Exemplos do parâmetro precondition da versão 2.2 do esquema

O esquema versão 2.2 fornece suporte para várias plataformas. Isso significa que, dentro de um único documento do SSM, você pode especificar diferentes sistemas operacionais para diferentes plugins. O suporte entre plataformas usa o parâmetro precondition dentro de uma etapa, como mostra o exemplo a seguir. Você também pode usar opreconditionpara validar os parâmetros de entrada definidos no documento do SSM. Veja isso no segundo exemplo a seguir.

Exemplo de esquema versão 2.2 do State Manager

Você pode usar o seguinte documento do SSM com o State Manager, um recurso do Systems Manager para baixar e instalar o software antivírus ClamAV. O State Manager impõe uma configuração específica, o que significa que cada vez que a associação do State Manager for executada, o sistema verificará se o software ClamAV está instalado. Se não, o State Manager executa novamente esse documento.

Exemplo de inventário do esquema versão 2.2

Você pode usar o documento SSM a seguir com o State Manager para coletar metadados de inventário sobre suas instâncias.

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

Exemplo de esquema versão 2.2 do `AWS-ConfigureAWSPackage`

O exemplo a seguir mostra o documento AWS-ConfigureAWSPackage. OmainStepsInclui a seçãoaws:configurePackageplugin noactionEtapa.

nota

Nos sistemas operacionais Linux, somente os pacotes AmazonCloudWatchAgent e AWSSupport-EC2Rescue são suportados.

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

Versão 1.2 do esquema

O exemplo a seguir mostra os elementos de nível superior de um documento do esquema versão 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"
            }
         ]
      }
   }
}

Exemplo de esquema versão 1.2 do `aws:runShellScript`

O exemplo a seguir mostra oAWS-RunShellScriptDocumento do MUS do. A seção runtimeConfig inclui o plugin aws:runShellScript.


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

Versão 0.3 do esquema

Elementos de nível superior

O exemplo a seguir mostra os elementos de nível superior de um runbook do Automation versão 0.3 do esquema no formato JSON.


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

Exemplo de runbook de automação YAML

O exemplo a seguir mostra o conteúdo de um runbook do Automation, no formato YAML. Este exemplo funcional da versão 0.3 do esquema do documento também demonstra o uso do Markdown para formatar descrições de documentos.


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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Componentes do documento

Elementos e parâmetros de dados

Esquemas, atributos e exemplos

nota

Usar o parâmetro precondition

Versão 2.2 do esquema

Elementos de nível superior

Exemplo de esquema versão 2.2 do

Exemplos do parâmetro precondition da versão 2.2 do esquema

Exemplo de esquema versão 2.2 do State Manager

Exemplo de inventário do esquema versão 2.2

Exemplo de esquema versão 2.2 do AWS-ConfigureAWSPackage

nota

Versão 1.2 do esquema

Exemplo de esquema versão 1.2 do aws:runShellScript

Versão 0.3 do esquema

Elementos de nível superior

Exemplo de runbook de automação YAML

Exemplo de esquema versão 2.2 do `AWS-ConfigureAWSPackage`

Exemplo de esquema versão 1.2 do `aws:runShellScript`