• El panel de AWS Systems Manager CloudWatch dejará de estar disponible después del 30 de abril de 2026. Los clientes pueden seguir utilizando la consola de Amazon CloudWatch para ver, crear y administrar sus paneles de Amazon CloudWatch, tal y como lo hacen actualmente. Para obtener más información, consulte la [documentación del panel de Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html).
# Componentes del documento
Esta sección incluye información sobre los componentes de los documentos de SSM.
**Topics**
+ [Esquemas, características y ejemplos](documents-schemas-features.md)
+ [Elementos y parámetros de datos](documents-syntax-data-elements-parameters.md)
+ [Referencia de complementos del documento de comandos](documents-command-ssm-plugin-reference.md)
# Esquemas, características y ejemplos
AWS Systems ManagerLos documentos de (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](session-manager-schema.md).
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 | Details |
| --- | --- |
| 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. |
| Interpolación de parámetros | Interpolación significa insertar o sustituir un valor variable en una cadena. Es como rellenar un espacio en blanco con valores reales antes de usar la cadena. En el contexto de los documentos de SSM, la interpolación de parámetros permite interpolar los parámetros de cadena en las variables de entorno antes de la ejecución del comando, lo que proporciona una mayor seguridad contra las inyecciones de comandos. Cuando se establece en `ENV_VAR`, el agente crea una variable de entorno denominada `SSM_parameter-name` que contiene el valor del parámetro. |
**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](run-command-tutorial-update-software.md#rc-console-agentexample).
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) | Details |
| --- | --- | --- |
| 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. |
| propiedades | 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.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: A description of the document.
parameters:
parameter 1:
property 1: "value"
property 2: "value"
parameter 2:
property 1: "value"
property 2: "value"
mainSteps:
- action: Plugin name
name: A name for the step.
inputs:
input 1: "value"
input 2: "value"
input 3: "{{ parameter 1 }}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "A description of the document.",
"parameters": {
"parameter 1": {
"property 1": "value",
"property 2": "value"
},
"parameter 2":{
"property 1": "value",
"property 2": "value"
}
},
"mainSteps": [
{
"action": "Plugin name",
"name": "A name for the step.",
"inputs": {
"input 1": "value",
"input 2": "value",
"input 3": "{{ parameter 1 }}"
}
}
]
}
```
------
**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.
------
#### [ YAML ]
```
---
schemaVersion: "2.2"
description: "Example document"
parameters:
Message:
type: "String"
description: "Example parameter"
default: "Hello World"
allowedValues:
- "Hello World"
mainSteps:
- action: "aws:runPowerShellScript"
name: "example"
inputs:
timeoutSeconds: '60'
runCommand:
- "Write-Output {{Message}}"
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Example document",
"parameters": {
"Message": {
"type": "String",
"description": "Example parameter",
"default": "Hello World",
"allowedValues": ["Hello World"]
}
},
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "example",
"inputs": {
"timeoutSeconds": "60",
"runCommand": [
"Write-Output {{Message}}"
]
}
}
]
}
```
------
**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.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: cross-platform sample
mainSteps:
- action: aws:runPowerShellScript
name: PatchWindows
precondition:
StringEquals:
- platformType
- Windows
inputs:
runCommand:
- cmds
- action: aws:runShellScript
name: PatchLinux
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- cmds
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "cross-platform sample",
"mainSteps": [
{
"action": "aws:runPowerShellScript",
"name": "PatchWindows",
"precondition": {
"StringEquals": [
"platformType",
"Windows"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
},
{
"action": "aws:runShellScript",
"name": "PatchLinux",
"precondition": {
"StringEquals": [
"platformType",
"Linux"
]
},
"inputs": {
"runCommand": [
"cmds"
]
}
}
]
}
```
------
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
parameters:
action:
type: String
allowedValues:
- Install
- Uninstall
confirmed:
type: String
allowedValues:
- True
- False
mainSteps:
- action: aws:runShellScript
name: InstallAwsCLI
precondition:
StringEquals:
- "{{ action }}"
- "Install"
inputs:
runCommand:
- sudo apt install aws-cli
- action: aws:runShellScript
name: UninstallAwsCLI
precondition:
StringEquals:
- "{{ action }} {{ confirmed }}"
- "Uninstall True"
inputs:
runCommand:
- sudo apt remove aws-cli
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"parameters": {
"action": {
"type": "String",
"allowedValues": [
"Install",
"Uninstall"
]
},
"confirmed": {
"type": "String",
"allowedValues": [
true,
false
]
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "InstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }}",
"Install"
]
},
"inputs": {
"runCommand": [
"sudo apt install aws-cli"
]
}
},
{
"action": "aws:runShellScript",
"name": "UninstallAwsCLI",
"precondition": {
"StringEquals": [
"{{ action }} {{ confirmed }}",
"Uninstall True"
]
},
"inputs": {
"runCommand": [
"sudo apt remove aws-cli"
]
}
}
]
}
```
------
**Ejemplo de interpolación de la versión 2.2 del esquema con versiones de SSM Agent anteriores a la 3.3.2746.0**
En las versiones de SSM Agent anteriores a la 3.3.2746.0, el agente ignora el parámetro `interpolationType` y, en su lugar, realiza una sustitución de cadena sin procesar. Si hace referencia a `SSM_parameter-name` de forma explícita, debe configurarlo de forma explícita. En el siguiente ejemplo para Linux, se hace referencia explícita a la variable de entorno `SSM_Message`.
```
{
"schemaVersion": "2.2",
"description": "An example document",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern: "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"inputs": {
"runCommand": [
"if [ -z "${SSM_Message+x}" ]; then",
" export SSM_Message=\"{{Message}}\"",
"fi",
"",
"echo $SSM_Message"
]
}
}
}
```
**nota**
`allowedPattern` no es técnicamente obligatorio si un documento SSM no utiliza doble llave: `{{ }}`
**Ejemplo de la versión 2.2 del esquema State Manager**
Puede utilizar el siguiente documento de SSM con State Manager, una herramienta 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.
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: State Manager Bootstrap Example
parameters: {}
mainSteps:
- action: aws:runShellScript
name: configureServer
inputs:
runCommand:
- sudo yum install -y httpd24
- sudo yum --enablerepo=epel install -y clamav
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "State Manager Bootstrap Example",
"parameters": {},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "configureServer",
"inputs": {
"runCommand": [
"sudo yum install -y httpd24",
"sudo yum --enablerepo=epel install -y clamav"
]
}
}
]
}
```
------
**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 `AmazonCloudWatchAgent` y `AWSSupport-EC2Rescue`.
------
#### [ 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/al2023-ami-kernel-6.1-x86_64 }}
schemaVersion: '0.3'
assumeRole: 'arn:aws:iam::111122223333::role/AutomationServiceRole'
parameters:
imageId:
type: String
default: '{{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64 }}'
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.11
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.11
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
```
## Ejemplos de gestión segura de parámetros
Los siguientes ejemplos demuestran la gestión seguro de parámetros mediante una variable de entorno `interpolationType`.
### Ejecución básica de comandos de forma segura
En este ejemplo se muestra cómo gestionar de forma segura un parámetro de comando:
**nota**
`allowedPattern` no es técnicamente obligatorio en los documentos SSM que no utilizan doble llave: `{{ }}`
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: An example document.
parameters:
Message:
type: String
description: "Message to be printed"
default: Hello
interpolationType: ENV_VAR
allowedPattern: "^[^"]*$"
mainSteps:
- action: aws:runShellScript
name: printMessage
precondition:
StringEquals:
- platformType
- Linux
inputs:
runCommand:
- echo {{Message}}
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType": "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition": {
"StringEquals": ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}]
}
```
------
### Uso de parámetros en lenguajes interpretados
Este ejemplo demuestra la gestión segura de parámetros en Python:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Secure Python script execution'
parameters:
inputData:
type: String
description: 'Input data for processing'
interpolationType: 'ENV_VAR'
mainSteps:
- action: aws:runPowerShellScript
name: runPython
inputs:
runCommand:
- |
python3 -c '
import os
import json
# Safely access parameter through environment variable
input_data = os.environ.get("SSM_inputData", "")
# Process the data
try:
processed_data = json.loads(input_data)
print(f"Successfully processed: {processed_data}")
except json.JSONDecodeError:
print("Invalid JSON input")
'
```
------
### Ejemplo de compatibilidad con versiones anteriores
En este ejemplo se muestra cómo gestionar los parámetros de forma segura y mantener la compatibilidad con versiones anteriores:
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: 'Backwards compatible secure parameter handling'
parameters:
userInput:
type: String
description: 'User input to process'
interpolationType: 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: processInput
inputs:
runCommand:
- |
# Handle both modern and legacy agent versions
if [ -z "${SSM_userInput+x}" ]; then
# Legacy agent - fall back to direct parameter reference
export SSM_userInput="{{userInput}}"
fi
# Process the input securely
echo "Processing input: $SSM_userInput"
```
------
**nota**
`allowedPattern` no es técnicamente obligatorio en los documentos SSM que no utilizan doble llave: `{{ }}`
## Prácticas recomendadas de seguridad de parámetros
Siga estas prácticas recomendadas cuando gestione parámetros en documentos SSM:
+ **Utilice la interpolación de variables de entorno**: utilice siempre `interpolationType: "ENV_VAR"` para los parámetros de cadena que se utilizarán en la ejecución de comandos.
+ **Implemente la validación de entradas**: utilice `allowedPattern` para restringir los valores de los parámetros a patrones seguros.
+ **Gestione los sistemas heredados**: incluya una lógica alternativa para las versiones de SSM Agent anteriores que no admitan la interpolación de variables de entorno.
+ **Escape los caracteres especiales**: cuando utilice valores de parámetros en los comandos, escape correctamente los caracteres especiales para evitar que el intérprete de comandos los interprete.
+ **Limite el alcance de los parámetros**: utilice los patrones de parámetros más restrictivos posibles para su caso de uso.
# 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](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html) en la *Guía de introducción a la Consola de administración de AWS*.
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.
Para mejorar la seguridad al administrar los parámetros de cadena, puede utilizar la interpolación de variables de entorno si especifica la propiedad `interpolationType`. Cuando se establece en `ENV_VAR`, el sistema crea una variable de entorno denominada `SSM_parameter-name` que contiene el valor del parámetro.
A continuación se incluye un ejemplo de un parámetro que utiliza una variable de entorno `interpolationType`:
```
{
"schemaVersion": "2.2",
"description": "An example document.",
"parameters": {
"Message": {
"type": "String",
"description": "Message to be printed",
"default": "Hello",
"interpolationType" : "ENV_VAR",
"allowedPattern": "^[^"]*$"
}
},
"mainSteps": [{
"action": "aws:runShellScript",
"name": "printMessage",
"precondition" : {
"StringEquals" : ["platformType", "Linux"]
},
"inputs": {
"runCommand": [
"echo {{Message}}"
]
}
}
}
```
`allowedPattern` no es técnicamente obligatorio en los documentos SSM que no utilizan doble llave: `{{ }}`
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`.
```
---
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 }}"],
interpolationType : 'ENV_VAR'
allowedPattern: '^[^"]*$'
mainSteps:
- action: aws:runShellScript
name: runShellScriptDefaultParams
inputs:
runCommand:"{{ commands }}"
```
```
{
"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 }}"],
"interpolationType" : "ENV_VAR"
}
},
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runShellScriptDefaultParams",
"inputs": {
"runCommand": [
"{{ commands }}"
]
}
}
]
}
```
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](systems-manager-parameter-store.md).
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](#top-level-properties-type) 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](https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html) 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](https://pkg.go.dev/regexp) antes de procesar el documento.
------
#### [ YAML ]
```
InstanceId:
type: String
description: "(Required) The instance ID to target."
allowedPattern: "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$"
default: ''
```
------
#### [ JSON ]
```
"InstanceId": {
"type": "String",
"description": "(Required) The instance ID to target.",
"allowedPattern": "^i-(?:[a-f0-9]{8}|[a-f0-9]{17})$",
"default": ""
}
```
------
+ `displayType`: (Opcional) Se utiliza para mostrar `textfield` o `textarea` en la Consola de administración de AWS. `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.
+ `interpolationType`: (Opcional) Define cómo se procesan los valores de los parámetros antes de ejecutar el comando. Cuando se establece en `ENV_VAR`, el valor del parámetro está disponible como una variable de entorno denominada `SSM_parameter-name`. Esta característica ayuda a evitar la inyección de comandos al tratar los valores de los parámetros como cadenas literales.
Tipo: cadena
Valores válidos: `ENV_VAR`
Obligatorio: 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](automation-action-update-variable.md).
Tipo: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
Obligatorio: no
```
variables:
payload:
type: StringMap
default: "{}"
```
```
{
"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
Obligatorio: 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
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](automation-action-outputs-inputs.md).
Tipo: diccionario
Obligatorio: 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](automation-action-executeScript.md). 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](automation-document-script-considerations.md) y [Experiencia de diseño visual para manuales de procedimientos de automatización](automation-visual-designer.md).
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](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) en la referencia de la API de AWS Systems Manager.
```
---
files:
launch.py:
checksums:
sha256: 18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE
```
```
"files": {
"launch.py": {
"checksums": {
"sha256": "18871b1311b295c43d0f...[truncated]...772da97b67e99d84d342ef4aEXAMPLE"
}
}
}
```
Tipo: diccionario
Obligatorio: 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 de parámetro `type`.
Cadena
Una secuencia de cero o más caracteres Unicode escritos entre comillas. Por ejemplo, "i-1234567890abcdef0". Utilice barras diagonales invertidas para aplicar escape.
Los parámetros de cadena pueden incluir un campo opcional `interpolationType` con el valor `ENV_VAR` para permitir la interpolación de variables de entorno y mejorar la seguridad.
```
---
InstanceId:
type: String
description: "(Optional) The target EC2 instance ID."
interpolationType: ENV_VAR
```
```
"InstanceId":{
"type":"String",
"description":"(Optional) The target EC2 instance ID.",
"interpolationType": "ENV_VAR"
}
```
StringList
Una lista de elementos de cadena separados por comas. Por ejemplo, ["cd \$1", "pwd"].
```
---
commands:
type: StringList
description: "(Required) Specify a shell script or a command to run."
default: ""
minItems: 1
displayType: textarea
```
```
"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.
```
---
canRun:
type: Boolean
description: ''
default: true
```
```
"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".
```
---
timeout:
type: Integer
description: The type of action to perform.
default: 100
```
```
"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, \$1"Env": "Prod"\$1.
```
---
notificationConfig:
type: StringMap
description: The configuration for events to be notified about
default:
NotificationType: 'Command'
NotificationEvents:
- 'Failed'
NotificationArn: "$dependency.topicArn"
maxChars: 150
```
```
"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.
```
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
```
```
"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/](https://console.aws.amazon.com/systems-manager/).
1. En el panel de navegación, elija **Documentos**.
1. En el cuadro de búsqueda, seleccione **Tipo de documento** y, a continuación, seleccione **Comando**.
1. Elija el nombre de un documento y, a continuación, la pestaña **Contenido**.
1. 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\]](http://docs.aws.amazon.com/es_es/systems-manager/latest/userguide/images/view-document-content.png)
# Referencia de complementos del documento de comandos
Esta referencia describe los complementos que puede especificar en un documento de tipo de comandos de AWS Systems Manager (SSM). Estos complementos no se pueden utilizar en manuales de procedimientos de Automation, que utilizan acciones de automatización. Para obtener información acerca de las acciones de AWS Systems Manager Automation, consulte [Referencia de acciones de Automatización de Systems Manager](automation-actions.md).
Systems Manager determina las acciones que hay que realizar en una instancia administrada; para ello, lee el contenido de un documento de SSM. Cada documento incluye una sección de ejecución de código. En función de la versión de esquema de su documento, esta sección de ejecución de código puede incluir uno o más complementos o pasos. A efectos de este tema de ayuda, los complementos y los pasos se denominan *complementos*. En esta sección, se incluye información sobre cada uno de los complementos de Systems Manager. Para obtener más información sobre los documentos, incluida la información sobre la creación de documentos y las diferencias entre las versiones de esquema, consulte [Documentos de AWS Systems Manager](documents.md).
En el caso de los complementos que aceptan parámetros de cadena, como `aws:runShellScript` y `aws:runPowerShellScript`, el parámetro `interpolationType` se puede utilizar para mejorar la seguridad al tratar las entradas de los parámetros como cadenas literales en lugar de comandos potencialmente ejecutables. Por ejemplo:
```
{
"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 }}"],
"interpolationType" : "ENV_VAR"
}
},
//truncated
}
```
**nota**
Algunos de los complementos descritos aquí se ejecutan solo en instancias de Windows Server o Linux. Se indican las dependencias de la plataforma para cada complemento.
Los siguientes complementos de documentos se admiten en instancias Amazon Elastic Compute Cloud (Amazon EC2) para macOS:
`aws:refreshAssociation`
`aws:runShellScript`
`aws:runPowerShellScript`
`aws:softwareInventory`
`aws:updateSsmAgent`
**Topics**
+ [Entradas compartidas](#shared-inputs)
+ [`aws:applications`](#aws-applications)
+ [`aws:cloudWatch`](#aws-cloudWatch)
+ [`aws:configureDocker`](#aws-configuredocker)
+ [`aws:configurePackage`](#aws-configurepackage)
+ [`aws:domainJoin`](#aws-domainJoin)
+ [`aws:downloadContent`](#aws-downloadContent)
+ [`aws:psModule`](#aws-psModule)
+ [`aws:refreshAssociation`](#aws-refreshassociation)
+ [`aws:runDockerAction`](#aws-rundockeraction)
+ [`aws:runDocument`](#aws-rundocument)
+ [`aws:runPowerShellScript`](#aws-runPowerShellScript)
+ [`aws:runShellScript`](#aws-runShellScript)
+ [`aws:softwareInventory`](#aws-softwareinventory)
+ [`aws:updateAgent`](#aws-updateagent)
+ [`aws:updateSsmAgent`](#aws-updatessmagent)
## Entradas compartidas
Solo con la versión 3.0.502 y las versiones posteriores de SSM Agent, todos los complementos pueden utilizar las siguientes entradas:
**finallyStep**
El último paso que desea que ejecute el documento. Si esta entrada se define para un paso, tendrá prioridad sobre un valor `exit` especificado en las entradas `onFailure` o `onSuccess`. Para que un paso con esta entrada se ejecute como se espera, el paso debe ser el último definido en los `mainSteps` del documento.
Tipo: booleano
Valores válidos: `true` \$1 `false`
Obligatorio: no
**onFailure**
Si especifica esta entrada para un complemento con el valor `exit` y el paso falla, el estado del paso refleja el error, y el documento no ejecuta los pasos restantes a menos que se haya definido un `finallyStep`. Si especifica esta entrada para un complemento con el valor `successAndExit` y el paso falla, el estado del paso aparece como realizado correctamente y el documento no ejecuta los pasos restantes a menos que se haya definido un `finallyStep`.
Tipo: cadena
Valores válidos: `exit` \$1 `successAndExit`
Obligatorio: no
**onSuccess**
Si especifica esta entrada para un complemento y el paso se ejecuta correctamente, el documento no ejecutará los pasos restantes a menos que se haya definido un `finallyStep`.
Tipo: cadena
Valores válidos: `exit`
Obligatorio: no
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: Shared inputs example
parameters:
customDocumentParameter:
type: String
description: Example parameter for a custom Command-type document.
mainSteps:
- action: aws:runDocument
name: runCustomConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomDocument"
documentParameters: '"documentParameter":{{customDocumentParameter}}'
onSuccess: exit
- action: aws:runDocument
name: ifConfigurationFailure
inputs:
documentType: SSMDocument
documentPath: "yourCustomRepairDocument"
onFailure: exit
- action: aws:runDocument
name: finalConfiguration
inputs:
documentType: SSMDocument
documentPath: "yourCustomFinalDocument"
finallyStep: true
```
------
#### [ JSON ]
```
{
"schemaVersion": "2.2",
"description": "Shared inputs example",
"parameters": {
"customDocumentParameter": {
"type": "String",
"description": "Example parameter for a custom Command-type document."
}
},
"mainSteps":[
{
"action": "aws:runDocument",
"name": "runCustomConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomDocument",
"documentParameters": "\"documentParameter\":{{customDocumentParameter}}",
"onSuccess": "exit"
}
},
{
"action": "aws:runDocument",
"name": "ifConfigurationFailure",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomRepairDocument",
"onFailure": "exit"
}
},
{
"action": "aws:runDocument",
"name":"finalConfiguration",
"inputs": {
"documentType": "SSMDocument",
"documentPath": "yourCustomFinalDocument",
"finallyStep": true
}
}
]
}
```
------
## `aws:applications`
Instalar, reparar o desinstalar aplicaciones en una instancia de EC2. Este complemento solo se ejecuta en los sistemas operativos Windows Server.
### Sintaxis
#### Esquema 2.2
------
#### [ YAML ]
```
---
schemaVersion: '2.2'
description: aws:applications plugin
parameters:
source:
description: "(Required) Source of msi."
type: String
mainSteps:
- action: aws:applications
name: example
inputs:
action: Install
source: "{{ source }}"
```
------
#### [ JSON ]
```
{
"schemaVersion":"2.2",
"description":"aws:applications",
"parameters":{
"source":{
"description":"(Required) Source of msi.",
"type":"String"
}
},
"mainSteps":[
{
"action":"aws:applications",
"name":"example",
"inputs":{
"action":"Install",
"source":"{{ source }}"
}
}
]
}
```
------
#### Esquema 1.2
------
#### [ YAML ]
```
---
runtimeConfig:
aws:applications:
properties:
- id: 0.aws:applications
action: "{{ action }}"
parameters: "{{ parameters }}"
source: "{{ source }}"
sourceHash: "{{ sourceHash }}"
```
------
#### [ JSON ]
```
{
"runtimeConfig":{
"aws:applications":{
"properties":[
{
"id":"0.aws:applications",
"action":"{{ action }}",
"parameters":"{{ parameters }}",
"source":"{{ source }}",
"sourceHash":"{{ sourceHash }}"
}
]
}
}
}
```
------
### Propiedades
**acción**
La acción que hay que realizar.
Tipo: enumeración
Valores válidos: `Install` \$1 `Repair` \$1 `Uninstall`
Obligatorio: sí
**parameters**
Los parámetros para el instalador.
Tipo: cadena
Requerido: no
**origen**
La URL del archivo `.msi` para la aplicación.
Tipo: cadena
Obligatorio: sí
**sourceHash**
Hash SHA256 del archivo `.msi`.
Tipo: cadena
Requerido: no
## `aws:cloudWatch`
Exportar datos desde Windows Server a Amazon CloudWatch o los Registros de Amazon CloudWatch y monitorear los datos mediante las métricas de CloudWatch. Este complemento solo se ejecuta en los sistemas operativos Windows Server. Para obtener más información sobre cómo configurar la integración de CloudWatch con Amazon Elastic Compute Cloud (Amazon EC2), consulte [Recopilación de métricas, registros y seguimientos con el agente de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) en la *Guía del usuario de Amazon CloudWatch*.
**importante**
El agente unificado de CloudWatch ha sustituido a SSM Agent como herramienta para enviar datos de registro a los Registros de Amazon CloudWatch. El complemento aws:cloudWatch del SSM Agent no es compatible. Recomendamos utilizar solo el agente de CloudWatch unificado para sus procesos de recopilación de registros. Para obtener más información, consulte los temas siguientes:
[Envío de registros de nodos a los Registros de CloudWatch (agente de CloudWatch) unificado](monitoring-cloudwatch-agent.md)
[Migrar la recopilación de registros del nodo de Windows Server al agente de CloudWatch](monitoring-cloudwatch-agent.md#monitoring-cloudwatch-agent-migrate)
[Recopilación de métricas, registros y seguimientos con el agente de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) en la *Guía del usuario de Amazon CloudWatch*.
Puede exportar y monitorizar los siguientes tipos de datos:
**ApplicationEventLog**
Envía datos de registro de eventos de aplicación a los Registros de CloudWatch.
**CustomLogs**
Envía cualquier archivo de registro basado en texto a los Registros de Amazon CloudWatch. El complemento de CloudWatch crea una huella digital para archivos de registro. El sistema asocia, a continuación, un desplazamiento de datos con cada huella digital. El complemento carga archivos cuando hay cambios, registra el desplazamiento y asocia el desplazamiento con una huella digital. Este método se utiliza para evitar una situación en la que un usuario activa el complemento, asocia el servicio con un directorio que contiene un gran número de archivos y el sistema carga todos los archivos.
Tenga en cuenta que si la aplicación trunca o intenta limpiar registros durante el sondeo, cualquier registro especificado para `LogDirectoryPath` pueden perder entradas. Si, por ejemplo, desea limitar el tamaño de los archivos de registro, cree un nuevo archivo de registro cuando se alcance el límite y, a continuación, continúe escribiendo datos en el nuevo archivo.
**ETW**
Envía datos de Seguimiento de eventos para Windows (ETW) a los Registros de CloudWatch.
**IIS**
Envía datos de registro de IIS a los Registros de CloudWatch.
**PerformanceCounter**
Envía contadores de rendimiento de Windows a CloudWatch. Puede seleccionar diferentes categorías para cargar a CloudWatch como métricas. Para cada contador de rendimiento que desee cargar, cree una sección **PerformanceCounter** con un ID único (por ejemplo, "PerformanceCounter2", "PerformanceCounter3", etc.) y configure sus propiedades.
Si se detiene el SSM Agent de AWS Systems Manager o el complemento de CloudWatch, los datos del contador de rendimiento no se registran en CloudWatch. Este comportamiento es distinto de los registros personalizados o de los registros de eventos de Windows. Estos registros mantienen los datos de contador de rendimiento y los cargan a CloudWatch después de que el SSM Agent o el complemento de CloudWatch estén disponibles.
**SecurityEventLog**
Envía datos de registro de eventos de seguridad a los Registros de CloudWatch.
**SystemEventLog**
Envía datos de registro de eventos de sistema a los Registros de CloudWatch.
Puede definir los siguientes destinos para los datos:
**CloudWatch**
El destino al que se envían los datos de las métricas del contador de rendimiento. Puede añadir más secciones con ID únicos (por ejemplo, "CloudWatch2", "CloudWatch3", etc.) y especificar una región diferente para cada ID nuevo para enviar los mismos datos a diferentes ubicaciones.
**CloudWatchLogs**
El destino al que se envían los datos de registro. Puede añadir más secciones con ID únicos (por ejemplo, "CloudWatchLogs2", "CloudWatchLogs3", etc.) y especificar una región diferente para cada ID nuevo para enviar los mismos datos a diferentes ubicaciones.
### Sintaxis
```
"runtimeConfig":{
"aws:cloudWatch":{
"settings":{
"startType":"{{ status }}"
},
"properties":"{{ properties }}"
}
}
```
### Configuración y propiedades
**AccessKey**
ID de clave de acceso. Esta propiedad es necesaria a menos que lanzara su instancia utilizando un rol de IAM. Esta propiedad no se puede utilizar con SSM.
Tipo: cadena
Requerido: no
**CategoryName**
La categoría de contador de rendimiento de Performance Monitor.
Tipo: cadena
Obligatorio: sí
**CounterName**
El nombre del contador de rendimiento de Performance Monitor.
Tipo: cadena
Obligatorio: sí
**CultureName**
La configuración regional en la que se registra la marca temporal. Si **CultureName** está en blanco, se usa de forma predeterminada la misma configuración regional que utiliza su instancia de Windows Server.
Tipo: cadena
Valores válidos: para obtener una lista de los valores admitidos, consulte el tema [National Language Support (NLS) API Reference [Referencia de la API de compatibilidad con el idioma nacional (NLS)]](https://msdn.microsoft.com/en-us/library/cc233982.aspx) en el sitio web de Microsoft. No se admiten los valores **div**, **div-MV**, **hu** ni **hu-HU**.
Obligatorio: no
**DimensionName**
Una dimensión para la métrica de Amazon CloudWatch. Si especifica `DimensionName`, también debe especificar `DimensionValue`. Estos parámetros ofrecen otra vista al enumerar las métricas. Puede utilizar la misma dimensión para varias métricas, lo que le permite ver todas las métricas que pertenezcan a una dimensión concreta.
Tipo: cadena
Requerido: no
**DimensionValue**
Un valor de dimensión para la métrica de Amazon CloudWatch.
Tipo: cadena
Requerido: no
**Codificación**
La codificación del archivo que se va a utilizar (por ejemplo, UTF-8). Utilice el nombre de codificación, no el nombre de visualización.
Tipo: cadena
Valores válidos: para obtener una lista de los valores admitidos, consulte [Clase Encoding](https://learn.microsoft.com/en-us/dotnet/api/system.text.encoding?view=net-7.0) en la biblioteca de Microsoft Learn.
Obligatorio: sí
**Filtro**
El prefijo de los nombres de registro. Deje en blanco este parámetro para monitorear todos los archivos.
Tipo: cadena
Valores válidos: para obtener una lista de los valores admitidos, consulte el tema [Propiedad FileSystemWatcherFilter](http://msdn.microsoft.com/en-us/library/system.io.filesystemwatcher.filter.aspx) en la biblioteca de MSDN.
Obligatorio: no
**Flujos**
Cada tipo de datos que se va a cargar, junto con el destino de los datos (CloudWatch o Registros de CloudWatch). Por ejemplo, para enviar un contador de rendimiento definido bajo `"Id": "PerformanceCounter"` al destino de CloudWatch definido bajo `"Id": "CloudWatch"`, escriba **“PerformanceCounter,CloudWatch”**. Del mismo modo, para enviar el registro personalizado, el registro de ETW y el registro del sistema al destino de los Registros de CloudWatch definido bajo `"Id": "ETW"`, escriba **“(ETW),CloudWatchLogs”**. Además, puede enviar el mismo contador de rendimiento o archivo de registro a más de un destino. Por ejemplo, para enviar el registro de la aplicación a dos destinos diferentes definidos bajo `"Id": "CloudWatchLogs"` y `"Id": "CloudWatchLogs2"`, escriba **"ApplicationEventLog,(CloudWatchLogs, CloudWatchLogs2)"**.
Tipo: cadena
Valores válidos (origen): `ApplicationEventLog` \$1 `CustomLogs` \$1 `ETW` \$1 `PerformanceCounter` \$1 `SystemEventLog` \$1 `SecurityEventLog`
Los valores válidos (destino): `CloudWatch` \$1 `CloudWatchLogs` \$1 `CloudWatch`*n* \$1 `CloudWatchLogs`*n*
Obligatorio: sí
**FullName**
El nombre completo del componente.
Tipo: cadena
Obligatorio: sí
**Id**
Identifica el origen o el destino de los datos. Este identificador deberá ser único dentro del archivo de configuración.
Tipo: cadena
Obligatorio: sí
**InstanceName**
El nombre de la instancia del contador de rendimiento. No utilice un asterisco (\$1) para indicar todas las instancias, porque cada componente de contador de rendimiento solo admite una métrica. Puede, sin embargo utilizar **\$1Total**.
Tipo: cadena
Obligatorio: sí
**Niveles**
Tipos de mensajes para enviar a Amazon CloudWatch.
Tipo: cadena
Valores válidos:
+ **1** - solo los mensajes de error cargados.
+ **2** - solo los mensajes de advertencia cargados.
+ **4** - solo los mensajes de información cargados.
Puede agregar valores juntos para incluir más de un tipo de mensaje. Por ejemplo, **3** significa que se incluyen mensajes de error (**1**) y mensajes de advertencia (**2**). El valor **7** significa que se incluyen mensajes de error (**1**), mensajes de advertencia (**2**) y mensajes informativos (**4**).
Obligatorio: sí
Los registros de seguridad de Windows deben establecer los niveles en 7.
**LineCount**
El número de líneas del encabezado para identificar el archivo de registro. Por ejemplo, los archivos de registros de IIS tienen encabezados prácticamente idénticos. Puede especificar **3**, que leería las tres primeras líneas del encabezado del archivo de registro para identificarlo. En los archivos de registro de IIS, la tercera línea es la marca de fecha y hora, que es distinta entre los archivos de registro.
Tipo: entero
Obligatorio: no
**LogDirectoryPath**
Para CustomLogs, escriba la ruta donde se almacenan registros en la instancia de EC2. Para los registros de IIS, la carpeta en la que se almacenan los registros de IIS para un sitio individual (por ejemplo, **C:\$1\$1inetpub\$1\$1logs\$1\$1LogFiles\$1\$1W3SVC*n***). Para los registros de IIS, solo se admite el formato de registro W3C. No se admiten los formatos IIS, NCSA y personalizados.
Tipo: cadena
Obligatorio: sí
**LogGroup**
El nombre de su grupo de registro. Este nombre se muestra en la pantalla **Grupos de registros** en la consola de CloudWatch.
Tipo: cadena
Obligatorio: sí
**LogName**
El nombre del archivo de registro.
1. Para encontrar el nombre del registro, en Visor de eventos, en el panel de navegación, seleccione **Registros de aplicaciones y servicios**.
1. En la lista de registros, haga clic con el botón derecho en el registro que desea cargar (por ejemplo, `Microsoft` > `Windows` > `Backup` > `Operational`) y, a continuación, seleccione **Crear vista personalizada**.
1. En el cuadro de diálogo **Create Custom View**, seleccione la pestaña **XML**. **LogName** se encuentra en la etiqueta