Skip to content
Skills Library
DevOps & cloud · Automation

linux-cloud-init

/linux-cloud-init

Use when authoring, validating, or debugging cloud-init user-data, Ubuntu autoinstall, or RHEL-family Kickstart for first-boot provisioning. Use linux-server-provisioning for interactive post-boot setup and linux-config-management for ongoing desired state.

Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
2
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use when authoring, validating, or debugging cloud-init user-data, Ubuntu autoinstall, or RHEL-family Kickstart for first-boot provisioning. Use linux-server-provisioning for interactive post-boot setup and linux-config-management for ongoing desired state.

Original author description

Use when authoring, validating, or debugging cloud-init user-data, Ubuntu autoinstall, or RHEL-family Kickstart for first-boot provisioning. Use linux-server-provisioning for interactive post-boot setup and linux-config-management for ongoing desired state.

How it works

  1. Distro support
  2. Use when
  3. Do not use when
  4. Required inputs
  5. Workflow
  6. Quality standards
  7. Anti-patterns
  8. Outputs
  9. References
  10. Evidence Produced
Original SKILL.md headings · 398 lines, 2,076 words
SKILL.md preview
---
name: linux-cloud-init
description: Use when authoring, validating, or debugging cloud-init user-data, Ubuntu autoinstall, or RHEL-family Kickstart for first-boot provisioning. Use linux-server-provisioning for interactive post-boot setup and linux-config-management for ongoing desired state.
license: MIT
metadata:
  portable: true
  compatible_with:
  - claude-code
  - codex
  author: Peter Bamuhigire
  author_url: techguypeter.com
  author_contact: "+256784464178"
---

# Linux cloud-init

## Distro support

Two-family skill — but mind the distinction:

- **cloud-init `user-data` / cloud-config is portable** — the same file runs on
  Ubuntu and Fedora/RHEL cloud images.
- **OS-install automation is NOT portable** — Ubuntu uses **autoinstall**
  (subiquity); the RHEL family (Fedora, RHEL, CentOS Stream, Rocky, Alma,
  Oracle) uses **Kickstart** (Anaconda). See
  [`references/kickstart-reference.md`](references/kickstart-reference.md).

| Concept | Debian/Ubuntu | RHEL family |
|---|---|---|
| Install automation | autoinstall (subiquity) | **Kickstart** (Anaconda) |
| Install config | `autoinstall:` schema | `.ks` directives, `inst.ks=` boot arg |
| First-boot config | cloud-init `user-data` | cloud-init `user-data` (same) |
| Admin group in cloud-config | `sudo` | `wheel` |
| Default cloud user | `ubuntu` | `fedora` / `cloud-user` / `ec2-user` |
| Time pkg in cloud-config | `systemd-timesyncd` | `chrony` |
| Network rendering | cloud-init → Netplan | cloud-init → NetworkManager |

Write **distro-neutral** cloud-config where possible (use `package_update`,
network-config v2, and group `wheel` on RHEL). See
[`references/kickstart-reference.md`](references/kickstart-reference.md) and
[`docs/multi-distro/plan.md`](../../docs/multi-distro/plan.md).

<!-- dual-compat-start -->
## Use when

- Designing or validating `cloud-init` user-data for first boot.
- Debugging why a cloud-init or autoinstall run failed.
- Bootstrapping a fresh Ubuntu server from declarative YAML rather than manual provisioning.

## Do not use when

- The server is already live and you only need manual provisioning changes; use `linux-server-provisioning`.
- The task is ordinary network or package troubleshooting outside cloud-init execution.

## Required inputs

| Artefact | Source | Required? | If absent |
|---|---|---|---|
| User-data, autoinstall file, Kickstart file, or failure logs | Operator, image build, or affected host | required | Stop authoring or diagnosis and request the actual input. |
| Target distribution, release, image, and cloud/installer context | Operator or image metadata | required | Return a family-neutral outline; do not claim deployability. |
| Desired users, keys, packages, network state, and commands | Provisioning requirement | required for authoring | Produce a validation-only report if requirements are incomplete. |

## Workflow

1. Confirm whether the task is new authoring, validation, or post-failure debugging.
2. Validate the YAML structure and cloud-init semantics before deployment.
3. Follow the matching workflow below for user-data, autoinstall, or bootstrap scenarios.
4. Inspect logs and rendered state after boot to prove the config applied as intended.
5. Stop if parsing fails, the target family is unknown, required access would be lost, or a secret is embedded.
6. Recover a failed test by correcting the source and rebuilding a disposable instance; do not treat rerunning once-per-instance modules as recovery.

## Quality standards

