Amazon EC2 Systems Manager
用户指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Systems Manager Automation 操作

Systems Manager Automation 会执行 Automation 文档中定义的步骤。每步都与特定操作相关。此操作确定本步的输入、行为和输出。步骤定义在 Automation 文档的 mainSteps 部分。Automation 支持以下操作:

  • aws:changeInstanceState:更改实例的状态。

  • aws:copyImage:将 AMI 从任何区域复制到当前区域中。此操作还可以对新的 AMI 进行加密。

  • aws:createImage:根据正在运行的实例创建 AMI。

  • aws:createStack:从模板创建新 AWS CloudFormation 堆栈。

  • aws:createTags:为 Amazon EC2 实例或 Systems Manager 管理的实例创建新标签。

  • aws:deleteImage:删除 AMI。

  • aws:deleteStack:删除 AWS CloudFormation 堆栈。

  • aws:invokeLambdaFunction:使您能够在自动化工作流中运行外部工作线程函数。

  • aws:runCommand:执行远程命令。

  • aws:runInstances:启动一个或多个实例。

  • aws:sleep:将 Automation 执行时间延迟指定的时间。

您无需指定操作或步骤的输出。由与本步关联的操作预先确定输出。当您在 Automation 文档中指定步骤输入时,可以引用前面某步中的一个或多个输出。例如,您可以使 aws:runInstances 的输出可用于后续的 aws:runCommand 操作。还可以在 Automation 文档的 Output 部分引用前面步骤中的输出。

所有操作中的常见属性

以下属性是所有操作的常见属性:

Copy
"mainSteps": [ { "name": "name", "action": "action", "maxAttempts": value, "timeoutSeconds": value, "onFailure": "Abort", "inputs": { ... } }, { "name": "name", "action": "action", "maxAttempts": value, "timeoutSeconds": value, "onFailure": "Abort", "inputs": { ... } } ]
name

在文档的所有步骤名称中必须唯一的标识符。

类型:字符串

必需:是

action

步骤要执行的操作的名称。

类型:字符串

必需:是

maxAttempts

在发生故障的情况下应重试步骤的次数。如果值大于 1,则直到所有重试尝试失败后,才会将此步骤视为失败。默认值是 1。

类型:整数

必需:否

timeoutSeconds

步骤的执行超时值。如果超时并且 maxAttempts 的值大于 1,则本步未考虑超时,直至已尝试所有重试。此字段没有默认值。

类型:整数

必需:否

onFailure

指示工作流是否应在发生失败时继续。默认为在发生失败时中止。

类型:字符串

有效值:Abort | Continue

必需:否

inputs

特定于操作的属性。

类型:映射

必需:是

aws:changeInstanceState

更改或断言实例的状态。

此操作可在断言模式下使用 (不要执行 API 来更改状态,而应验证实例是否处于预期状态。)要使用断言模式,请将 CheckStateOnly 参数设置为 true。当在 Windows 上运行 Sysprep 命令时,此模式很有用。该命令是一种可在后台长时间运行的异步命令。您可以确保在创建 AMI 之前停止实例。

输入

Copy
{ "name":"stopMyInstance", "action": "aws:changeInstanceState", "maxAttempts": 3, "timeoutSeconds": 3600, "onFailure": "Abort", "inputs": { "InstanceIds": ["i-1234567890abcdef0"], "CheckStateOnly": true, "DesiredState": "stopped" } }
InstanceIds

实例的 ID。

类型:字符串

必需:是

CheckStateOnly

如果为 false,请将实例状态设置为预期状态。如果为 true,请使用轮询断言预期状态。

类型:布尔值

必需:否

DesiredState

预期状态。

类型:字符串

有效值:running | stopped | terminated

必需:是

Force

如果设置此项,则强制停止实例。则该实例没有机会来刷新文件系统缓存或文件系统元数据。如果您使用此选项,则必须执行文件系统检查和修复流程。 我们不建议将该选项用于 Windows 实例。

类型:布尔值

必需:否

AdditionalInfo

预留。

类型:字符串

必需:否

输出

aws:copyImage

