ec2 User Data Explained With Troubleshooting Steps

ec2 user data

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.


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/

Here is an example.

    user data with ec2 aws cli command

    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.

    ec2 user data in aws web console

    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 usage in Terraform

    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.


    user data script location

    The script your add to the user data section gets stored in the following location with name 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.


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

    ec2 user data system logs from ec2 console

    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"

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    You May Also Like