How do I set the properties of a root volume for an Amazon EC2 instance that I created using an AWS CloudFormation template?

Short description

To set the properties of the root volume for an EC2 instance, you must identify the device name of the root volume for your Amazon Machine Image (AMI). Then, you can use the BlockDeviceMapping property of an AWS::EC2::Instance resource to set the properties of the root volume.

Note: By default, the block devices specified in the block device mapping for the AMI are used by the EC2 instance. To override the AMI block device mapping, use instance block device mapping. For the root volume, you can override only the volume size, volume type, and DeleteOnTermination setting. After the instance is running, you can modify only the DeleteOnTermination setting of the attached Amazon Elastic Block Store (Amazon EBS) volumes.

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

Resolution

Identify the device name of the root volume of your AMI

To find the device name, complete the following steps in either the Amazon EC2 console or the AWS CLI.

Using the Amazon EC2 console:

1.    Open the Amazon EC2 console.

2.    From the navigation bar, select the AWS Region where you want to launch your instances.

3.    In the navigation pane, choose AMIs.

4.    Use the Filter option to find your AMI, and then select your AMI.

5.    On the Details tab, find the Root Device Name. This is where your root device name is listed.

Using the AWS CLI command:

In the AWS CLI, run the following command:

aws ec2 describe-images \
    --region us-east-1 \
    --image-ids ami-1234567890AWSEXAMPLE

Note: Replace us-east-1 with your Region. Replace ami-1234567890AWSEXAMPLE with your AMI.

The output of the preceding command returns the RootDeviceName field, which shows the device name of the root volume.

Set the properties of the root volume for your EC2 instance

Use the BlockDeviceMapping property of an AWS::EC2::Instance resource to set the properties of the root volume for your EC2 instance.

In the following JSON and YAML examples, AWS CloudFormation creates an EC2 instance with the size of the root volume set to 30 GB.

In the JSON and YAML templates, the DeleteOnTermination property of the root volume is set to true. The DeviceName is set to /dev/xvda because the AMI specified is an Amazon Linux 2 AMI. Finally, the Encrypted property is set to true, which enables default encryption on the root volume.

Important: In your template, replace /dev/xvda with the value of the Root Device Name property that you identified earlier. Then, modify the Ebs property in the template based on your requirements.

JSON template:

{
  "AWSTemplateFormatVersion": "2010-09-09",
  "Description": "AWS CloudFormation Sample Template that shows how to increase the size of the root volume. **WARNING** This template creates an Amazon EC2 instance. You will be billed for the AWS resource used if you create a stack from this template.",
  "Parameters": {
    "KeyName": {
      "Type": "AWS::EC2::KeyPair::KeyName",
      "Description": "Name of an existing EC2 KeyPair to enable SSH access to the EC2 instance."
    },
    "InstanceType": {
      "Description": "EC2 instance type",
      "Type": "String",
      "Default": "t2.micro",
      "ConstraintDescription": "Please choose a valid instance type."
    },
    "AMIID": {
      "Description": "The Latest Amazon Linux 2 AMI taken from the public AWS Systems Manager Parameter Store",
      "Type": "AWS::SSM::Parameter::Value<String>",
      "Default": "/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2"
    }
  },
  "Resources": {
    "LinuxInstance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": {
          "Ref": "AMIID"
        },
        "InstanceType": {
          "Ref": "InstanceType"
        },
        "KeyName": {
          "Ref": "KeyName"
        },
        "BlockDeviceMappings": [
          {
            "DeviceName": "/dev/xvda",
            "Ebs": {
              "VolumeType": "gp2",
              "VolumeSize": "30",
              "DeleteOnTermination":"false",
              "Encrypted": "true"
            }
          }
        ]
      }
    }
  }
}

YAML template:

AWSTemplateFormatVersion: 2010-09-09
Description: >-
  AWS CloudFormation Sample Template that shows how to increase the size of the root volume. **WARNING** This template creates an Amazon EC2 instance. You will be billed for the AWS resource used if you create a stack from this template.
Parameters:
  KeyName:
    Type: 'AWS::EC2::KeyPair::KeyName'
    Description: Name of an existing EC2 KeyPair to enable SSH access to the EC2 instance.
  InstanceType:
    Description: EC2 instance type
    Type: String
    Default: t2.micro
    ConstraintDescription: Please choose a valid instance type.
  AMIID:
    Description: >-
      The Latest Amazon Linux 2 AMI taken from the public Systems Manager
      Parameter Store
    Type: 'AWS::SSM::Parameter::Value<String>'
    Default: /aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2
Resources:
  LinuxInstance:
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: !Ref AMIID
      InstanceType: !Ref InstanceType
      KeyName: !Ref KeyName
      BlockDeviceMappings:
        - DeviceName: /dev/xvda
          Ebs:
            VolumeType: gp2
            VolumeSize: '30'
            DeleteOnTermination: 'false'
            Encrypted: 'true'

---