将 AMI 从任何区域复制到当前区域中。此操作还可以对新的 AMI 进行加密。

输入

此操作支持大多数 CopyImage 参数。有关更多信息,请参阅 CopyImage

以下示例在首尔地区创建 AMI 的副本 (SourceImageID:ami-0fe10819。SourceRegion: ap-northeast-2). 新的 AMI 将复制到您启动 Automation 操作的区域。将对复制的 AMI 进行加密,因为可选 Encrypted 标记将设置为 true

Copy
{ "name": "createEncryptedCopy", "action": "aws:copyImage", "maxAttempts": 3, "onFailure": "Abort", "inputs": { "SourceImageId": "ami-0fe10819", "SourceRegion": "ap-northeast-2", "ImageName": "Encrypted Copy of LAMP base AMI in ap-northeast-2", "Encrypted": true } }
SourceRegion

源 AMI 当前所在的区域。

类型:字符串

必需:是

SourceImageId

要从源区域复制的 AMI ID。

类型:字符串

必需:是

ImageName

新映像的名称。

类型:字符串

必需:是

ImageDescription

目标映像的描述。

类型:字符串

必需:否

加密

对目标 AMI 进行加密。

类型:布尔值

必需:否

KmsKeyId

在复制操作期间对映像快照进行加密时要使用的 AWS Key Management Service CMK 的完整 Amazon 资源名称 (ARN)。有关更多信息,请参阅 CopyImage

类型:字符串

必需:否

ClientToken

您为确保请求幂等性而提供的唯一、区分大小写的标识符。有关更多信息,请参阅 CopyImage

类型:字符串

必需:否

输出

ImageId

已复制映像的 ID。

ImageState

已复制映像的状态。

有效值:available | pending | failed

aws:createImage

从已停止的实例创建新 AMI。

重要

该操作不会隐式停止实例。您必须使用 aws:changeInstanceState 操作来停止实例。如果针对正在运行的实例使用此操作,则生成的 AMI 可能存在缺陷。

输入

此操作支持大多数 CreateImage 参数。有关更多信息,请参阅 CreateImage

Copy
{ "name": "createMyImage", "action": "aws:createImage", "maxAttempts": 3, "onFailure": "Abort", "inputs": { "InstanceId": "i-1234567890abcdef0", "ImageName": "AMI Created on{{global:DATE_TIME}}", "NoReboot": true, "ImageDescription": "My newly created AMI" } }
实例 ID

实例的 ID。

类型:字符串

必需:是

ImageName

映像的名称。

类型:字符串

必需:是

ImageDescription

映像的描述。

类型:字符串

必需:否

NoReboot

一种布尔文本。

类型:布尔值

必需:否

BlockDeviceMappings

适用于实例的块储存设备。

类型:映射

必需:否

输出

ImageId

新建映像的 ID。

ImageState

作为字符串文本值提供的执行脚本。如果输入文本值,则必须为 Base64 编码。

必需:否

aws:createStack

从模板创建新 AWS CloudFormation 堆栈。

输入

Copy
{ "name": "makeStack", "action": "aws:createStack", "maxAttempts": 1, "onFailure": "Abort", "inputs": { "Capabilities": [ "CAPABILITY_IAM" ], "StackName": "myStack", "TemplateURL": "http://s3.amazonaws.com/mybucket/myStackTemplate", "TimeoutInMinutes": 5 } }
功能

必须在 AWS CloudFormation 可以创建某些堆栈之前指定的值列表。一些堆栈模板中包含的资源会影响您的 AWS 账户中的权限。例如,创新新 AWS Identity and Access Management (IAM) 用户会影响您账户中的权限。对于这些堆栈,您必须通过指定此参数来明确确认它们的功能。

有效值仅为 CAPABILITY_IAMCAPABILITY_NAMED_IAM。以下资源要求您指定此参数。

如果您的堆栈模板包含这些资源,我们建议您查看与之关联的所有权限并在必要时编辑其权限。

如果包含 IAM 资源,您可以指定任意一个功能。如果包含具有自定义名称的 IAM 资源,则必须指定 CAPABILITY_NAMED_IAM。如果您不指定此参数,则此操作会返回 InsufficientCapabilities 错误。