- Keep configurations reproducible, explicit, and safe for unattended execution.
- Validate before rollout, especially for multi-server deployments.
- Treat logs and instance state as the source of truth when debugging.

## Anti-patterns

- Shipping unvalidated YAML to multiple servers. Fix: run schema and syntax checks, then boot one disposable instance.
- Mixing first-boot responsibilities with ongoing state management. Fix: hand repeatable post-boot state to `linux-config-management`.
- Assuming a failed command ran. Fix: inspect `cloud-init status --long`, stage logs, and rendered configuration.
- Using Ubuntu package names or the `sudo` group on a RHEL image. Fix: branch on the target family and use `wheel` plus family-correct packages.
- Retrying a poisoned instance indefinitely. Fix: correct the source input and rebuild because most cloud-init modules run once per instance.

## Outputs

| Artefact | Consumer | Acceptance condition |
|---|---|---|
| Validated provisioning configuration | Image builder or cloud operator | Parser/schema checks pass and family-specific values match the target image. |
| Failure diagnosis | Incident owner | Names the failed stage, log evidence, root cause, and safe retry/rebuild path. |
| First-boot verification record | Provisioning handoff | Required users, SSH access, packages, services, and network state are observed on a test instance. |

## References

- [`references/user-data-reference.md`](references/user-data-reference.md)
- [`references/autoinstall-reference.md`](references/autoinstall-reference.md)
- [`references/debugging.md`](references/debugging.md)

## Evidence Produced

| Artefact | Acceptance condition |
|---|---|
| Provisioning validation evidence | Contains parser output, test-instance `cloud-init status --long`, relevant log excerpts, and checks for every declared outcome. |

## Capability contract

Read access to the source configuration is required. Execution on a disposable target is preferred. Editing, image publication, or production rebuilds require explicit authority; never place private keys or plaintext secrets in evidence.

## Degraded mode

If no parser or disposable instance is available, perform a read-only structural review, label runtime checks `not assessed`, and return the exact commands the operator must run. An unbooted configuration is not validated.

## Decision rules

| Choice | Action | Failure or risk avoided |
|---|---|---|
| Existing cloud image first boot | Use cloud-config/user-data | Installer-only directives being ignored. |
| Bare-metal or ISO install | Use Ubuntu autoinstall or RHEL Kickstart | Applying the wrong installer schema. |
| Ongoing configuration drift | Hand off to `linux-config-management` | Re-running once-per-instance modules as a configuration manager. |

## Worked example

For a Rocky Linux image that must create an administrator and install Nginx, select cloud-config, use the `wheel` group and RHEL package names, validate the YAML, boot one disposable VM, then record the created user, key-only login, package version, and service state before scaling out.

<!-- dual-compat-end -->

**This skill is self-contained.** Every command below is a standard tool
present on both families (`cloud-init`, `journalctl`, `yamllint`) — see the
**Distro support** matrix above for what is portable versus family-specific.
The `sk-*`
scripts in the **Optional fast path** section are convenience wrappers —
never required.

This skill owns **first-boot provisioning from YAML** — cloud-init
user-data on cloud images (portable across both families), plus the
OS-install flow on the installer: Ubuntu's autoinstall and the RHEL
family's Kickstart (see
[`references/kickstart-reference.md`](references/kickstart-reference.md)).
It is the mechanism that takes a blank cloud image and turns it into a
server ready for `linux-server-provisioning` to finish.

It does **not** own:

- **Interactive post-boot setup** — `linux-server-provisioning`.
- **Cloud provider APIs** (creating the VM in the first place) — out of
  scope.
- **Ongoing configuration management** — `linux-config-management`.

Informed by the Canonical *Ubuntu Server Guide* (cloud-init, autoinstall
chapters).

---

## When to use

- Writing a `user-data` YAML for a cloud image.
- Writing an Ubuntu `autoinstall` config for a new installer ISO.
- Validating user-data before feeding it to a cloud provider.
- Debugging why a first-boot didn't install packages or create users.
- Extracting errors from `/var/log/cloud-init*.log` on a provisioned host.

## When NOT to use

- Day-2 config changes — use `linux-config-management` (Ansible).
- Manual post-boot steps — run the relevant `linux-*` skill directly.

---

## Standing rules

1. **Validate every user-data file before using it.** A broken
   user-data silently ignores modules — you end up with an
   under-configured server.
2. **Never put secrets in plain-text user-data.** cloud-init caches it
   under `/var/lib/cloud/` where it can be read later. Use vaulted
   values or post-boot pulls from a secret store.
3. **`runcmd` is last resort.** Prefer first-class modules (`users`,
   `packages`, `write_files`, `ssh_authorized_keys`) where possible.
   They log cleanly and are idempotent-friendly.
4. **The very last `runcmd` step in every production server user-data
   should install linux-skills.** Templates live in the references.
5. **Debug with the logs.** `/var/log/cloud-init.log` has the module
   trace; `/var/log/cloud-init-output.log` has stdout/stderr of
   `runcmd`.
6. **Autoinstall is a different schema than runtime user-data.** Don't
   cross them over. Autoinstall's cloud-init runs in a restricted
   installer environment.

---

## Quick reference — manual commands

### Validate a user-data file

```bash
# Built-in schema check (requires cloud-init installed)
cloud-init schema --config-file user-data.yaml

# With verbose output
cloud-init schema --config-file user-data.yaml --strict

# YAML syntax check first (basic)
yamllint user-data.yaml
```

### Inspect cloud-init state on a running server

```bash
# Overall status
cloud-init status --long

# How long each stage took
cloud-init analyze show
cloud-init analyze blame                    # slowest modules
cloud-init analyze dump                     # full event stream

# What datasource was used?
cloud-init query --format '{{ ds.platform }} / {{ ds.region }}'

# All the collected facts (ds metadata + user-data + vendor-data)
cloud-init query --all
```

### Debug a failed run

```bash
# Main log — module start/end, failures, tracebacks
sudo less /var/log/cloud-init.log

# runcmd output
sudo less /var/log/cloud-init-output.log

# Filter for errors only
sudo grep -iE "error|fail|traceback" /var/log/cloud-init.log

# See which modules ran at each stage
sudo grep "Running module" /var/log/cloud-init.log

# Reset cloud-init and re-run (for testing in a disposable VM)
sudo cloud-init clean --logs --seeds
sudo reboot
```

### Autoinstall debugging (during install)

```bash
# Installer has its own logs (on the target system during install)
sudo less /var/log/installer/cloud-init.log
sudo less /var/log/installer/curtin-install.log
sudo less /var/log/installer/subiquity-server-debug.log

# After install, look for autoinstall-specific failures
sudo journalctl -u cloud-init -u cloud-config -u cloud-final
```

Full user-data reference (every common module with 5 worked examples,
module ordering, idempotency, secrets note, datasource detection) — see
[`references/user-data-reference.md`](references/user-data-reference.md).

Full autoinstall reference (schema, storage layouts, LVM, ZFS,
autoinstall ISO build, serving over HTTP for PXE, 3 complete autoinstall
examples) — see
[`references/autoinstall-reference.md`](references/autoinstall-reference.md).

Full debugging guide (log layout, status decoding, re-run workflow) —
see [`references/debugging.md`](references/debugging.md).

---

## Typical workflows

### Workflow: "Validate this user-data before I deploy 10 servers with it"

```bash
# 1. YAML sanity
yamllint user-data.yaml

# 2. cloud-init schema validation
cloud-init schema --config-file user-data.yaml --strict

# 3. Visual review of the modules it will run
grep -E '^[a-z_]+:' user-data.yaml

# 4. Check that runcmd uses absolute paths
grep -A20 '^runcmd:' user-data.yaml

# 5. Boot one in a disposable cloud VM or LXD container
lxc launch ubuntu:24.04 test --config=user.user-data="$(cat user-data.yaml)"
lxc exec test -- cloud-init status --wait
lxc exec test -- cloud-init status --long
lxc delete test --force
```

### Workflow: "Why didn't my first-boot install nginx?"

```bash
sudo cloud-init status --long                     # overall result
sudo grep -A2 "packages" /var/log/cloud-init.log  # what package list was seen
sudo grep -iE "error|fail" /var/log/cloud-init-output.log | head -20

# Common causes:
#   - packages: - nginx   (YAML dash indentation wrong)
#   - package_update: false   (apt index is stale)
#   - package_upgrade: true + slow mirror = timeout
#   - apt sources unreachable
```

### Workflow: "Bootstrap linux-skills via cloud-init"

Put this as the final `runcmd` block in your production user-data:

```yaml
#cloud-config
users:
  - name: administrator
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    ssh_authorized_keys:
      - ssh-ed25519 AAAA... admin@example
packages:
  - git
  - curl
  - unattended-upgrades
runcmd:
  - sudo -u administrator bash -lc 'git clone https://github.com/<org>/linux-skills.git ~/.claude/skills'
  - sudo bash /home/administrator/.claude/skills/scripts/setup-claude-code.sh
  # Once install-skills-bin is available:
  # - sudo /usr/local/bin/install-skills-bin core
```

Full templates for a web server, Docker host, LXD guest, and database
server in [`references/user-data-reference.md`](references/user-data-reference.md).

### Workflow: "Build an autoinstall ISO"

```bash
# Write the autoinstall user-data (see references/autoinstall-reference.md)
# and a meta-data file (can be empty):
mkdir /tmp/autoinstall
cat > /tmp/autoinstall/user-data <<'EOF'
#cloud-config
autoinstall:
  version: 1
  identity:
    hostname: web01
    username: administrator
    password: '$6$...'     # crypt(3) hash
  ssh:
    install-server: true
    authorized-keys:
      - ssh-ed25519 AAAA...
  # ... rest of the autoinstall config
EOF

touch /tmp/autoinstall/meta-data

# Validate
cloud-init schema --config-file /tmp/autoinstall/user-data

# Serve over HTTP (trivial option)
cd /tmp/autoinstall && python3 -m http.server 3003
# Boot the installer with ds=nocloud-net;s=http://your-server:3003/
```

---

## Troubleshooting / gotchas

- **Indentation errors pass YAML parse but break cloud-init.** `yamllint`
  doesn't enforce cloud-init semantics. Use
  `cloud-init schema --config-file` as the real validator.
- **`runcmd` with a relative path fails silently.** Always use absolute
  paths: `/usr/bin/apt-get`, not `apt-get`. cloud-init's PATH is
  minimal at runcmd time.
- **Modules run once per instance-id.** Re-running a playbook requires
  `sudo cloud-init clean` (deletes state) + reboot. Without that,
  cloud-init thinks it's already done.
- **Long `package_upgrade: true` on a slow mirror times out.** The
  install appears to hang, then continue without the upgraded packages.
  Use `package_upgrade: false` for user-data where speed matters; run
  `unattended-upgrades` after boot instead.
- **Autoinstall storage config is unforgiving.** A typo in the `storage`
  section produces an install that hangs at partitioning. Validate with
  `cloud-init schema` and test in a VM before shipping the ISO.
- **`write_files` default encoding is text, not base64.** For binary
  files set `encoding: b64` explicitly.
- **`users:` module replaces the default user completely** unless you
  include `- default` as the first entry.

---

## References

- [`references/user-data-reference.md`](references/user-data-reference.md) —
  full user-data reference: every module with examples, 5 complete
  worked templates, idempotency and secrets notes.
- [`references/autoinstall-reference.md`](references/autoinstall-reference.md) —
  full autoinstall schema, storage, network, 3 complete examples.
- [`references/kickstart-reference.md`](references/kickstart-reference.md) — Kickstart automated install (RHEL family)
- [`references/debugging.md`](references/debugging.md) — cloud-init
  logs, status decoding, re-run workflow, autoinstall debug.
- Book: *Ubuntu Server Guide* (Canonical) — cloud-init, autoinstall.
- Upstream: https://cloudinit.readthedocs.io/

---

## Script availability

No wrapper commands for this skill are shipped in this checkout. Use the native procedures above; planned wrappers remain in [the script inventory](../../docs/engine-design/script-inventory.md) until their source files are present.
Files in this package (5)
  • SKILL.md 16 KB
  • references/autoinstall-reference.md 20 KB
  • references/debugging.md 14 KB
  • references/kickstart-reference.md 6 KB
  • references/user-data-reference.md 21 KB

Versions

The database has no other skills named linux-cloud-init.

Database snapshot: 13.11.2026 · package version f00a1f116a9e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100linux-server-provisioning
    Use when interactively provisioning a fresh Debian/Ubuntu or RHEL-family server after first boot, including identity, admin access, updates, firewall, services, and verification. Use linux-cloud-init for unattended first boot and linux-config-management for repeatable fleet state.
  • 100linux-config-management
    Use when managing repeatable server state with Ansible, etckeeper, check mode, or drift remediation across Debian/Ubuntu and RHEL families. Use linux-server-provisioning for one-time bootstrap and linux-cloud-init for first boot.
  • 95linux-patcher
    Automated Linux server patching and Docker container updates. Use when the user asks to update, patch, or upgrade Linux servers, apply security updates, update Docker containers, check for system updates, or manage server maintenance across multiple hosts. Supports Ubuntu,…
  • 96linux-package-management
    Use when managing Ubuntu apps across apt, snap, Flatpak.
  • 95linux-server
    Linux (Ubuntu/Debian) server initial setup and ongoing administration skill. Covers new server hardening, user management, package management, file permissions, resource limits, log rotation, cron scheduling, and disk management. USE WHEN: - Performing initial setup of a fresh…
  • 90oci-os-management
    Operate OCI OS Management Hub for patching and update governance across Oracle Linux, Ubuntu, and Windows managed instances. Use for OS Management Hub registration, profiles, groups, dynamic sets, lifecycle environments, software sources, Ksplice, scheduled update jobs, reports,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.