cloud-init operations

v0.1.19

cloud-init introspection + boot diagnostics + stage re-runs. Use when an EC2/GCE/Azure VM finishes booting but the workload didn't come up the way it should: check overall status, blame slow modules, dump user-data / cloud-config / vendor-data as the instance actually saw them, tail the cloud-init logs, and (with operator approval) re-run individual modules or the full init pipeline.

13 allowed by default 9 need approval by default 1 denied by default

Pack ID

cloud-init

Vendor

emisar

linux

Actions

Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.


              cloud-init


              journalctl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host

sudo emisar pack install cloud-init --hash sha256:ca2eb822cd266554b8d196fe11d6b6e004aade41333e54e0f120f32d29fbe74a

Setup

Reads the local runner host's cloud-init status, logs, and results — no credentials needed.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read protected cloud-init state and logs, or rerun and clean boot stages, as root.

cloud-init.analyze_showcloud-init.analyze_blamecloud-init.analyze_dumpcloud-init.userdata_dumpcloud-init.cloud_config_dumpcloud-init.vendor_data_dumpcloud-init.log_tailcloud-init.output_log_tailcloud-init.journal_tailcloud-init.collect_logscloud-init.modules_configcloud-init.modules_finalcloud-init.single_modulecloud-init.init_localcloud-init.initcloud-init.clean_logscloud-init.clean

Run the Emisar service as root

Grant access

sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-cloud-init-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar

Verify access

test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root. Cloud-init reads may expose raw user-data secrets, and mutators can reapply provisioning or erase instance state.

Notes

Status, version, schema validation, and instance-id reads work without elevated host access.

Verify it works

Runs cloud-init.status, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host

sudo emisar pack verify cloud-init

Install and configure a pack walks through the whole sequence on a host.

Actions 23 total

View on GitHub

cloud-init.analyze_blame exec low

cloud-init analyze blame

List modules ranked by duration. The single fastest answer to "why did cloud-init take 90 seconds?" — the slow module is at the top.
View source on GitHub
cloud-init.analyze_dump exec low

cloud-init analyze dump

Dump raw event records from cloud-init.log as JSON. Useful for downstream tooling that wants structured timing data.
View source on GitHub
cloud-init.analyze_show exec low

cloud-init analyze show

Show per-stage timing for the most recent boot — when each stage started, duration, and which records contributed. Read-only.
View source on GitHub
cloud-init.clean exec critical

cloud-init clean

Wipe ALL cloud-init state — /var/lib/cloud/, logs, instance-id, module-run records. NEXT BOOT cloud-init treats the host as a brand-new instance and re-runs every module from scratch. Combine with a reboot to genuinely re-bootstrap the host. Catastrophic on a long-lived host where users have been added outside cloud-init — those won't be re-added.
View source on GitHub
cloud-init.clean_logs exec medium

cloud-init clean --logs

Truncate cloud-init logs without resetting instance state. Use to clear noisy stale errors before re-running a stage to confirm a fix worked.
View source on GitHub
cloud-init.cloud_config_dump exec high

cat /var/lib/cloud/instance/cloud-config.txt

Dump the final merged cloud-config (user-data + vendor-data + system defaults) as cloud-init evaluated it. The source of truth for "what did cloud-init actually try to do?". User-data classically embeds credentials, keys, and tokens, and the merged cloud-config is a superset of it; the runner's redaction is a pattern-bound backstop, not a guarantee.
View source on GitHub
cloud-init.collect_logs exec medium

cloud-init collect-logs

Bundle /var/log/cloud-init* + journals + config into a tarball under /tmp/cloud-init.tar.gz. Use when you need to share state with cloud-init upstream or attach to a support ticket.
View source on GitHub
cloud-init.init exec high

cloud-init init

Run the (non-local) init stage — fetch user-data + vendor-data, merge cloud-config, populate /var/lib/cloud/instance/. Without `cloud-init clean` first, an unchanged instance-id is a no-op.
View source on GitHub
cloud-init.init_local exec high

cloud-init init --local

