ec2 User Data Explained With Troubleshooting Steps

In this blog, we will look at how to troubleshoot ec2 user data script execution on Linux instances.

What is ec2 user data?

ec2 user data is primarily used to execute scripts during the instance startup.

You can make use of ec2 user data in the following ways.

1. To execute shell scripts directly.
2. To execute and configure apps using the cloud-init directives.

There are many use cases for using user data, for example,

1. To trigger an Ansible playbook that configures an application
2. To set a custom hostname for the server using cloud-config
3. Run a Python script to retrieve secrets from the secret manager.

You can add user data scripts using the following methods.

Using AWS CLI

When you launch an ec2 instance using AWS CLI, you can pass the user data script from a file using the following flag and format

 --user-data file://path/to/script.sh

Here is an example.

If you want to run a single-line command, you can use the following

--user-data sudo systemctl nginx start

AWS Web Console

If you are using the web console to create an ec2 instance, you have an option to directly enter the script in the user data option. You will find the option under the Advanced details.

You can either upload the script file or enter the script directly in the text box as shown here.

Using IaC Tools

If you are using Infrastructure as code tools like Terraform, it provides options to execute userdata script while provisioning.

Here is a terraform user data example.

ec2 user data Troubleshooting

There are scenarios where the ec2 user data might not work as expected. It could be of different reasons.

Let's look at different options to troubleshoot ec2 user data script issues.

Verify user data script

The first step is to verify the user data script. You can do that by logging into the instance and executing the following command. The instance metadata URL returns the added metadata.

curl http://169.254.169.254/latest/user-data

user data script location

The script your add to the user data section gets stored in the following location with name part-001

/var/lib/cloud/instances/<instance-id>/scripts/part-001

Cloud Init Logs

The user data execution is part of the cloud init logs. You can find the log in the following location.

/var/log/cloud-init.log

You can get the same log from the web console under instance -->actions --> Monitor and troubleshoot -->Get stem log

As we discussed in the previous section, part-001 is the file name used by the ec2 instance to store the user-data script. we can use the name and search in the log to identify if the script has been executed or not.

Here is the Linux command to check the logs.

tail -n 1000 /var/log/cloud-init.log | grep "part-001"