keepcalculator

06 Numbers and Powers

Terraform AWS EC2 User Data: Complete Guide

Card No. 06·72828 · Updated · Standard formula, shown below

Terraform’s user_data argument lets you pass a startup script or configuration to an AWS EC2 instance, which the instance runs automatically on first boot. You supply the script as a string in your Terraform configuration, and AWS executes it inside the instance, making it the standard way to bootstrap software, apply updates, or register the instance with a configuration management tool.

What Is EC2 User Data?

When you launch an EC2 instance, AWS allows you to specify a block of text—up to 16 KB before base64 encoding—that the instance’s cloud-init system processes during the first boot. This block is called user data. It is not stored on the instance’s root volume; it is fetched from the metadata service and executed by cloud-init, which is preinstalled on most official Amazon Machine Images (AMIs). The script can be a shell script (starting with #!/bin/bash), a cloud-init directive (starting with #cloud-config), or another supported format. User data runs only once, on the first boot, unless you explicitly reconfigure cloud-init to run it again.

How Terraform Passes User Data

In Terraform, you define user data in the aws_instance resource block using the user_data argument. The value is a string, and Terraform sends it to the AWS API as part of the instance launch request. Because the API expects base64-encoded data, Terraform automatically base64-encodes the string you provide if you use the user_data argument directly. If you prefer to handle encoding yourself, you can use user_data_base64 instead. Here is a minimal example:

resource "aws_instance" "web" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"

  user_data = <<-EOF
    #!/bin/bash
    apt-get update
    apt-get install -y nginx
    systemctl start nginx
  EOF
}

The heredoc syntax (<<-EOF) is common in Terraform because it preserves newlines and indentation. Terraform sends the exact string to AWS, and cloud-init executes it on the instance. You can also reference variables or files using Terraform’s interpolation or the file() function:

user_data = file("${path.module}/user_data.sh")

Using Template Files for Dynamic User Data

Often you need to pass instance-specific values—like the instance’s own IP, a database endpoint, or a token—into the script. Terraform’s templatefile() function is the cleanest way to do this. It reads a file and substitutes variables you provide. For example, create a file user_data.sh.tpl:

#!/bin/bash
echo "${db_endpoint}" > /etc/db_endpoint
systemctl start myapp

Then in your Terraform configuration:

user_data = templatefile("${path.module}/user_data.sh.tpl", {
  db_endpoint = aws_db_instance.main.endpoint
})

This keeps your script readable and avoids string concatenation. The templatefile() function is available in Terraform 0.12 and later. For older versions, you would use the template_file data source, which is now deprecated.

Passing User Data to Launch Templates and Auto Scaling Groups

If you use an Auto Scaling Group (ASG), you do not attach user data to the ASG itself. Instead, you define it in a launch template (or launch configuration) and reference that template in the ASG. The aws_launch_template resource has a user_data argument that accepts the same base64-encoded string. When the ASG launches new instances, it uses the template’s user data. This is essential for horizontally scaled fleets because every new instance gets the same bootstrap script. For example:

resource "aws_launch_template" "app" {
  name_prefix   = "app-"
  image_id      = data.aws_ami.ubuntu.id
  instance_type = "t3.micro"

  user_data = base64encode(templatefile("${path.module}/user_data.sh.tpl", {
    environment = var.environment
  }))
}

Notice that in a launch template you must manually base64-encode the string using base64encode(), because the launch template API expects base64. The aws_instance resource does this automatically, but the launch template does not.

Debugging User Data Scripts

When a user data script fails, the instance still launches, but the script’s output is not shown in the AWS console by default. To debug, you need to check the cloud-init logs on the instance. The most useful files are:

  • /var/log/cloud-init-output.log – captures the output of your script
  • /var/log/cloud-init.log – detailed cloud-init activity

If you cannot access the instance (e.g., it is in a private subnet), you can enable user_data_replace_on_change in the Terraform resource, but that only triggers a replacement when the user data changes, not when it fails. A common debugging technique is to write the script’s output to a file on an attached EBS volume or to send it to CloudWatch Logs. For example, add to your script:

exec > >(logger -t user-data) 2>&1

This sends all output to syslog, which can be forwarded to CloudWatch. Alternatively, you can use aws s3 cp to upload a log file to S3 after the script runs.

Common Mistakes and Misconceptions

One frequent mistake is assuming user data runs on every boot. By default, it runs only once. If you need to run a script on every boot, you must create a systemd service or a cron job that runs at startup. Another misconception is that user data is stored on the instance. It is not; it is fetched from the metadata service (169.254.169.254) and is not available after the first boot unless you explicitly save it. Also, the 16 KB limit applies to the raw script before base64 encoding. If your script is larger, you must compress it or store it in S3 and have the script download it. Finally, ensure your script has the correct shebang line. If you omit #!/bin/bash, cloud-init may interpret the file as a cloud-config YAML file, which will fail if the content is not valid YAML.

Security Considerations

User data scripts often contain sensitive information like API keys or database passwords. Avoid embedding secrets directly in the script because they are visible in the EC2 console and in Terraform state files. Instead, use AWS Systems Manager Parameter Store or AWS Secrets Manager to store secrets, and have the script fetch them at runtime. You can also use IAM instance profiles to grant the instance permissions to read those secrets. Another security point: user data is visible to anyone with ec2:DescribeInstanceAttribute permission, so treat it as non-sensitive. If you must include a secret, use a secure method like aws ssm get-parameter with decryption.

Alternatives to User Data

User data is the simplest way to bootstrap an instance, but it has limitations. For more complex configuration management, you might use:

  • Ansible, Chef, or Puppet – these tools can be installed via user data, then they take over configuration.
  • Packer – build a custom AMI with all software preinstalled, so user data is minimal or unnecessary.
  • AWS Systems Manager State Manager – run scripts on a schedule or on demand, independent of instance launch.
  • EC2 Image Builder – automate the creation of custom AMIs with your software.

Each approach has trade-offs. User data is fast and free, but it is not idempotent by default and lacks error handling. For production workloads, a combination of a custom AMI (built with Packer) and a short user data script that pulls the latest configuration from a central store is often the most robust pattern.

Frequently Asked Questions

Can I update user data on an existing EC2 instance?

No, user data is only applied at launch. Changing the user_data argument in Terraform will cause Terraform to replace the instance (destroy and recreate) if you have user_data_replace_on_change = true; otherwise, Terraform will update the attribute but the running instance will not see the change. To apply new user data, you must either terminate and recreate the instance or use a different mechanism like SSM Run Command.

Does user data work with Windows EC2 instances?

Yes, but the format differs. For Windows, you provide a PowerShell script (with <powershell> tags) or a batch script. AWS runs it via EC2Launch (Windows Server 2016+) or EC2Config (older versions). The script runs on first boot, similar to Linux.

How do I pass a file to user data?

You can use the file() function in Terraform to read a local file and pass its contents as the user data string. For example: user_data = file("${path.module}/bootstrap.sh"). This is the simplest way to keep your script in a separate file.

What is the difference between user_data and user_data_base64?

The user_data argument expects a plain string, and Terraform base64-encodes it automatically. user_data_base64 expects a string that is already base64-encoded. Use user_data_base64 only if you have a pre-encoded string (e.g., from a data source that returns base64).

Can user data be used with spot instances?

Yes, spot instances support user data exactly like on-demand instances. You specify user data in the launch template or in the aws_spot_instance_request resource. The script runs on the spot instance when it launches.

Why is my user data script not running?

Common reasons: the script lacks a shebang line, the instance type does not support cloud-init (rare), the script has a syntax error, or the instance was launched from an AMI that does not include cloud-init. Check the cloud-init logs at /var/log/cloud-init-output.log to see the error. Also, ensure the script is not being blocked by a firewall or proxy.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →