Automation system variables - AWS Systems Manager

Automation system variables

Systems Manager Automation runbooks use the following variables. For an example of how these variables are used, view the JSON source of the AWS-UpdateWindowsAmi runbook.

To view the JSON source of the AWS-UpdateWindowsAmi runbook

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Documents.

  3. In the document list, use either the Search bar or the numbers to the right of the Search bar to choose the runbook AWS-UpdateWindowsAmi.

  4. Choose the Content tab.

System Variables

Automation runbooks currently support the following system variables.

Variable Details

global:ACCOUNT_ID

The AWS account ID of the AWS Identity and Access Management (IAM) user or role in which Automation runs.

global:DATE

The date (at run time) in the format yyyy-MM-dd.

global:DATE_TIME

The date and time (at run time) in the format yyyy-MM-dd_HH.mm.ss.

global:REGION

The Region that the runbook is run in. For example, us-east-2.

Automation Variables

Automation runbooks currently support the following automation variables.

Variable Details

automation:EXECUTION_ID

The unique identifier assigned to the current automation. For example, 1a2b3c-1a2b3c-1a2b3c-1a2b3c1a2b3c1a2b3c.

Terminology

The following terms describe how variables and parameters are resolved.

Term Definition Example

Constant ARN

A valid ARN without variables

arn:aws:iam::123456789012:role/roleName

Runbook parameter

A parameter defined at the runbook level (for example, instanceId). The parameter is used in a basic string replace. Its value is supplied at Start Execution time.

{ "description": "Create Image Demo", "version": "0.3", "assumeRole": "Your_Automation_Assume_Role_ARN", "parameters":{ "instanceId": { "type": "String", "description": "Instance to create image from" } }

System variable

A general variable substituted into the runbook when any part of the runbook is evaluated.

"activities": [ { "id": "copyImage", "activityType": "AWS-CopyImage", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "ImageName": "{{imageName}}", "SourceImageId": "{{sourceImageId}}", "SourceRegion": "{{sourceRegion}}", "Encrypted": true, "ImageDescription": "Test CopyImage Description created on {{global:DATE}}" } } ]

Automation variable

A variable relating to the automation substituted into the runbook when any part of the runbook is evaluated.