Run the init-local stage — datasource detection, fallback networking, early disk setup. Normally only runs at boot. Re-running mid-life rarely useful except for testing a datasource fix.
View source on GitHub
cloud-init.instance_id exec low

cat /var/lib/cloud/data/instance-id

Show the instance ID cloud-init currently tracks. If this differs from the cloud's idea, cloud-init thinks the machine is "new" and may re-run all modules at next boot.
View source on GitHub
cloud-init.journal_tail exec medium

journalctl -u cloud-init -n <lines>

Tail systemd journal entries for the four cloud-init units (cloud-init, cloud-init-local, cloud-config, cloud-final). Use when boot failed before /var/log/cloud-init.log was even written.
View source on GitHub
cloud-init.log_tail exec medium

tail /var/log/cloud-init.log

Tail the main cloud-init log (last N lines). Contains module execution, errors, and per-stage timing.
View source on GitHub
cloud-init.modules_config exec high

cloud-init modules --mode=config

Re-run every module in the `config` stage (locale, users-groups, ssh, set-passwords, apt-pipelining, package-update-upgrade-install, etc.). Mutates the host the same way boot does. Use after fixing a buggy cloud-config — no need to reboot.
View source on GitHub
cloud-init.modules_final exec high

cloud-init modules --mode=final

Re-run every module in the `final` stage (runcmd, scripts-user, phone-home, power-state-change, etc.). Anything that was scripted to run "after first boot" runs again. Power-state modules can reboot/shutdown — make sure your cloud-config has no power-state directive before invoking.
View source on GitHub
cloud-init.output_log_tail exec medium

tail /var/log/cloud-init-output.log

Tail captured stdout/stderr from every command cloud-init ran during boot (`runcmd`, `bootcmd`, package install, etc.). Where to look when a shell command in cloud-config silently failed.
View source on GitHub
cloud-init.query_metadata exec high

cloud-init query <key>

Pull one key out of cloud-init's runtime metadata (instance-id, hostname, region, availability_zone, …), or pass `--all` (the default) to dump everything. cloud-init redacts sensitive values only for non-root callers: as root, `--all` and the `userdata` / `vendordata` / `combined_cloud_config` keys return raw user-data, which classically embeds credentials, keys, and tokens. The runner's redaction is a pattern-bound backstop, not a guarantee.
View source on GitHub
cloud-init.schema_validate exec low

cloud-init schema --system

Validate the rendered cloud-config against the cloud-init schema. Use to catch typos / deprecated keys before they cause a silent no-op on next boot.
View source on GitHub
cloud-init.single_module exec high

cloud-init single --name=<module>

Run one named cloud-init module out-of-band (e.g. `users-groups`, `ssh`, `runcmd`, `set_hostname`). The module is invoked with its current configuration; effects depend entirely on which module.
View source on GitHub
cloud-init.status exec low

cloud-init status

Show the current overall cloud-init state — `running`, `done`, `error`, `disabled`, or `not run`. Use as the first answer to "did boot finish?".
View source on GitHub
cloud-init.status_long exec low

cloud-init status --long [--wait]

Show detailed status — per-stage state, last update, recoverable + last errors, datasource detected. With `block: true`, blocks until cloud-init finishes (useful right after boot).
View source on GitHub
cloud-init.userdata_dump exec high

cat /var/lib/cloud/instance/user-data.txt

Dump raw user-data as cloud-init received it (after MIME decoding, before cloud-config merging). Compare against what you set in the launch config to confirm delivery. User-data classically embeds credentials, keys, and tokens; the runner's redaction is a pattern-bound backstop, not a guarantee.
View source on GitHub
cloud-init.vendor_data_dump exec high

cat /var/lib/cloud/instance/vendor-data.txt

Dump vendor-data the cloud provider injected (AWS / GCE / Azure provider defaults that ran before user-data). Useful when "why is X installed that I didn't ask for?" leads back to a vendor module. Vendor-data can embed the same credential material as user-data; the runner's redaction is a pattern-bound backstop, not a guarantee.
View source on GitHub
cloud-init.version exec low

cloud-init --version

Show the build + version string for the cloud-init on this host.
View source on GitHub

← Back to registry

Pack reference Publish your own