Elementos y parámetros de datos - AWS Systems Manager
Elementos de datos de nivel superiorEjemplos del parámetro type en documentos de SSMVisualización del contenido del documento de Command de SSM

Elementos y parámetros de datos

En este tema se describen los elementos de datos que se utilizan en los documentos de SSM. La versión del esquema utilizada para crear un documento define la sintaxis y los elementos de datos que el documento acepta. Se recomienda utilizar la versión de esquema 2.2 o una versión posterior para los documentos de Command. Los manuales de procedimientos de Automation utilizan la versión de esquema 0.3. Asimismo, los manuales de procedimientos de Automation admiten el uso de Markdown, un lenguaje de marcado que le permite agregar descripciones de estilo wiki a documentos y pasos individuales dentro del documento. Para obtener más información acerca del uso de Markdown, consulte Uso de Markdown en la consola en la Guía de introducción a la AWS Management Console.

En la siguiente sección se describen los elementos de datos que puede incluir en un documento de SSM.

Elementos de datos de nivel superior

schemaVersion

La versión de esquema que utilizar.

Tipo: versión

Obligatorio: sí

description

La información que proporciona para describir el propósito del documento. También puede utilizar este campo para determinar si un parámetro requiere un valor para que se ejecute un documento o si es opcional proporcionar un valor para el parámetro. En los ejemplos de este tema, se pueden ver los parámetros obligatorios y opcionales.

Tipo: cadena

Requerido: no

parameters

Una estructura que define los parámetros que acepta el documento.

En el caso de los parámetros que usa con frecuencia, le recomendamos que los almacene en Parameter Store, una herramienta de AWS Systems Manager. A continuación, puede definir parámetros en el documento que hagan referencia a los parámetros de Parameter Store como su valor predeterminado. Para hacer referencia a un parámetro de Parameter Store, utilice la sintaxis siguiente. 

{{ssm:parameter-name}}

Puede utilizar un parámetro que haga referencia a un parámetro de Parameter Store igual que haría con cualquier otro parámetro de documentos. En el siguiente ejemplo, el valor predeterminado del parámetro commands es el parámetro myShellCommands de Parameter Store. Al especificar el parámetro commands como una cadena runCommand, el documento ejecuta los comandos almacenados en el parámetro myShellCommands.

YAML
---
schemaVersion: '2.2'
description: runShellScript with command strings stored as Parameter Store parameter
parameters:
  commands:
    type: StringList
    description: "(Required) The commands to run on the instance."
    default: ["{{ ssm:myShellCommands }}"]
mainSteps:
- action: aws:runShellScript
  name: runShellScriptDefaultParams
  inputs:
    runCommand:"{{ commands }}"
JSON
{
    "schemaVersion": "2.2",
    "description": "runShellScript with command strings stored as Parameter Store parameter",
    "parameters": {
      "commands": {
        "type": "StringList",
        "description": "(Required) The commands to run on the instance.",
        "default": ["{{ ssm:myShellCommands }}"]
      }
    },
    "mainSteps": [
      {
        "action": "aws:runShellScript",
        "name": "runShellScriptDefaultParams",
        "inputs": {
            "runCommand": [
              "{{ commands }}"
          ]
        }
      }
    ]
  }
nota

Puede hacer referencia a los parámetros de String y StringList de Parameter Store en la sección parameters del documento. No puede hacer referencia a los parámetros SecureString de Parameter Store.

Para obtener más información acerca de Parameter Store, consulte AWS Systems Manager Parameter Store.

Tipo: estructura

La estructura parameters acepta los siguientes campos y valores:

  • type: (Obligatorio) Entre los valores permitidos se incluyen los siguientes: String, StringList, Integer Boolean, MapList y StringMap. Para ver ejemplos de cada tipo, consulte Ejemplos del parámetro type en documentos de SSM en la siguiente sección.

    nota

    Los documentos de tipo comando solo admiten los tipos de parámetros String y StringList.

  • description: (Opcional) Una descripción del parámetro.

  • default: (Opcional) El valor predeterminado del parámetro o una referencia a un parámetro en Parameter Store.

  • allowedValues: (Opcional) Una matriz de valores permitidos para el parámetro. La definición de valores permitidos para el parámetro valida la entrada del usuario. Si un usuario introduce un valor que no está permitido, la ejecución no se iniciará.

    YAML
    DirectoryType:
  type: String
  description: "(Required) The directory type to launch."
  default: AwsMad
  allowedValues:
  - AdConnector
  - AwsMad
  - SimpleAd
    JSON
    "DirectoryType": {
  "type": "String",
  "description": "(Required) The directory type to launch.",
  "default": "AwsMad",
  "allowedValues": [
    "AdConnector",
    "AwsMad",
    "SimpleAd"
  ]
}

  • allowedPattern: (Opcional) Una expresión regular que valida si la entrada del usuario coincide con el patrón definido para el parámetro. Si la entrada del usuario no coincide con el patrón permitido, la ejecución no se iniciará.

    nota

    Systems Manager realiza dos validaciones para allowedPattern. La primera validación se lleva a cabo utilizando la Biblioteca regex de Java en el nivel de API cuando usa un documento. La segunda validación se lleva a cabo en SSM Agent mediante el uso de la Biblioteca regex antes de procesar el documento.

    YAML
    InstanceId:
  type: String
  description: "(Required) The instance ID to target."
  allowedPattern: "^i-[a-z0-9]{8,17}$"
  default: ''
    JSON
    "InstanceId": {
  "type": "String",
  "description": "(Required) The instance ID to target.",
  "allowedPattern": "^i-[a-z0-9]{8,17}$",
  "default": ""
}

  • displayType: (Opcional) Se utiliza para mostrar textfield o textarea en la AWS Management Console. textfield es un cuadro de texto de línea única. textarea es un área de texto multilínea.

  • minItems: (Opcional) El número mínimo de elementos permitidos.

  • maxItems: (Opcional) El número máximo de elementos permitidos.

  • minChars: (Opcional) El número mínimo de caracteres del parámetro permitidos.

  • maxChars: (Opcional) El número máximo de caracteres del parámetro permitidos.

Requerido: no

variables

(Solo en la versión 0.3 del esquema) Valores a los que puede hacer referencia o actualizar a lo largo de los pasos de un manual de procedimientos de automatización. Las variables son similares a los parámetros, pero difieren de forma muy importante. Los valores de los parámetros son estáticos en el contexto de un manual de procedimientos, pero los valores de las variables se pueden cambiar en el contexto del manual de procedimientos. Al actualizar el valor de una variable, el tipo de datos debe coincidir con el tipo de datos definido. Para obtener información sobre la actualización de los valores de las variables en una automatización, consulte aws:updateVariable — Actualiza el valor de una variable del manual de procedimientos.

Tipo: Boolean | Integer | MapList | String | StringList | StringMap

Requerido: no

YAML
variables:
    payload:
        type: StringMap
        default: "{}"
JSON
{
    "variables": [
        "payload": {
            "type": "StringMap",
            "default": "{}"
        }
    ]
}
runtimeConfig

(Versión de esquema 1.2 solamente) La configuración de la instancia aplicada por uno o varios complementos de Systems Manager. No se garantiza que los complementos se ejecuten en secuencia.

Tipo: diccionario<cadena,PluginConfiguration>

Requerido: no

mainSteps

(Solo versiones de esquema 0.3, 2.0 y 2.2) Un objeto que puede incluir varios pasos (complementos). Los complementos se definen en pasos. Los pasos se ejecutan en orden secuencial según se indica en el documento.

Tipo: diccionario<cadena,PluginConfiguration>

Obligatorio: sí

salidas