有关更多信息,请参阅确认 AWS CloudFormation 模板中的 IAM 资源

类型:字符串的数组

有效值:CAPABILITY_IAM | CAPABILITY_NAMED_IAM

必需:否

DisableRollback

如果堆栈创建失败,请设置为 true 以禁用堆栈回滚。

Conditional:您可以指定 DisableRollback 参数或 OnFailure 参数,但不能同时指定。

默认值:false

类型:布尔值

必需:否

NotificationARNs

用于发布堆栈相关事件的 Amazon SNS 主题 ARN。您可以使用 Amazon SNS 控制台 https://console.amazonaws.cn/sns/v2/home 找到 SNS 主题 ARN。

类型:字符串的数组

数组成员:最多 5 项。

必需:否

OnFailure

如果堆栈创建失败,确定要执行的操作。您必须指定 DO_NOTHINGROLLBACKDELETE

Conditional:您可以指定 OnFailure 参数或 DisableRollback 参数,但不能同时指定。

默认值:ROLLBACK

类型:字符串

有效值: DO_NOTHING | ROLLBACK | DELETE

必需:否

参数

指定堆栈输入参数的 Parameter 结构列表。有关更多信息,请参阅参数数据类型。

类型:参数对象数组

必需:否

ResourceTypes

您有权用于此创建堆栈操作的模板资源类型。例如,AWS::EC2::InstanceAWS::EC2::*Custom::MyCustomInstance。使用以下语法描述模板资源类型。

  • 对于所有 AWS 资源:

    AWS::*
  • 对于所有自定义资源:

    Custom::*
  • 对于指定自定义资源:

    Custom::logical_ID
  • 对于特定 AWS 服务中的所有资源:

    AWS::service_name::*
  • 对于指定 AWS 资源:

    AWS::service_name::resource_logical_ID

如果资源类型列表不包括您创建的资源,那么堆栈创建将会失败。默认情况下,AWS CloudFormation 对所有资源类型授予权限。IAM 将此参数用于 IAM 策略中 AWS CloudFormation 特定的条件密钥。有关更多信息,请参阅使用 AWS Identity and Access Management 控制访问权限

类型:字符串的数组

长度约束:最小长度为 1。长度上限为 256。

必需:否

RoleARN

AWS CloudFormation 创建堆栈所代入的 IAM 角色的 Amazon 资源名称 (ARN)。AWS CloudFormation 使用该角色的凭证以您的名义进行调用。AWS CloudFormation 针对堆栈的所有未来操作始终使用此角色。只要用户有权对堆栈进行操作,AWS CloudFormation 会使用此角色,即使用户无权传递它。确保该角色授予最少的权限。

如果您不指定值,则 AWS CloudFormation 会使用之前与堆栈关联的角色。如果角色不可用,则 AWS CloudFormation 会使用您的用户凭证生成的一个临时会话。

类型:字符串

长度约束:最小长度为 20。长度上限为 2048。

必需:否

StackName

与堆栈关联的名称。名称在您创建堆栈的区域中必须是唯一的。

注意

堆栈名称只能包含字母数字字符(区分大小写)和连字符。该名称必须以字母字符开头,且不得超过 128 个字符。

类型:字符串

必需:是

StackPolicyBody

包含堆栈策略正文的结构。有关更多信息,请参阅防止更新堆栈资源

Conditional:您可以指定 StackPolicyBody 参数或 StackPolicyURL 参数,但不能同时指定。

类型:字符串

长度约束:最小长度为 1。长度上限为 16384。

必需:否

StackPolicyURL

包含堆栈策略的文件的位置。URL 指向的策略必须位于与堆栈处于同一区域的 Amazon S3 存储桶中。堆栈策略允许的最大文件大小为 16 KB。

Conditional:您可以指定 StackPolicyBody 参数或 StackPolicyURL 参数,但不能同时指定。

类型:字符串

长度约束:最小长度为 1。长度上限为 1350。

必需:否

Tags

与此堆栈关联的键值对。AWS CloudFormation 还可以将这些标签传播到堆栈中创建的资源。您可以指定最多 10 个标签。

