How to Launch an Amazon AWS EC2 Instance with UserData from CLI

In Amazon AWS, all the activities that you perform to manipulate your EC2 instances from AWS Console web interface can also be performed from command line using aws cli utilities.

The command is aws. You can use the ec2 option in the aws command to manipulate your ec2 instances.

This tutorial specifically covers about UserData in EC2. We’ve shown the CLI examples for the following:

1. Launch a New EC2 Instance without UserData from CLI
2. Create a new EC2 Server Instance with UserData from CLI
3. View the UserData of an existing EC2 Instance from CLI

1. Launch a New EC2 Instance from CLI (Without UserData)

You can launch any instance from the AWS Marketplace directly from the command line.

For this, you should know the AMI id (i.e image id) of the particular image from which you want to create a new instance.

In this example, we’ll be launching a new EC2 server from the Amazon Linux image. The image id for this is ami-a4c7edb2.

In this example, the image we are using is called “Amazon Linux AMI 2017.03.1 (HVM), SSD Volume Type” with this image id: ami-a4c7edb2. This is the description of this particular image: The Amazon Linux AMI is an EBS-backed, AWS-supported image. The default image includes AWS command line tools, Python, Ruby, Perl, and Java. The repositories include Docker, PHP, MySQL, PostgreSQL, and other packages.

To launch a new server from an image, use the run-instances option along with “aws ec2” command as shown below:

# aws ec2 run-instances --image-id ami-a4c7edb2 --count 1 \
        --instance-type t2.micro --key-name mynewkey \
        --subnet-id subnet-5630306b
{
 "OwnerId": "123449611234",
 "ReservationId": "r-05e649ad3ee70f52d",
 "Groups": [],
 "Instances": [
     {
         "Monitoring": {
             "State": "disabled"
         },
..
..
         "VpcId": "vpc-63042b04",
         "StateTransitionReason": "",
         "InstanceId": "i-01ce046ad25ceb467",
         "ImageId": "ami-a4c7edb2",
         "PrivateDnsName": "ip-192-30-4-91.ec2.internal",
         "KeyName": "mynewkey",
         "SecurityGroups": [
             {
                 "GroupName": "default",
                 "GroupId": "sg-26d3d362"
             }
         ],
..
..
         "RootDeviceName": "/dev/xvda",
         "VirtualizationType": "hvm",
         "AmiLaunchIndex": 0
     }
 ]
}

In the above:

• aws ec2 run-instances – This is the command to launch new Amazon EC2 instance
• –image-id ami-a4c7edb2 – This is the image id of the image that we will be using to create a new instance. This is the image id of Amazon Linux
• –count 1 This indicates that we want to create just one new server with this image. Be very careful with this parameter, you don’t want to by mistake specify a higher number here, as it will create those many number of servers, which will be charged to your account.
• –instance-type t2.micro – Specify the instance type here.
• –key-name mynewkey – Use the key pair that you’ve already created and have it on your AWS account.
• –subnet-id subnet-5630306b – This is the network VPC where I want to create the new EC2 server.

If you don’t specify the network interface, you’ll get the following VPCResourceNotSpecified error message:

A client error (VPCResourceNotSpecified) occurred when calling the RunInstances operation: The specified instance type can only be used in a VPC. A subnet ID or network interface ID is required to carry out the request.

If you specify a parameter that cannot be used in the combination you are using, you’ll get the following InvalidParameterCombination error message.

# aws ec2 run-instances --image-id ami-a4c7edb2 --count 1 --instance-type t2.micro --key-name mynewkey --security-groups my-aws-security-group --subnet-id subnet-8534a4af
A client error (InvalidParameterCombination) occurred when calling the RunInstances operation: The parameter groupName cannot be used with the parameter subnet

If you specify an invalid AMI image id, you’ll get the following InvalidAMIID.Malformed error:

A client error (InvalidAMIID.Malformed) occurred when calling the RunInstances operation: Invalid id: "ami-a4c7edbm"

There are many things you can do using the aws ec2 CLI utility as we discussed earlier: 15 Essential Amazon AWS EC2 CLI Command Examples

2. Create a new EC2 Instance with UserData from CLI

You can use Userdata file during an instance creation to execute your custom commands. This is helpful when you want your newly created instance to be in a certain state with certain packages installed, or with certain custom configuration.

Create your custom userdata file. For example: ud.txt

# cat ud.txt
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

Specify the above ud.txt file during the instance creation in the run-instances command as shown below:

aws ec2 run-instances --image-id ami-a4c7edb2 --count 1 \
     --instance-type t2.micro --key-name mynewkey \
     --subnet-id subnet-5630306b --user-data file://ud.txt

3. View the UserData of an Existing EC2 Instance from CLI

To view the Userdata that was used while creating your instance, do the following:

For this, use the describe-instance-attribute option in the “aws ec2” command as shown below. Use the

aws ec2 describe-instance-attribute --instance-id i-08dae85dc8fa85aa2 \
     --attribute userData --output text --query "UserData.Value" \
     | base64 --decode

In the above:

• aws ec2 describe-instance-attribute – This is the command to view any attribute of the specified instance
• –attribute userData – This indicates that the attribute we are interested is userData
• –instance-id – Specify the instance id for which we want to view the attribute
• –output text – We want to output in text format
• –query “UserData.Value” – We are specifically querying for the UserData.Value
• base64 –decode – The output is in base64. So, we have to pipe the output to base64 and decode the value as show here.

The following is the output of the above command. This is the userdata file that was used when this particular instance was launched for the first time.

#!/bin/bash
yum update -y
service mysqld start
chkconfig mysqld on