(Solo versión de esquema 0.3) Datos generados por la ejecución de este documento que puede utilizarse en otros procesos. Por ejemplo, si el documento crea una nueva AMI, puede especificar “CreateImage.ImageId” como valor de salida y, a continuación, utilizar este resultado para crear nuevas instancias en una ejecución de automatización posterior. Para obtener más información acerca de las salidas, consulte Uso de salidas de acción como entradas.

Tipo: diccionario<cadena,OutputConfiguration>

Requerido: no

files

(Solo versión de esquema 0.3) Los archivos de script (y sus sumas de comprobación) están asociados al documento y se ejecutan durante una ejecución de automatización. Solo se aplica a los documentos que incluyen la acción aws:executeScript y para los que se han especificado datos adjuntos en uno o más pasos.

Para obtener más información sobre los tiempos de ejecución compatibles con los manuales de procedimientos de Automatización, consulte aws:executeScript: ejecutar un script. Para obtener más información acerca de la inclusión de secuencias de comandos en documentos de Automation, consulte Uso de scripts en manuales de procedimientos y Experiencia de diseño visual para manuales de procedimientos de automatización.

Cuando se crea un manual de procedimientos de automatización con datos adjuntos, también se deben especificar los archivos de los datos adjuntos mediante la opción --attachments (para AWS CLI) o Attachments (para API y SDK). Puede especificar la ubicación del archivo para los archivos y los documentos de SSM almacenados en buckets de Amazon Simple Storage Service (Amazon S3). Para obtener más información, consulte Attachments en la referencia de la API de AWS Systems Manager.

YAML
---
files:
  launch.py:
    checksums:
      sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
JSON
"files": {
    "launch.py": {
        "checksums": {
            "sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
        }
    }
}

Tipo: diccionario<cadena,FilesConfiguration>

Requerido: no

Ejemplos del parámetro type en documentos de SSM

Los tipos de parámetros de los documentos de SSM son estáticos. Esto significa que el tipo de parámetro no se puede cambiar después de definirlo. Cuando se utilizan parámetros con complementos de documentos de SSM, el tipo de parámetro no se puede cambiar dinámicamente dentro de la entrada de un complemento. Por ejemplo, no se puede hacer referencia a un parámetro Integer dentro de la entrada runCommand del complemento aws:runShellScript porque esta entrada acepta una cadena o lista de cadenas. Para utilizar un parámetro para una entrada de un complemento, el tipo de parámetro debe coincidir con el tipo aceptado. Por ejemplo, debe especificar un parámetro de tipo Boolean para la entrada allowDowngrade del complemento aws:updateSsmAgent. Si el tipo de parámetro no coincide con el tipo de entrada de un complemento, el documento de SSM no se valida y el sistema no crea el documento. Esto también es cierto cuando se utilizan parámetros posteriores dentro de entradas para otros complementos o acciones de AWS Systems Manager automatización. Por ejemplo, no puede hacer referencia a un parámetro StringList dentro de la entrada documentParameters del complemento aws:runDocument. La entrada documentParameters acepta un mapa de cadenas incluso si el tipo de parámetro posterior de documento de SSM es un parámetro StringList y coincide con el parámetro al que está haciendo referencia.

Cuando se utilizan parámetros con acciones de Automation, los tipos de parámetros no se validan cuando se crea el documento de SSM en la mayoría de los casos. Solo cuando se utiliza la acción aws:runCommand se validan los tipos de parámetros cuando crea el documento de SSM. En todos los demás casos, la validación de parámetros se produce durante la ejecución de la automatización cuando se verifica la entrada de una acción antes de ejecutar la acción. Por ejemplo, si el parámetro de entrada es String y hace referencia a él como el valor de la entrada MaxInstanceCount de la acción aws:runInstances, se crea el documento de SSM. Sin embargo, al ejecutar el documento, la automatización produce un error al validar la acción aws:runInstances porque la entrada MaxInstanceCount requiere un valor Integer.

A continuación, se incluyen ejemplos de cada type de parámetro.

Cadena

Una secuencia de cero o más caracteres Unicode escritos entre comillas. Por ejemplo, "i-1234567890abcdef0". Utilice barras diagonales invertidas para aplicar escape.

YAML
---
InstanceId:
  type: String
  description: "(Optional) The target EC2 instance ID."
JSON
"InstanceId":{
  "type":"String",
  "description":"(Optional) The target EC2 instance ID."
}
StringList

Una lista de elementos de cadena separados por comas. Por ejemplo, ["cd ~", "pwd"].

YAML
---
commands:
  type: StringList
  description: "(Required) Specify a shell script or a command to run."
  default: ""
  minItems: 1
  displayType: textarea
JSON
"commands":{
  "type":"StringList",
  "description":"(Required) Specify a shell script or a command to run.",
  "minItems":1,
  "displayType":"textarea"
}
Booleano

Admite solo true o false. No admite “true” o 0.

YAML
---
canRun:
  type: Boolean
  description: ''
  default: true
JSON
"canRun": {
  "type": "Boolean",
  "description": "",
  "default": true
}
Entero

Números enteros. No acepta números decimales, por ejemplo 3,14159 ni números escritos entre comillas, por ejemplo "3".

YAML
---
timeout:
  type: Integer
  description: The type of action to perform.
  default: 100
JSON
"timeout": {
  "type": "Integer",
  "description": "The type of action to perform.",
  "default": 100    
}
StringMap

Un mapeo de claves a valores. Las claves y los valores deben ser cadenas. Por ejemplo, {"Env": "Prod"}.

YAML
---
notificationConfig:
  type: StringMap
  description: The configuration for events to be notified about
  default:
    NotificationType: 'Command'
    NotificationEvents:
    - 'Failed'
    NotificationArn: "$dependency.topicArn"
  maxChars: 150
JSON
"notificationConfig" : {
  "type" : "StringMap",
  "description" : "The configuration for events to be notified about",
  "default" : {
    "NotificationType" : "Command",
    "NotificationEvents" : ["Failed"],
    "NotificationArn" : "$dependency.topicArn"
  },
  "maxChars" : 150
}
MapList

Una lista de objetos StringMap.

YAML
blockDeviceMappings:
  type: MapList
  description: The mappings for the create image inputs
  default:
  - DeviceName: "/dev/sda1"
    Ebs:
      VolumeSize: "50"
  - DeviceName: "/dev/sdm"
    Ebs:
      VolumeSize: "100"
  maxItems: 2
JSON
"blockDeviceMappings":{
  "type":"MapList",
  "description":"The mappings for the create image inputs",
  "default":[
    {
      "DeviceName":"/dev/sda1",
      "Ebs":{
        "VolumeSize":"50"
      }
    },
    {
      "DeviceName":"/dev/sdm",
      "Ebs":{
        "VolumeSize":"100"
      }
    }
  ],
  "maxItems":2
}

Visualización del contenido del documento de Command de SSM

Para tener una vista previa de los parámetros necesarios y opcionales para un documento de AWS Systems Manager (SSM) Command, además de las acciones que ejecuta, puede ver el contenido del documento en la consola de Systems Manager.

Para ver el contenido del documento de SSM Command

  1. Abra la consola de AWS Systems Manager en https://console.aws.amazon.com/systems-manager/.

  2. En el panel de navegación, elija Documentos.

  3. En el cuadro de búsqueda, seleccione Tipo de documento y, a continuación, seleccione Comando.

  4. Elija el nombre de un documento y, a continuación, la pestaña Contenido.

  5. En el campo de contenido, revise los parámetros disponibles y los pasos de acción para el documento.

    Por ejemplo, en la siguiente imagen se muestra que (1) version y 2 allowDowngrade son parámetros opcionales para el documento AWS-UpdateSSMAgent y que la primera acción ejecutada por el documento es (3) aws:updateSsmAgent.

    Ver el contenido del documento de SSM en la consola de Systems Manager