Cloud-Init — A Visual Blueprint
“The first 60 seconds of an EC2 instance’s life, choreographed.”
🌅 1. The Big Picture (Mental Metaphor)
Imagine a new hire on Day 1.
HR gives them: cloud-init gives the VM:
───────────── ─────────────────────
• ID badge ───► • hostname / SSH keys
• Laptop setup ───► • packages installed
• Onboarding doc ───► • user-data script
• Email/Slack ───► • network + DNS
• Welcome lunch ───► • final "ready" signal
After lunch → they're productive.
After cloud-init → the VM is production-ready.Cloud-init is the universal “onboarding officer” that runs once when a cloud VM first boots, turning a generic image into your server.
🗺️ 2. Where Cloud-Init Lives (System Map)
┌──────────────────────────────────────────────────────────────┐
│ CLOUD PROVIDER │
│ ┌─────────────┐ ┌───────────────┐ ┌────────────────┐ │
│ │ AMI/Image │ │ Metadata │ │ User-Data │ │
│ │ (Ubuntu 22) │ │ Service │ │ (your script) │ │
│ └─────────────┘ │ 169.254.169 │ └────────────────┘ │
│ │ │ .254 │ │ │
│ │ └───────┬───────┘ │ │
│ ▼ │ │ │
│ ┌──────────────────────────▼────────────────────▼─────────┐ │
│ │ VM BOOTS │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ cloud-init (4 stages) │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘Key insight: cloud-init = the glue between
the immutable image ↔ the per-VM metadata ↔ your runtime config.
🔄 3. The 4 Boot Stages (Flowchart)
Power-On
│
▼
┌──────────────────┐
│ ① generator │ Decide: "Do I run at all?"
│ (systemd) │ → reads kernel cmdline
└────────┬─────────┘
▼
┌──────────────────┐ Network: ❌ not yet
│ ② local │ Tasks: detect datasource,
│ cloud-init │ set hostname, fs resize
└────────┬─────────┘
▼
┌──────────────────┐ Network: ✅ up
│ ③ network │ Tasks: fetch metadata + user-data
│ cloud-init │ configure NTP, mounts
└────────┬─────────┘
▼
┌──────────────────┐ Tasks: install packages,
│ ④ config │ write files, create users,
│ cloud-config │ add SSH keys, run cmds
└────────┬─────────┘
▼
┌──────────────────┐ Tasks: user scripts (runcmd),
│ ⑤ final │ boot finished signal,
│ cloud-final │ snapshot of all logs
└────────┬─────────┘
▼
System ready ✅ (~30-90 s after power-on)Mnemonic: G-L-N-C-F → “Generator, Local, Network, Config, Final”
🧱 4. Anatomy of Inputs (Layered Framework)
WHO TELLS THE VM WHAT TO DO?
────────────────────────────
Layer 4: USER-DATA ← You write this
(cloud-config YAML, (most customization happens here)
shell script,
MIME multi-part)
Layer 3: VENDOR-DATA ← Cloud provider injects
(defaults from AWS, (e.g. AWS SSM Agent setup)
Azure, GCP)
Layer 2: METADATA ← Read from 169.254.169.254
(instance-id, hostname, (immutable per-instance facts)
AZ, IAM role, tags)
Layer 1: DATASOURCE ← Auto-detected
(Ec2, Azure, GCE, (decides where to find layers 2-4)
NoCloud, OpenStack)
Layer 0: /etc/cloud/cloud.cfg ← Image author baked this in
(which modules run, (the "rulebook")
in what order)Causal chain:
cloud.cfg → picks datasource → pulls metadata + user-data
│
▼
modules execute
in defined order📝 5. The Star of the Show: #cloud-config (Cheat Sheet)
#cloud-config ← THIS MAGIC HEADER is mandatory
# ─────────────────────────────────────────────────
hostname: web-01 ← Identity
fqdn: web-01.example.com
users: ← Who can log in
- name: deploy
sudo: ALL=(ALL) NOPASSWD:ALL
ssh_authorized_keys:
- ssh-ed25519 AAAA...
package_update: true ← What software
package_upgrade: true
packages:
- nginx
- jq
write_files: ← What config
- path: /etc/nginx/conf.d/app.conf
content: |
server { listen 80; ... }
runcmd: ← What to execute
- systemctl enable --now nginx
- curl https://example.com/register
final_message: "Booted in $UPTIME s"Visual pattern: Identity → Users → Packages → Files → Commands → Signal done
⚖️ 6. user-data Formats (Comparison)
┌───────────────────┬─────────────────────┬──────────────────────┐
│ Format │ Header │ When to use │
├───────────────────┼─────────────────────┼──────────────────────┤
│ cloud-config │ #cloud-config │ Declarative, │
│ (YAML) │ │ idempotent ✅ │
├───────────────────┼─────────────────────┼──────────────────────┤
│ Shell script │ #!/bin/bash │ Quick & dirty, │
│ │ │ imperative │
├───────────────────┼─────────────────────┼──────────────────────┤
│ MIME multipart │ Content-Type: ... │ Combine both │
├───────────────────┼─────────────────────┼──────────────────────┤
│ Jinja template │ ## template:jinja │ Render with │
│ │ #cloud-config │ metadata vars │
├───────────────────┼─────────────────────┼──────────────────────┤
│ Gzip / Base64 │ (binary) │ Bypass 16 KB limit │
└───────────────────┴─────────────────────┴──────────────────────┘Rule of thumb:
Declarative (cloud-config) for config, imperative (script) for one-shot actions.
🔁 7. Idempotency & Re-Runs (Mental Model)
First boot: Subsequent boots:
───────────── ──────────────────
▲ ▲
│ all modules │ only "always" modules
│ execute │ (e.g. NTP, network)
│ │ "once" modules SKIP
│ /var/lib/cloud/ │ via stamp files in
│ instance/sem/ │ /var/lib/cloud/sem/
│ *.once ◄───────────────┘ ┌──────────────────┐
debug rerun ───► cloud-init clean ├───► next reboot
│ (wipes stamps) │ re-runs everything
└──────────────────┘Mental hook: Stamp file present? Skip. Missing? Run.
🔍 8. Forensics — Where Things Live (Map)
/etc/cloud/
├── cloud.cfg ← master config (modules + order)
├── cloud.cfg.d/ ← drop-ins (vendor + user overrides)
└── templates/ ← hostname, hosts, etc.
/var/lib/cloud/
├── instance/ ← symlink → current instance
│ ├── user-data.txt ← raw user-data as received
│ ├── cloud-config.txt ← rendered cloud-config
│ ├── scripts/ ← runcmd & per-boot scripts
│ └── sem/ ← "I already ran" stamps
└── instances/<iid>/ ← history per instance
/var/log/
├── cloud-init.log ← every module call (verbose)
└── cloud-init-output.log ← stdout/stderr of scriptsDebug recipe:
See also: Mastering the Linux Command Line — Your Complete Free Training Guide
cloud-init status --long # current state
cloud-init query --all # all known vars (metadata, ds, etc.)
sudo cloud-init schema --system # validate config
sudo tail -f /var/log/cloud-init-output.log⏱️ 9. Timeline: A Real Boot
0 s ┃ Hypervisor starts VM
2 s ┃ Kernel loaded
4 s ┃ systemd reaches "cloud-init.target"
5 s ┃ ② local stage — hostname set
8 s ┃ DHCP gets IP
10 s ┃ ③ network stage — fetch user-data from
┃ http://169.254.169.254/latest/user-data
15 s ┃ ④ config stage — apt update, install nginx
45 s ┃ ⑤ final stage — runcmd, write final_message
46 s ┃ EC2 status check goes ✅
Terraform sees "instance running" and continues🧠 10. Cause-and-Effect: Why Things Break
Symptom Root cause
───────────────────────────────── ─────────────────────────────
Hostname stays "ip-10-…" ◄─── user-data missing #cloud-config
header → treated as garbage
SSH keys not added ◄─── IAM role can't read metadata,
or instance in private subnet
without VPCe to metadata
"runcmd" never executes ◄─── YAML indentation error
(silent skip — check schema!)
Re-run does nothing ◄─── Stamp files exist;
need: cloud-init clean --logs
Boot takes 5 min ◄─── `package_upgrade: true` over
slow NAT → upgrade megabytes🧬 11. Cloud-Init in Your Terraform Context
[Terraform admin-host module]
│
▼
creates aws_instance
│
│ user_data = <<-EOF
│ #cloud-config
│ hostname: adminhost
│ write_files: …
│ runcmd: [bootstrap-ansible.sh]
│ EOF
▼
EC2 boots from AMI:
│
▼
cloud-init takes over:
① reads metadata (IAM role, AZ, tags)
② applies hostname, SSH keys
③ runs bootstrap (joins consul, registers DNS)
│
▼
Instance is "an adminhost" ✅Insight: That’s why baking a minimal AMI + delegating to cloud-init
is more flexible than baking everything into the image — same image,
different roles across environments.
🎯 12. Mental Snapshot (One Picture to Remember Everything)
┌─────────────────────────────────────────┐
│ CLOUD-INIT IN ONE FRAME │
├─────────────────────────────────────────┤
│ │
│ Generic Image + Per-VM Recipe │
│ │ │ │
│ └──────┬─────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ cloud-init │ ← runs ONCE │
│ │ G→L→N→C→F │ (stamps it) │
│ └───────┬────────┘ │
│ ▼ │
│ Unique, ready VM │
│ │
│ Inputs: metadata + user-data │
│ Where: /etc/cloud + /var/lib/cloud │
│ Logs: /var/log/cloud-init*.log │
│ Debug: `cloud-init status --long` │
│ │
└─────────────────────────────────────────┘One-line mantra:
“Image is the body, cloud-init is the soul that arrives on first breath.”