类型:标签对象数组

必需:否

TemplateBody

包含最小长度为 1 字节、最大长度为 51,200 字节的模板正文的结构。有关更多信息,请参阅模板剖析

Conditional:您可以指定 TemplateBody 参数或 TemplateURL 参数,但不能同时指定。

类型:字符串

长度约束:最小长度为 1。

必需:否

TemplateURL

包含模板正文的文件的位置。URL 必须指向一个位于 Amazon S3 存储桶中的模板。模板允许的最大大小为 460,800 字节。有关更多信息,请参阅模板剖析

Conditional:您可以指定 TemplateBody 参数或 TemplateURL 参数,但不能同时指定。

类型:字符串

长度约束:最小长度为 1。长度上限为 1024。

必需:否

TimeoutInMinutes

堆栈状态变为 CREATE_FAILED 前允许经过的时间。如果未设置 DisableRollback 或将其设置为 false,堆栈将被回滚。

类型:整数

有效范围:最小值为 1。

必需:否

输出

堆栈 ID

堆栈的唯一标识符。

类型:字符串

StackStatus

堆栈的当前状态。

类型:字符串

有效值:CREATE_IN_PROGRESS | CREATE_FAILED | CREATE_COMPLETE | ROLLBACK_IN_PROGRESS | ROLLBACK_FAILED | ROLLBACK_COMPLETE | DELETE_IN_PROGRESS | DELETE_FAILED | DELETE_COMPLETE | UPDATE_IN_PROGRESS | UPDATE_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_COMPLETE | UPDATE_ROLLBACK_IN_PROGRESS | UPDATE_ROLLBACK_FAILED | UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_ROLLBACK_COMPLETE | REVIEW_IN_PROGRESS

必需:是

StackStatusReason

与堆栈状态相关联的成功或失败消息。

类型:字符串

必需:否

有关更多信息,请参阅 CreateStack

安全考虑因素

您必须将以下策略分配给 IAM Automation 代入角色,才可以使用 aws:createStack 操作。有关代入角色的更多信息,请参阅任务 2:为 Automation 创建 IAM 角色

Copy
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "sqs:*", "cloudformation:CreateStack", "cloudformation:DescribeStacks" ], "Resource":"*" } ] }

aws:createTags

为 Amazon EC2 实例或 Systems Manager 托管实例创建新标签。

输入

此操作支持大多数 EC2 CreateTags 和 SSM AddTagsToResource 参数。有关更多信息,请参阅 CreateTagsAddTagsToResource

以下示例说明如何为 AMI 和实例添加标签以作为特定部门的生产资源。

Copy
{ "name": "createTags", "action": "aws:createTags", "maxAttempts": 3, "onFailure": "Abort", "inputs": { "ResourceType": "EC2", "ResourceIds": [ "ami-9a3768fa", "i-02951acd5111a8169" ], "Tags": [ { "Key": "production", "Value": "" }, { "Key": "department", "Value": "devops" } ] } }
ResourceIds

要为其添加标签的资源的 ID。如果资源类型不是“EC2”,则此字段只能包含单个项目。

类型:字符串列表

必需:是

Tags

要与资源关联的标签。

类型:映射列表

必需:是

ResourceType

要为其添加标签的资源的类型。如果未提供,则使用默认值“EC2”。

类型:字符串

必需:否

有效值: EC2 | ManagedInstance | MaintenanceWindow | Parameter

输出

aws:deleteImage

删除指定映像和所有的相关快照。

输入

此操作仅支持一个参数。有关更多信息,请参阅 DeregisterImageDeleteSnapshot 的相关文档。

Copy
{ "name": "deleteMyImage", "action": "aws:deleteImage", "maxAttempts": 3, "timeoutSeconds": 180, "onFailure": "Abort", "inputs": { "ImageId": "ami-12345678" } }
ImageId

要删除的映像的 ID。

类型:字符串

必需:是

输出

aws:deleteStack

删除 AWS CloudFormation 堆栈。

输入

