Create EC2 stack instance with additional volumes - AMS Advanced Onboarding Guide

Create EC2 stack instance with additional volumes

Create an Amazon Elastic Compute Cloud, EC2 instance, with up to five additional volumes, using the AMS console or the AMS API/CLI.

Classification: Deployment | Advanced stack components | EC2 stack | Create (with additional volumes)

Change type ID: ct-1aqsjf86w6vxg

Version: 4.0

For more information about Amazon EC2, including size recommendations, see Amazon Elastic Compute Cloud Documentation.

To update your EC2 stack with additional volumes after they're created, see EC2 stack: updating with additional volumes

Important

There is a new version of this change type, v 4.0, that uses a different StackTemplateId (stm-nn8v8ffhcal611bmo). This is important if you're submitting the RFC with this change type at the command line. The new version introduces two new parameters (RootVolumeKmsKeyId and CreditSpecification) and changes the default for one existing parameter (InstanceType).

Required data:

  • Description: A reason for the request.

  • VpcId: The VPC to use. For information about finding VPC IDs, see Find VPC.

  • Name: A name for the stack or stack component. You must use a "Name" tag in order for the instance to have a name in the EC2 console Instances details page.

  • TimeoutInMinutes: The number of minutes allowed for the creation of the stack before the RFC fails. This setting won't delay the RFC execution, but you must give enough time (for example, don't specify "5"). Valid values are "60" up to "360," for long-running UserData.

  • Parameters:

    • InstanceAmiId: The AMI to use to create the EC2 instance. We recommend using the most recent AMS AMI that begins with "customer-". For help finding AMIs, see Finding an AMI.

    • InstanceSubnetId: The subnet that you want to launch the instance into. For information about finding subnet IDs, see Find Subnet.

Optional data:

When using the AMS console, to see the optional parameters, you must enable the Additional configuration view.

  • Tags: Up to 40 tags (key/value pairs) to categorize the EC2.

  • RootVolumeKmsKeyId: The ID, or ARN, of the KMS master key to be used to encrypt the root volume. Specify default to use the default EBS KMS Key. Leave blank to not encrypt the root volume. Note that, if a value is set, the InstanceRootVolumeName must also be specified for KMS encryption settings on the root volume to take effect.

  • CreditSpecification: The credit option for CPU usage. This is only supported with t2, t3, and t3a, instance types. If your instance is unlikely to require CPU bursting, choose standard, but note that, once all the CPU credits for that instance are used up, it will be throttled. For better burst handling, and to not allow throttling, choose unlimited, but note that additional charges may apply when additional credits are used.

  • InstanceTerminationProtection: True to prevent the instance from being terminated through the API, false to allow it. Default is false. Termination protection must be disabled with an update (ct-1o1x2itfd6rk8) before deleting the stack or performing an update where instance replacement is required, otherwise failures occur.

  • InstanceType: The type of EC2 instance to deploy. If InstanceEBSOptimized = true, specify an InstanceType that supports EBS optimization. Default is t3.large. NOTE: EC2 instances need enough capacity to support AMS tools such as EPS, SSM, and Cloudwatch in addition to the application workload. AMS does not recommend the t2.micro/t3.micro and t2.nano/t3.nano types. These are smaller instance types, and can degrade the performance of your application and AMS tools. For more information, see Choosing the Right EC2 Instance Type for Your Application. In version 4.0, the default type was raised from t2.large to t3.large. T3 instances launch with 'unlimited credits' by default. You won't experience CPU throttling even if the instance consumes all CPU credits. You can, instead, choose to launch T2 instances and use the CreditSpecification unlimited option.

  • InstanceSecurityGroupIds: IDs for the security groups you want to attach to the instance. These security groups control access to the EC2 instance. Default AMS security groups are attached to the instance in addition to the security groups specified here.

  • InstanceDetailedMonitoring: True to enable detailed monitoring on the instance, false to use only basic monitoring. The default is false.

  • InstanceEBSOptimized: True for the instance to be optimized for Amazon Elastic Block Store I/O, false for it to not be. If you set this to true, choose an InstanceType that supports EBS optimization. Default is false, which means that you get basic EBS storage.

  • InstanceProfile: An IAM instance profile defined in your account for the EC2 instance. The default is customer-mc-ec2-instanceprofile.

  • InstanceRootVolumeName: The name of the root volume to use. Default is /dev/xvda for Linux, and /dev/sda for Windows.

  • InstanceRootVolumeSize: The size of the root volume for the instance. The default is 8 GiB for Linux, and 30 GiB for Windows.

  • InstanceRootVolumeIops: The Iops to use for the root volume, if io1 volume type is specified. The default is 0.

  • InstanceRootVolumeType: Choose SSD-backed volumes optimized for transactional workloads (io1, gp2 and gp3), or HDD-backed volumes optimized for large streaming workloads (standard). The default is standard. The additional volumes support all the supported EBS types (gp2, gp3, io1, sc1, st1 and standard), encryption using KMS, and creation using snapshots.

  • InstancePrivateStaticIp: The static IP address that the instance can support.

  • InstanceSecondaryPrivateIpAddressCount: The number of secondary private IP addresses that EC2 automatically assigns to the primary network interface. The number of secondary IP addresses that can be assigned is dependent on the type of instance used.

  • InstanceType: See previous Important note.

  • InstanceUserData: A newline-delimited list where each element is a line of script to be run on boot. To separate lines, use the literal: "\n".

  • Volume1-5Encrypted: True if the volume is encrypted. False if it is not.

  • Volume1-5Iops: The Iops to use for the volume if the type = io1.

  • Volume1-5Throughput: The throughput to use for the volume volume, if the volume type = gp3. If the volume type is not gp3, any value provided here is ignored. Default is 125.

  • Volume1-5KmsKeyId: Amazon Resource Name (ARN) of the KMS master key to be used to encrypt the volume.

  • Volume1-5Name: The device name for the volume (for example, /dev/sdh or xvdh).

  • Volume1-5Size: The size of the volume in GiB. The default is 1 GiB.

  • Volume1-5Snapshot: Snapshot ID for the volume.

  • Volume1-5Type: The type for the volume. Choose io1, gp2 or gp3 for SSD-backed volumes optimized for transactional workloads. Choose sc1 or st1 for HDD-backed volumes optimized for large streaming workloads. Choose standard for HDD-backed volumes suitable for workloads where data is infrequently accessed.

The following shows this change type in the AMS console.

How it works:

  1. Navigate to the Choose change type page: RFCs -> Create RFC.

  2. Choose a change type from the drop-down lists. Optionally, open the Additional configuration area to select a change type version. After your selections are complete, a Change type: details area opens. Choose Next.

  3. Configure the request for change. A Subject is required. Optionally, open the Additional configuration area to add information about the RFC. Choose Next.

  4. Choose the execution parameters. At the top, in the RFC configuration area, enter values for the change type required parameters. These vary by change type. Open the Additional configuration area to add Tags or additional settings. Some change types also provide a Parameters area where only the required settings are visible. In that case, open the Additional configuration area to view optional parameters.

  5. When finished, choose Create. If there are no errors, the RFC successfully created page displays with the submitted RFC details, and the initial Execution output.

  6. Open the Execution parameters area to see the configurations you submitted. Refresh the page to update the RFC execution status. Optionally, cancel the RFC or create a copy of it with the options at the top of the page.

How it works:

  1. Use either the Inline Create (you issue a create-rfc command with all RFC and execution parameters included), or Template Create (you create two JSON files, one for the RFC parameters and one for the execution parameters) and issue the create-rfc command with the two files as input. Both methods are described here.

  2. Submit the RFC: aws amscm submit-rfc --rfc-id ID command with the returned RFC ID.

    Monitor the RFC: aws amscm get-rfc --rfc-id ID command.

To check the change type version, use this command:

aws amscm list-change-type-version-summaries --filter Attribute=ChangeTypeId,Value=CT_ID
Note

You can use any CreateRfc parameters with any RFC whether or not they are part of the schema for the change type. For example, to get notifications when the RFC status changes, add this line, --notification "{\"Email\": {\"EmailRecipients\" : [\"email@example.com\"]}}" to the RFC parameters part of the request (not the execution parameters). For a list of all CreateRfc parameters, see the AMS Change Management API Reference.

INLINE CREATE:

Issue the create RFC command with execution parameters provided inline (escape quotation marks when providing execution parameters inline), and then submit the returned RFC ID (example shows required parameters only). For example, you can replace the contents with something like this:

aws amscm create-rfc --change-type-id "ct-1aqsjf86w6vxg" --change-type-version "4.0" --title "EC2-Create-A-V-QC" --execution-parameters "{\"Description\":\"My EC2 stack with addl vol\",\"VpcId\":\"VPC_ID\",\"Name\":\"My Stack\",\"StackTemplateId\":\"stm-nn8v8ffhcal611bmo\",\"TimeoutInMinutes\":60,\"Parameters\":{\"InstanceAmiId\":\"AMI_ID\",\"InstanceSubnetId\":\"SUBNET_ID\"}}

TEMPLATE CREATE:

  1. Output the execution parameters for this change type to a JSON file named CreateEC2AVParams.json.

    aws amscm get-change-type-version --change-type-id "ct-1aqsjf86w6vxg" --query "ChangeTypeVersion.ExecutionInputSchema" --output text > CreateEC2AVParams.json
  2. Modify and save the CreateEC2AVParams file (example shows most parameters). For example, you can replace the contents with something like this:

    { "Description": "EC2-Create-1-Addl-Volumes", "VpcId": "VPC_ID", "StackTemplateId": "stm-nn8v8ffhcal611bmo", "Name": "My-EC2-1-Addl-Volume", "TimeoutInMinutes": 60, "Parameters": { "InstanceAmiId": "AMI_ID", "InstanceSecurityGroupIds": "SECURITY_GROUP_ID", "InstanceDetailedMonitoring": "true", "InstanceEBSOptimized": "false", "InstanceProfile": "customer-mc-ec2-instance-profile", "InstanceRootVolumeIops": 100, "InstanceRootVolumeName": "/dev/xvda", "InstanceRootVolumeSize": 50, "InstanceRootVolumeType": "io1", "RootVolumeKmsKeyId": "default", "InstancePrivateStaticIp": "10.27.0.100", "InstanceSecondaryPrivateIpAddressCount": 0, "InstanceTerminationProtection": "false", "InstanceType": "t3.large", "CreditSpecification": "unlimited", "InstanceUserData": "echo $", "Volume1Encrypted": "true", "Volume1Iops": "IOPS" "Volume1KmsKeyId": "KMS_MASTER_KEY_ID", "Volume1Name": "xvdh" "Volume1Size": "2 GiB", "Volume1Snapshot": "SNAPSHOT_ID", "Volume1Type": "iol", "InstanceSubnetId": "SUBNET_ID" } }
  3. Output the RFC template to a file in your current folder; this example names it CreateEC2AVRfc.json:

    aws amscm create-rfc --generate-cli-skeleton > CreateEC2AVRfc.json
  4. Modify and save the CreateEC2AVRfc.json file. For example, you can replace the contents with something like this:

    { "ChangeTypeVersion": "4.0", "ChangeTypeId": "ct-1aqsjf86w6vxg", "Title": "EC2-Create-1-Addl-Volume-RFC" }
  5. Create the RFC, specifying the CreateEC2AVRfc file and the CreateEC2AVParams file:

    aws amscm create-rfc --cli-input-json file://CreateEC2AVRfc.json --execution-parameters file://CreateEC2AVParams.json

    You receive the ID of the new RFC in the response and can use it to submit and monitor the RFC. Until you submit it, the RFC remains in the editing state and does not start.