Versión de esquema 2.2 Versión de esquema 1.2 Versión de esquema 0.3

Esquemas, características y ejemplos

Los documentos de AWS Systems Manager (SSM) utilizan las siguientes versiones de esquema.

Los documentos del tipo Command pueden utilizar la versión de esquema 1.2, 2.0 y 2.2. Si utiliza documentos de esquema 1.2, le recomendamos que cree documentos que utilicen la versión de esquema 2.2.
Los documentos del tipo Policy deben utilizar la versión de esquema 2.0 o posterior.
Los documentos del tipo Automation deben utilizar la versión de esquema 0.3.
Los documentos del tipo Session deben utilizar la versión de esquema 1.0.
Puede crear documentos en JSON o YAML.

Para obtener más información acerca del esquema del documento de Session, consulte Esquema del documento de Session.

Si utiliza la versión de esquema más reciente para los documentos de tipo Command y Policy, puede aprovechar las siguientes características.

Características de los documentos con la versión de esquema 2.2
Característica	Detalles
Edición de documentos	Ahora los documentos pueden actualizarse. Con la versión 1.2, cualquier actualización de un documento requería guardarlo con otro nombre.
Control de versiones automático	Cualquier actualización de un documento crea una versión nueva. No es una versión de esquema, sino una versión del documento.
Versión predeterminada	Si tiene varias versiones de un documento, puede especificar qué versión es el documento predeterminado.
Secuenciación	Los complementos o los pasos de un documento se ejecutan en el orden especificado.
Compatibilidad multiplataforma	La compatibilidad multiplataforma le permite especificar diferentes sistemas operativos para distintos complementos dentro del mismo documento de SSM. La compatibilidad multiplataforma utiliza el parámetro `precondition` dentro de un paso.

nota

El AWS Systems Manager SSM Agent de las instancias debe mantenerse actualizado con la versión más reciente para poder utilizar las características nuevas de Systems Manager y las características del documento de SSM. Para obtener más información, consulte Actualización de SSM Agent mediante Run Command.

La siguiente tabla enumera las diferencias entre las versiones de esquema principales.

Versión 1.2	Versión 2.2 (versión más reciente)	Detalles
runtimeConfig	mainSteps	En la versión 2.2, la sección `mainSteps` sustituye a la `runtimeConfig`. La sección `mainSteps` permite a Systems Manager ejecutar los pasos de forma secuencial.
properties	inputs	En la versión 2.2, la sección `inputs` sustituye la sección `properties`. La sección `inputs` acepta parámetros en los pasos.
comandos	runCommand	En la versión 2.2, la sección `inputs` toma el parámetro `runCommand` en lugar del parámetro `commands`.
id	acción	En la versión 2.2, `Action` sustituye a `ID`. Se trata tan solo de un cambio de nombre.
no se usa	name	En la versión 2.2, `name` es cualquier nombre definido por el usuario para un paso.

Uso del parámetro precondition

Con la versión de esquema 2.2 o posterior, puede utilizar el parámetro precondition para especificar el sistema operativo de destino de cada complemento o para validar los parámetros de entrada que definió en su documento de SSM. El parámetro precondition admite hacer referencia a los parámetros de entrada de su documento de SSM, y platformType utilizando los valores de Linux, MacOS, y Windows. Solo el operador StringEquals es compatible.

En el caso de documentos que utilizan la versión de esquema 2.2 o posterior, si no se especifica precondition, cada complemento se ejecuta u omite en función de la compatibilidad del complemento con el sistema operativo. La compatibilidad de los complementos con el sistema operativo se evalúa antes de precondition. En el caso de los documentos que utilizan el esquema 2.0 o anterior, los complementos incompatibles generarán un error.

Por ejemplo, en un documento con la versión de esquema 2.2, si no se especifica precondition y se incluye el complemento aws:runShellScript, el paso se ejecuta en las instancias de Linux, pero el sistema lo omite en las instancias de Windows Server, ya que aws:runShellScript no es compatible con las instancias de Windows Server. Sin embargo, en el caso de un documento con versión de esquema 2.0, si especifica el complemento aws:runShellScript y, a continuación, ejecuta el documento en una instancia de Windows Server, se produce un error en la ejecución. Puede ver un ejemplo del parámetro de condición previa en un documento de SSM más adelante en esta sección.

Versión de esquema 2.2

Elementos de nivel superior

En el siguiente ejemplo, se muestran los elementos de nivel superior de un documento de SSM que utiliza la versión 2.2 del esquema.

Ejemplo de la versión 2.2 del esquema

En el ejemplo siguiente, se utiliza el complemento aws:runPowerShellScript para ejecutar un comando de PowerShell en las instancias de destino.

Ejemplos del parámetro de condición previa de una versión de esquema 2.2

La versión de esquema 2.2 ofrece compatibilidad multiplataforma. Esto significa que dentro de un mismo documento de SSM puede especificar diferentes sistemas operativos para distintos complementos. La compatibilidad multiplataforma utiliza el parámetro precondition dentro de un paso, tal y como se muestra en el siguiente ejemplo. También puede utilizar el parámetro precondition para validar los parámetros de entrada que haya definido en el documento de SSM. Puede ver esto en el segundo caso de los siguientes ejemplos.

Ejemplo de la versión 2.2 del esquema State Manager

Puede utilizar el siguiente documento de SSM con State Manager, una capacidad de Systems Manager, para descargar e instalar el software antivirus ClamAV. State Manager aplica una configuración específica, lo que significa que cada vez que se ejecuta la asociación de State Manager, el sistema comprueba si el software ClamAV está instalado. En caso contrario, State Manager vuelve a ejecutar este documento.

Ejemplo de inventario con la versión 2.2 del esquema

Puede utilizar el siguiente documento de SSM con State Manager para recopilar metadatos de inventario de las instancias.

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

Ejemplo de la versión 2.2 del esquema `AWS-ConfigureAWSPackage`

El siguiente ejemplo muestra el documento de AWS-ConfigureAWSPackage. La sección mainSteps incluye el complemento aws:configurePackage en el paso action.

nota

En sistemas operativos Linux, solo son compatibles los paquetes AWSSupport-EC2Rescue y AmazonCloudWatchAgent.

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

Versión de esquema 1.2

El siguiente ejemplo muestra los elementos de nivel superior de un documento con la versión de esquema 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"
            }
         ]
      }
   }
}

Ejemplo de la versión 1.2 del esquema `aws:runShellScript`

El siguiente ejemplo muestra el documento de SSM AWS-RunShellScript. La sección runtimeConfig incluye el complemento 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 }}"
                }
            ]
        }
    }
}

Versión de esquema 0.3

Elementos de nivel superior

El siguiente ejemplo muestra los elementos de nivel superior de un manual de procedimientos de automatización con la versión de esquema 0.3 o posterior en 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
        }
    }
}

Ejemplo de manual de procedimientos de automatización YAML

En el siguiente ejemplo, se muestra el contenido de un manual de procedimientos de automatización en formato YAML. Este ejemplo de trabajo de la versión 0.3 del esquema del documento también demuestra el uso de Markdown para dar formato a las descripciones del documento.


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Componentes del documento

Elementos y parámetros de datos

Esquemas, características y ejemplos

nota

Uso del parámetro precondition

Versión de esquema 2.2

Elementos de nivel superior

Ejemplo de la versión 2.2 del esquema

Ejemplos del parámetro de condición previa de una versión de esquema 2.2

Ejemplo de la versión 2.2 del esquema State Manager

Ejemplo de inventario con la versión 2.2 del esquema

Ejemplo de la versión 2.2 del esquema AWS-ConfigureAWSPackage

nota

Versión de esquema 1.2

Ejemplo de la versión 1.2 del esquema aws:runShellScript

Versión de esquema 0.3

Elementos de nivel superior

Ejemplo de manual de procedimientos de automatización YAML

Ejemplo de la versión 2.2 del esquema `AWS-ConfigureAWSPackage`

Ejemplo de la versión 1.2 del esquema `aws:runShellScript`