AWS tech-specific script execution

Tech-specific script execution lets Cloud Management Platform (CMP) run remote scripts on an EC2 instance it cannot reach directly over SSH or WinRM. CMP instead uses the AWS Systems Manager (SSM) Run Command feature, which delivers the script to the instance and reports the result back.

Prerequisites

Set these up in AWS before configuring anything in CMP.

• Instances must have the SSM Agent installed. See Images with the SSM Agent pre-installed.
• Linux instances need port 443 reachable, or a correctly configured VPC endpoint for SSM.
• Windows instances need port 3389 open. The default launch-wizard security groups do not work. Use an instance type of t2.small or larger for acceptable performance, and allow a few minutes longer than Linux for SSM to finish installing: an instance can report Running before SSM is ready. The instance system log in AWS helps here.
• If the deployment has no internet access over port 443, configure VPC endpoints. See the AWS guidance on creating VPC endpoints.

Roles and policies

Roles are what SSM support in CMP rests on. Create an IAM role in AWS for SSM, for example EnablesEC2ToAccessSystemsManagerRole. CMP uses it to enable SSM on supported operating systems. See Supported operating systems in the AWS documentation.

The AmazonSSMManagedInstanceCore policy must be attached to that role:

1. In the AWS console, open IAM.
2. Under Access management, select Policies.
3. Search for AmazonSSMManagedInstanceCore and open it.
4. Select Policy usage and check that your SSM role is attached. If it is not, attach it.

Set up Systems Manager in CMP

Setup has three parts: add the SSM role, add the parameters, then provision a server and test.

Add the SSM role

1. Go to Admin > Resource Handlers.
2. Select an existing AWS resource handler, or create one.
3. On the Overview tab, select Edit Settings.
4. In SSM ARN, enter the ARN of the role from Roles and policies, for example arn:aws:iam::123456789012:role/EnablesEC2ToAccessSystemsManagerRole.
5. Select Save.

The Overview tab shows the value as SSM Role ARN. You need the same role ARN when you set up the blueprint.

Add the parameter to a group or environment

1. Open the group or environment associated with the AWS resource handler.

2. On the Parameters tab, select Add.

3. Find Use Tech-Specific Script Execution and add it.

   (opens full-size image in a new tab)

4. Select the parameter you just added.

5. Ensure that Show on Objects and Available to all servers are enabled.

Set up a blueprint

A server built from this blueprint gets the SSM role associated with it.

1. Open Catalog and select the blueprint.
2. Open the Parameters tab.
3. Add AWS IAM Role ARN and Use Tech-Specific Script Execution.
4. On AWS IAM Role ARN, edit the Options column and add the role ARN from Add the SSM role as an option.

Provision and test

1. Provision a server from that blueprint.
2. On the provisioned server, run an ad hoc script. It should run without asking for a username and password.

Images with the SSM Agent pre-installed

AWS ships the SSM Agent pre-installed on several of its images, including the current Amazon Linux, Ubuntu Server, Windows Server, and ECS-optimized images. Names vary by region and release, and the list changes, so check the AWS list of images with the agent pre-installed for what applies to the image you plan to use. On any other image, install the agent.

Troubleshooting

Remote scripts over SSM behave differently from ordinary remote scripts. AWS runs the script on the instance and reports back, rather than CMP running commands itself, so a failed script can still appear to have succeeded.

• Check that the script is correct, as errors may not be returned in a verbose manner.
• Handle exceptions in the script, and check the return code for errors.

For what AWS reports back, see Understanding command statuses.