{ "name": "runFixedCmds", "action": "aws:runCommand", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "DocumentName": "AWS-RunPowerShellScript", "InstanceIds": [ "{{LaunchInstance.InstanceIds}}" ], "Parameters": { "commands": [ "dir", "date", "“{{outputFormat}}” -f “left”,”right”,”{{global:DATE}}”,”{{automation:EXECUTION_ID}}” ] } } }

SSM Parameter

A variable defined within Parameter Store. It cannot be directly referenced in step input. Permissions might be required to access the parameter.

description: Launch new Windows test instance schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String default: '' description: >- (Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook. LatestAmi: type: String default: >- {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}} description: The latest Windows Server 2016 AMI queried from the public parameter. mainSteps: - name: launchInstance action: 'aws:runInstances' maxAttempts: 3 timeoutSeconds: 1200 onFailure: Abort inputs: ImageId: '{{LatestAmi}}' ...

Supported scenarios

Scenario Comments Example

Constant ARN assumeRole at creation.

An authorization check is performed to verify that the calling user is permitted to pass the given assumeRole.

{ "description": "Test all Automation resolvable parameters", "schemaVersion": "0.3", "assumeRole": "arn:aws:iam::123456789012:role/roleName", "parameters": { ...

Runbook parameter supplied for AssumeRole when the automation is started.

Must be defined in the parameter list of the runbook.

{ "description": "Test all Automation resolvable parameters", "schemaVersion": "0.3", "assumeRole": "{{dynamicARN}}", "parameters": { ...

Value supplied for runbook parameter at start.

Customer supplies the value to use for a parameter. Any inputs supplied at start time need to be defined in the parameter list of the runbook.

... "parameters": { "amiId": { "type": "String", "default": "ami-12345678", "description": "list of commands to run as part of first step" }, ...

Inputs to Start Automation Execution include : {"amiId" : ["ami-12345678"] }

SSM Parameter referenced within runbook content.

The variable exists within the customer's account, or is a publicly accessibly parameter, and the AssumeRole for the runbook has access to the variable. A check is performed at create time to confirm the AssumeRole has access. The parameter cannot be directly referenced in step input.

... parameters: LatestAmi: type: String default: >- {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}} description: The latest Windows Server 2016 AMI queried from the public parameter. mainSteps: - name: launchInstance action: 'aws:runInstances' maxAttempts: 3 timeoutSeconds: 1200 onFailure: Abort inputs: ImageId: '{{LatestAmi}}' ...

System variable referenced within step definition

A system variable is substituted into the runbook when the automation is started. The value injected into the runbook is relative to when the substitution occurs. That is, the value of a time variable injected at step 1 is different from the value injected at step 3 because of the time it takes to run the steps between. System variables do not need to be set in the parameter list of the runbook.

... "mainSteps": [ { "name": "RunSomeCommands", "action": "aws:runCommand", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "DocumentName": "AWS:RunPowerShell", "InstanceIds": ["{{LaunchInstance.InstanceIds}}"], "Parameters": { "commands" : [ "echo {The time is now {{global:DATE_TIME}}}" ] } } }, ...

Automation variable referenced within step definition.

Automation variables do not need to be set in the parameter list of the runbook. The only supported Automation variable is automation:EXECUTION_ID.

... "mainSteps": [ { "name": "invokeLambdaFunction", "action": "aws:invokeLambdaFunction", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "FunctionName": "Hello-World-LambdaFunction", "Payload" : "{ "executionId" : "{{automation:EXECUTION_ID}}" }" } } ...

Refer to output from previous step within next step definition.

This is parameter redirection. The output of a previous step is referenced using the syntax {{stepName.OutputName}}. This syntax cannot be used by the customer for runbook parameters. This is resolved when the referring step runs. The parameter is not listed in the parameters of the runbook.

... "mainSteps": [ { "name": "LaunchInstance", "action": "aws:runInstances", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "ImageId": "{{amiId}}", "MinInstanceCount": 1, "MaxInstanceCount": 2 } }, { "name":"changeState", "action": "aws:changeInstanceState", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "InstanceIds": ["{{LaunchInstance.InstanceIds}}"], "DesiredState": "terminated" } } ...

Unsupported scenarios

Scenario Comment Example

SSM Parameter supplied for assumeRole at create

Not supported.

... { "description": "Test all Automation resolvable parameters", "schemaVersion": "0.3", "assumeRole": "{{ssm:administratorRoleARN}}", "parameters": { ...

SSM Parameter directly referenced in step input.

Returns InvalidDocumentContent exception at create time.

... mainSteps: - name: launchInstance action: 'aws:runInstances' maxAttempts: 3 timeoutSeconds: 1200 onFailure: Abort inputs: ImageId: '{{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}' ...

Variable step definition

The definition of a step in the runbook is constructed by variables.

... "mainSteps": [ { "name": "LaunchInstance", "action": "aws:runInstances", "{{attemptModel}}": 1, "onFailure": "Continue", "inputs": { "ImageId": "ami-12345678", "MinInstanceCount": 1, "MaxInstanceCount": 2 } ... User supplies input : { "attemptModel" : "minAttempts" }

Cross referencing runbook parameters

The user supplies an input parameter at start time, which is a reference to another parameter in the runbook.

... "parameters": { "amiId": { "type": "String", "default": "ami-7f2e6015", "description": "list of commands to run as part of first step" }, "alternateAmiId": { "type": "String", "description": "The alternate AMI to try if this first fails". "default" : "{{amiId}}" }, ...

Multi-level expansion

The runbook defines a variable that evaluates to the name of a variable. This sits within the variable delimiters (that is {{ }}) and is expanded to the value of that variable/parameter.

... "parameters": { "firstParameter": { "type": "String", "default": "param2", "description": "The parameter to reference" }, "secondParameter": { "type": "String", "default" : "echo {Hello world}", "description": "What to run" } }, "mainSteps": [{ "name": "runFixedCmds", "action": "aws:runCommand", "maxAttempts": 1, "onFailure": "Continue", "inputs": { "DocumentName": "AWS-RunPowerShellScript", "InstanceIds" : "{{LaunchInstance.InstanceIds}}", "Parameters": { "commands": [ "{{ {{firstParameter}} }}"] } ... Note: The customer intention here would be to run a command of "echo {Hello world}"

Referencing output from a runbook step that is a different variable type

The user references the output from a preceding runbook step within a subsequent step. The output is a variable type that does not meet the requirements of the action in the subsequent step.

... mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ImageName}}" outputs: - Name: ImageIdList Selector: "$.Images" Type: "StringList" - name: copyMyImages action: aws:copyImage maxAttempts: 3 onFailure: Abort inputs: SourceImageId: {{getImageId.ImageIdList}} SourceRegion: ap-northeast-2 ImageName: Encrypted Copies of LAMP base AMI in ap-northeast-2 Encrypted: true ... Note: You must provide the type required by the Automation action. In this case, aws:copyImage requires a "String" type variable but the preceding step outputs a "StringList" type variable.