Copy
{ "name":"deleteStack", "action":"aws:deleteStack", "maxAttempts":1, "onFailure":"Abort", "inputs":{ "StackName":"{{stackName}}" } }
ClientRequestToken

DeleteStack 请求的唯一标识符。如果您计划重试请求以便 AWS CloudFormation 知道您未在尝试删除同名堆栈,请指定此令牌。您可以重试 DeleteStack 请求以验证 AWS CloudFormation 是否收到了它们。

类型:字符串

长度约束:最小长度为 1。长度上限为 128。

模式:[a-zA-Z][-a-zA-Z0-9]*

必需:否

RetainResources.member.N

此输入仅适用于处于 DELETE_FAILED 状态的堆栈。您想要保留的资源的逻辑资源 ID 的列表。在删除时,AWS CloudFormation 删除堆栈,但不删除保留资源。

如果无法删除某个资源 (例如非空 Amazon S3 存储桶),但需要删除堆栈,则保留资源会很有用。

类型:字符串的数组

必需:否

RoleARN

AWS CloudFormation 创建堆栈所代入的 IAM 角色的 Amazon 资源名称 (ARN)。AWS CloudFormation 使用该角色的凭证以您的名义进行调用。AWS CloudFormation 针对堆栈的所有未来操作始终使用此角色。只要用户有权对堆栈进行操作,AWS CloudFormation 会使用此角色,即使用户无权传递它。确保该角色授予最少的权限。

如果您不指定值,则 AWS CloudFormation 会使用之前与堆栈关联的角色。如果角色不可用,则 AWS CloudFormation 会使用您的用户凭证生成的一个临时会话。

类型:字符串

长度约束:最小长度为 20。长度上限为 2048。

必需:否

StackName

与堆栈关联的名称或唯一堆栈 ID。

类型:字符串

必需:是

安全考虑因素

您必须将以下策略分配给 IAM Automation 代入角色,才可以使用 aws:deleteStack 操作。有关代入角色的更多信息,请参阅任务 2:为 Automation 创建 IAM 角色

Copy
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[ "sqs:*", "cloudformation:DeleteStack", "cloudformation:DescribeStacks" ], "Resource":"*" } ] }

aws:invokeLambdaFunction

调用指定的 Lambda 函数。

输入

此操作支持 Lambda 服务的大多数调用参数。有关更多信息,请参阅调用

Copy
{ "name": "invokeMyLambdaFunction", "action": "aws:invokeLambdaFunction", "maxAttempts": 3, "timeoutSeconds": 120, "onFailure": "Abort", "inputs": { "FunctionName": "MyLambdaFunction" } }
FunctionName

Lambda 函数的名称。此函数必须存在。

类型:字符串

必需:是

限定词

函数版本或别名。

类型:字符串

必需:否

InvocationType

调用类型。默认为 RequestResponse

类型:字符串

有效值:Event | RequestResponse | DryRun

必需:否

LogType

如果 Tail,调用类型必须为 RequestResponse。AWS Lambda 返回 Lambda 函数生成的采用 base64 编码的最后 4 KB 日志数据。

类型:字符串

有效值:None | Tail

必需:否

ClientContext

特定于客户端的信息。

必需:否

Payload

您的 Lambda 函数的 JSON 输入。

必需:否

输出

StatusCode

函数执行状态代码。

FunctionError

指示执行 Lambda 函数时是否出现错误。如果出现错误,则此字段将显示 HandledUnhandledHandled 错误由函数报告。Unhandled 错误由 AWS Lambda 检测和报告。

LogResult

Lambda 函数调用的 base64 编码日志。只有在调用类型为 RequestResponse 并且请求了日志时,才存在日志。

Payload

Lambda 函数返回的对象的 JSON 表示形式。只有在调用类型为 RequestResponse 时才存在有效负载。

aws:runCommand

运行指定的命令。

输入

此操作支持大多数 send command 参数。有关更多信息,请参阅 SendCommand

Copy
{ "name": "installPowerShellModule", "action": "aws:runCommand", "inputs": { "DocumentName": "AWS-InstallPowerShellModule", "InstanceIds": ["i-1234567890abcdef0"], "Parameters": { "source": "https://my-s3-url.com/MyModule.zip ", "sourceHash": "ASDFWER12321WRW" } } }
DocumentName

Run Command 文档的名称。

类型:字符串

必需:是

InstanceIds

实例的 ID。

类型:字符串

必需:是

参数

文档中指定的必需参数和可选参数。

类型:映射

必需:否

评论

有关此命令的用户定义的信息。

类型:字符串

必需:否

DocumentHash

文档的哈希。

类型:字符串

必需:否

DocumentHashType

哈希的类型。

类型:字符串

有效值:Sha256 | Sha1

必需:否

NotificationConfig

用于发送通知的配置。

必需:否

OutputS3BucketName

命令执行响应的 S3 存储桶的名称。

类型:字符串

必需:否

OutputS3KeyPrefix

前缀。

类型:字符串

必需:否

ServiceRoleArn

IAM 角色的 ARN。

类型:字符串

必需:否

TimeoutSeconds

run-command 超时值 (以秒为单位)。

类型:整数

必需:否

aws:runInstances

启动新实例。

输入

此操作支持大多数 API 参数。有关更多信息,请参阅 RunInstances API 文档。

Copy
{ "name": "launchInstance", "action": "aws:runInstances", "maxAttempts": 3, "timeoutSeconds": 1200, "onFailure": "Abort", "inputs": { "ImageId": "ami-12345678", "InstanceType": "t2.micro", "MinInstanceCount": 1, "MaxInstanceCount": 1, "IamInstanceProfileName": "myRunCmdRole" } }
ImageId

Amazon 系统映像 (AMI) 的 ID。

必需:是

InstanceType

实例的类型。

必需:否

MinInstanceCount

要启动的实例的最小数量。

必需:否

MaxInstanceCount

要启动的实例的最大数量。

必需:否

AdditionalInfo

预留。

必需:否

BlockDeviceMappings

适用于实例的块储存设备。

必需:否

ClientToken

用于确保请求的幂等性的标识符。

必需:否

DisableApiTermination

启用或禁用实例 API 终止

必需:否

EbsOptimized

启用或禁用 EBS 优化。

必需:否

IamInstanceProfileArn

实例的 IAM 实例配置文件的 ARN。

必需:否

IamInstanceProfileName

实例的 IAM 实例配置文件的名称。

必需:否

InstanceInitiatedShutdownBehavior

指示此实例是否在系统关闭时停止或终止。

必需:否

KernelId

内核的 ID。

必需:否

KeyName

密钥对的名称。

必需:否

监控

启动或禁用详细监控。

必需:否

NetworkInterfaces

网络接口。

必需:否

Placement

实例的置放。

必需:否

PrivateIpAddress

主要 IPv4 地址。

必需:否

RamdiskId

RAM 磁盘的 ID。

必需:否

SecurityGroupIds

实例的安全组的 ID。

必需:否

SecurityGroups

实例的安全组的名称。

必需:否

SubnetId

子网 ID。

必需:否

UserData

作为字符串文本值提供的执行脚本。如果输入文本值,则必须为 Base64 编码。

必需:否

输出

InstanceIds

实例的 ID。

aws:sleep

将 Automation 执行时间延迟指定的时间。此操作使用国际标准化组织 (ISO) 8601 日期和时间格式。有关此日期和时间格式的更多信息,请参阅 ISO 8601

输入

可将执行时间延迟指定的时间。

Copy
{ "name":"sleep", "action":"aws:sleep", "inputs":{ "Duration":"PT10M" } }

还可以将执行时间延迟到指定日期和时间。如果指定日期和时间已过,操作将立即执行。

Copy
{ "name": "sleep", "action": "aws:sleep", "inputs": { "Timestamp": "2020-01-01T01:00:00Z" } }

注意

Automation 当前支持的最大延迟为 604800 秒 (7 天)。

Duration

ISO 8601 持续时间。您不能指定负数持续时间。

类型:字符串

必需:否

时间戳

ISO 8601 时间戳。如果您没有为此参数指定值,那么必须为 Duration 参数指定一个值。

类型:字符串

必需:否

输出