Topic lessonTopic: EC2: launch and operation
EC2 user data explained: first-boot execution, a safe example and logs
User data supplies launch-time configuration or instructions to EC2. The operating system’s initialization tooling interprets the supplied data. This lesson uses Amazon Linux 2023, cloud-init and a Bash script that creates one file, separating execution identity, first boot and outcome verification.
Explain who runs user data and when, then understand a small initialization example without secrets and verify it through logs and an output artifact.
Know EC2 launch/connection and basic Linux files and permissions. The example assumes a fresh disposable AL2023 instance, not Windows or an arbitrary custom AMI. This site neither executes the code nor connects to AWS.
Separate the EC2 input from execution inside the OS
- User data → cloud-initEC2 holds the input; OS tooling interprets it.
- cloud-init → Run as rootAssumes first boot on AL2023; distinct from SSH login.
- Run as root → Logs and artifactSupplying the script alone does not prove success.
- User data
- Configuration or a script supplied at launch.
- cloud-init
- OS-side initialization tooling.
- Run as root
- Runs this form of shell user-data script.
- Logs and artifact
- Check processing evidence and intended output.
A normal AL2023 shell user-data script runs as root during the initial boot cycle. Root has elevated OS privileges. Avoid interactive prompts and do not add sudo inside this script. It is not automatically an every-reboot task; frequency depends on initialization tooling and configuration.
Example: create a completion file without network access
Assume a fresh disposable AL2023 instance where /var/lib/infra-lesson is not used for anything else. The example creates that directory and status.txt with a fixed completion message. It installs no packages, starts no public server, calls no AWS API and reads no secrets. Do not paste it into an existing system without review.
#!/bin/bash
set -eu
umask 027
install -d -m 0750 /var/lib/infra-lesson
printf '%s\n' 'initialization complete' > /var/lib/infra-lesson/status.txt
chmod 0640 /var/lib/infra-lesson/status.txt
printf '%s\n' 'lesson-bootstrap: complete'
| Part | Meaning | Boundary in this example |
|---|---|---|
| #!/bin/bash | Interpret the input as Bash | Shell user data, not cloud-config or Windows syntax |
| set -eu | Expose undefined variables and failed commands | It does not roll back earlier changes |
| umask / install | Set creation permissions and a dedicated directory | Root-owned exercise path; no conflict with other uses |
| printf / chmod | Write a fixed value and set mode 0640 | Overwrite status.txt rather than appending duplicates |
| Final printf | Emit a completion marker to standard output | Do not log secrets or customer data |
Check the input before launch and the result afterward
- Review the OS/AMI, cloud-init, Bash, output path and side effects; read the entire script first.
- For a real exercise, supply the plain shell example in User data under advanced launch settings. Let the normal console input handle Base64 rather than encoding twice.
- Allow initialization time, then inspect the instance through an approved connection method. Running state alone is not initialization success.
- Inspect /var/log/cloud-init-output.log for errors and the marker, then check the artifact’s content, owner and permissions.
- Reconcile retained data/resources and clean up after the exercise. Remove secrets and real-environment values before sharing logs.
sudo cat /var/lib/infra-lesson/status.txt
sudo ls -ld /var/lib/infra-lesson
sudo ls -l /var/lib/infra-lesson/status.txt
sudo tail -n 40 /var/log/cloud-init-output.logChoose an option to see the result and explanation.
Worked example: editing and rebooting are not the same as running
| Observation | What to check |
|---|---|
| User data was edited while stopped, but the file did not change after start | Normal first-boot frequency: editing alone does not imply execution |
| The log shows a failure and no final marker | The failed command and artifacts/permissions created before it |
| The SSH ec2-user cannot read the file | Root ownership, file mode 0640 and directory mode 0750 are intentional |
| You want to run the same script manually | Recheck existing state, overwrite path, privileges and side effects; this is not necessarily equivalent to first boot |
Idempotency means designing repeated identical input to preserve the intended state. This example overwrites a fixed value instead of appending duplicates. That does not make every initialization task safe to rerun, nor does it roll back earlier changes after a failure.
Choose an option to see the result and explanation.
Keep secrets out; separate OS root from AWS permissions
Running as OS root does not grant unrestricted AWS API access. A task that calls AWS APIs needs appropriate IAM-role and instance-profile conditions. Hardcoding an access key in the script is not a substitute.
Check, then explain in your own words
- Explain the OS tooling and execution identity.
- Verify frequency, logs and the output artifact separately.
- Review rerun side effects and secret protection.
Check your understanding: Does supplying user data make the same task run on every AMI?
No. It depends on the OS, initialization tooling, input format and execution conditions.
This example is scoped to AL2023, cloud-init, Bash and a fresh exercise path. Reassess execution identity and side effects whenever those conditions change.
Sources and conditions checked
The official references used in this lesson are collected here with their scope, conditions and corresponding sections. Independent expert review and live AWS comparison have not been performed.
Scope and conditionsLinux shell format, default first-boot/root execution, input encoding, output logs and editing versus execution. Does not apply these conditions to Windows or all custom AMIs.
Used in this lessonSeparate the EC2 input from execution inside the OS Worked example: editing and rebooting are not the same as running Keep secrets out; separate OS root from AWS permissions
Scope and conditionsAL2023 cloud-init interprets user-data and performs OS initialization. The authored script does not change cloud-init frequency or perform package actions.
Used in this lessonSeparate the EC2 input from execution inside the OS
Scope and conditionsMetadata/user-data visibility and prohibition on embedding passwords/long-lived keys. No metadata or live credentials are retrieved by this lesson.
Used in this lessonKeep secrets out; separate OS root from AWS permissions
- IAM roles for Amazon EC2Checked:
Scope and conditionsTemporary role credentials through an instance profile and least privilege for AWS API use, distinct from root inside the OS.
Used in this lessonKeep secrets out; separate OS root from AWS permissions