AmazonEC2 plugin

The AmazonEC2 plugin provides steps for working with Amazon Elastic Compute Cloud (EC2) instances.

Before you begin

To use the AmazonEC2 plugin, complete the following prerequisite tasks:

  1. Verify that your Deployment Automation user role allows you to manage plugins. For details, see Server roles and system security.

  2. Download the Deployment Automation plugin bundle, extract the AmazonEC2 plugin zip file from the bundle, and load the file into Deployment Automation. For details, see Load and upgrade plugins.

To use the plugin steps, open a component or global process and navigate to Cloud > AmazonEC2 in the Tools pane.

For details on creating processes, see Create and design component processes and Create and design global processes.

Back to top

Step: Associate IPs

Use the Associate IPs step to associate Elastic IP addresses with Amazon EC2 instances.

In Amazon Web Services (AWS), an Elastic IP address enables you to reserve an IP address that you can then assign to any EC2 instance you have running.

After an Elastic IP is assigned to an instance, it remains associated with the instance until you release it. You can change the assignment to a different instance anytime.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

IPs Specify Elastic IPs to associate with EC2 instances. Enter each IP on a new line.
Instance IDs Specify instance IDs that correspond to the Elastic IPs you specified. Enter each instance ID on a new line.

Back to top

Step: Create Security Group

The Amazon EC2 security group acts as a firewall that controls the traffic allowed into a group of instances.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

Security Group Name If you are not using a file to add permissions, enter a name for the new security group. The name must be unique within your Virtual Private Cloud (VPC).
Description If you are not using a file to add permissions, enter a description for the security group.
VPC ID (Optional) If you are not using a file to add permissions, enter the ID of your Virtual Private Cloud (VPC).
Definition File

To create a security group from a file, enter the full path to an XML file containing the security group's allowed IPs/ports.

The file defines the following entries:

<SecurityGroup name="name" description="description" vpcId="id_optional">
   <ipPermission protocol="tcp" fromPort="nn" toPort="nn">
      <ipRange value="0.0.0.0/0"/>
   </ipPermission>
</SecurityGroup>

To create an empty security group, leave this field empty.

Back to top

Step: Register Instances with Load Balancer

Use the Register Instances with Load Balancer step to add EC2 instances to the specified load balancer.

Elastic Load Balancing automatically distributes incoming application traffic across multiple Amazon EC2 instances. It detects unhealthy instances within a pool and automatically reroutes traffic to healthy instances until the unhealthy instances are restored.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the Elastic Load Balancing endpoint. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/LoadBalancerEndPoint}

For details, see the section about Elastic Load Balancing endpoints and quotas in the AWS documentation.

Load Balancer Name Enter the name of the load balancer to which you want to add the EC2 instances.
Instance IDs Enter instance IDs to register with the load balancer, separated with commas.

Back to top

Step: Deregister Instances with Load Balancer

Use the Deregister Instances with LoadBalancer step to remove EC2 instances from the specified load balancer. A deregistered instance stops receiving requests from the load balancer.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the Elastic Load Balancing endpoint. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/LoadBalancerEndPoint}

For details, see the section about Elastic Load Balancing endpoints and quotas in the AWS documentation.

Load Balancer Name Enter the name of the load balancer from which you want to deregister the EC2 instances.
Instance IDs Enter instance IDs to deregister from the load balancer, separated with commas.

Back to top

Step: Get Public DNS

Use the Get Public DNS step to get a list of public DNS host names that Amazon EC2 instances are running on.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

Instance IDs Enter the IDs of instances for which to retrieve DNS names. Separate IDs with commas. DNS names are returned in the same order in which the IDs are specified.

Back to top

Step: Launch Instances

Use the Launch Instances step to create and start EC2 instances from an Amazon Machine Image (AMI).

An AMI is a template that contains a software configuration, such as an operating system, application server, or applications that you can run in an Amazon environment.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

# of instances Enter the number of EC2 instances to launch.
Instance Type From the list of available types, select the type of EC2 instances to launch.
Subnet ID (Optional) To launch instances in a specific subnet, enter the subnet ID.
Security Group

(Optional) For additional security, enter the names of security groups to use, separated with commas.

If a security group is not in your default Virtual Private Cloud (VPC), specify the security group ID.

Key Pair (Optional) For additional security, specify the key pair name associated with the relevant public key in Amazon EC2, to launch instances.
AMI ID Specify the ID of the AMI from which to launch instances.

Tags

Available in versions: 6.3.6 and later

To add tags to instances, enter each tag on a new line using the following syntax:

key=value

IAM Instance Profile

Available in versions: 6.3.6 and later

Specify the instance profile to pass its IAM role to the EC2 instances, for example:

customer-mc-ec2-instance-profile

All EC2 instances launched by this step assume the instance profile's IAM role and inherit its permissions.

User data Specify the user data to be passed to instances. For example, you can pass a date and time script to run on the instances as soon as they are launched.
Delete volume on termination Choose to delete or keep the store volumes when the instances are terminated. By default, the volumes associated with the instance are deleted.

Back to top

Step: Manage Tags

Available in versions: 6.3.6 and later

Use the Manage Tags step to attach, modify, or remove user-defined tags in EC2 instances. Tags provide a way to categorize instances by purpose, owner, environment or other relevant criteria.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.
Authentication Type

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

Instance IDs Enter the IDs of instances for which you want to manage tags. Separate IDs with commas.
Tag Operation Type

Select the tag action:

  • To add new tags or modify existing tags, select create/edit.

  • To remove tags, select delete.

Tags

Enter the tags to create, edit, or delete. Each tag is a key=value pair, where the tag key is case-sensitive and the tag value is optional.

Specify each tag on a new line using the following syntax:

key=value
key=

Hidden properties
Delete all tags

If you are deleting tags, you can use this option to remove all tags attached to the specified EC2 instances.

Note: This option works only if you selected delete as the Tag Operation Type.

Back to top

Step: Remove Volumes

If you no longer require Amazon EBS store volumes, use the Remove Volumes step to delete the volumes.

Caution: You cannot restore the volume's data after deletion. The deleted volume cannot be attached to any instance.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

Include Volume IDs Enter the IDs of the EBS volumes to be removed, separated with commas. If this field is empty, no volumes are removed.
Include Volume States

Enter one or more states in which a volume can be removed, separated with commas.

Volume states describe a volume's availability. You can use the following states: creating, available, in-use, deleting, or error. For example, to remove all the volumes attached to an instance or detached from it, enter in-use,available.

Exclude Volume IDs To keep specific volumes from being removed, enter their volume IDs, separated with commas. Otherwise, all the volumes defined in the Include Volume IDs field are removed.

Back to top

Steps: Start / Stop / Terminate Instances

To start, stop, or terminate Amazon EC2 instances, you pass the same set of parameters to identify the instances. Terminating an instance means deleting it.

You can start, stop or terminate multiple instances at once.

The following table describes the steps' properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

Instance IDs Enter the IDs of the EC2 instances to start, stop, or terminate, separated with commas.
Retry on Failure If any instances aren't started, stopped, or terminated, Deployment Automation attempts to repeat the operation. If you don't want to retry the operation, clear this option.

Back to top

Step: Wait for Instance

You can create a step that waits for the specified instances to be in a certain state.

The following table describes the step's properties. For details about optional properties that are common to all AmazonEC2 steps, see Optional properties.

Property Description
Name Enter a name for the step. By default, the system uses the command name.

Authentication Type

Available in versions: 6.3.6 and later

Select the method to authenticate to your Amazon EC2 instance:

  • IAM Role Assumed. Assume the Identity and Access Management (IAM) role associated with the EC2 instance on which this step runs. The IAM role provides a set of temporary credentials to make AWS API requests.

  • IAM Security Credentials. Use a security key pair.

Access Key ID

To authenticate using IAM security credentials, enter your access key ID. By default, the following property is used:

${p:component/EC2AccessKeyId}

Secret Key

To authenticate using IAM security credentials, enter the corresponding secret key. By default, the following secure property is used:

${p:component/EC2SecretKey}

Endpoint

Specify the AWS service endpoint to use for API requests. An endpoint is a URL that serves as an entry point for an AWS web service. By default, the following property is used:

${p:component/EC2EndPoint}

For details, see the section about AWS service endpoints in the AWS documentation.

Instance IDs Enter the IDs of instances for which to check the state. Separate IDs with commas.
State Specify the state in which the instances must be, such as pending, running, shutting-down, terminated, or stopped.
Timeout

Specify how long the step waits until the instances are in the specified state, in milliseconds.

During the timeout, the step continuously polls for the state of each instance. If an instance changes to the relevant state, the step detects the change and uses the instance.

Back to top

Optional properties

The following properties are common to all AmazonEC2 plugin steps. These properties are optional.

Property Description
Ignore Failure Select this option if you want the step to always be considered successful.
Working Directory

Enter an alternative absolute path to the working directory for the step.

To use the default working directory for the process, leave the field empty.

Post Processing Script

Select a custom post-processing script. To run the step's default script, leave the field empty.

To create your custom post-processing script, click Add , and enter script details in the Create Script dialog box.

A post-processing script helps ensure that expected results occur. It runs after a step finishes processing. For details, see Post-processing scripts.

Precondition Enter a JavaScript script to define a condition that must exist before the step can run. The condition resolves to true or false.
Use Impersonation Select this option if you want an agent to run the step as a different user. Specify the impersonation details for a Windows or UNIX/Linux agent, as described in Use impersonation to run processes.
Hint Add a comment to the step. To view the comment, point to the step in the design space.
Hidden properties
Output properties secure rules

Specify properties you want to be treated as secure. Secure properties are stored encrypted, and their values are displayed obscured in the Deployment Automation user interface.

Use regular expressions to select multiple properties. Enter each property name or expression on a new line.

Example: To select all properties with names that start with prop, use this regular expression: prop.*

Maximum number of retries

If the operation fails, specify how many times Deployment Automation attempts to retry the operation.

Default: 50 attempts

Maximum fail timeout (s)

Enter the maximum time interval between failed attempts, in seconds.

The initial timeout is one second. With every failed attempt, the timeout is doubled until it reaches the maximum value you specified.

Default: 30 seconds

Debug logs Select this option to log debug information during the run.

Back to top

See also: