|
| 1 | +--- |
| 2 | +title: "Bootstrap until ready (custom setup)" |
| 3 | +description: "Run packages or a setup script before grain says the sandbox is ready — with status you can watch." |
| 4 | +section: get-started |
| 5 | +keywords: |
| 6 | + - bootstrap |
| 7 | + - readiness |
| 8 | + - userdata |
| 9 | + - apt |
| 10 | + - setup script |
| 11 | + - wait bootstrap |
| 12 | + - custom image |
| 13 | +--- |
| 14 | + |
| 15 | +**Goal:** create a VM, run your install/setup steps, and only get a shell (or next command) when those steps finished **with zero failures**. |
| 16 | + |
| 17 | +Stock `grain-ubuntu` is already “ready” when the agent is up. This page is for **custom** first-boot work (apt, scripts, image authors). |
| 18 | + |
| 19 | +Deep reference: [Readiness protocol](../explain/readiness/). |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## 1. What “ready” means here |
| 24 | + |
| 25 | +A sandbox is ready when: |
| 26 | + |
| 27 | +1. The **VM is up** and the **guest agent** is healthy, and |
| 28 | +2. Your **bootstrap** finished successfully (`state=ready`), with **no failed steps**. |
| 29 | + |
| 30 | +If bootstrap fails, create errors and the VM is **left running** so you can inspect logs and fix. |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## 2. Minimal path (cloud-init) |
| 35 | + |
| 36 | +Save this as `bootstrap.yaml` on the **host**: |
| 37 | + |
| 38 | +```yaml |
| 39 | +#cloud-config |
| 40 | +runcmd: |
| 41 | + - | |
| 42 | + set -euo pipefail |
| 43 | + dir=/var/lib/grain/readiness |
| 44 | + mkdir -p "$dir" /var/lib/grain |
| 45 | +
|
| 46 | + echo running >"$dir/state" |
| 47 | + echo packages >"$dir/phase" |
| 48 | + echo "installing git" >"$dir/message" |
| 49 | +
|
| 50 | + export DEBIAN_FRONTEND=noninteractive |
| 51 | + apt-get update -qq |
| 52 | + apt-get install -y -qq git |
| 53 | +
|
| 54 | + echo ready >"$dir/state" |
| 55 | + echo my-stack >"$dir/ready_name" |
| 56 | + date -u +"%Y-%m-%dT%H:%M:%SZ" >"$dir/updated_at" |
| 57 | + touch /var/lib/grain/userdata-ran |
| 58 | +``` |
| 59 | +
|
| 60 | +Create and **wait for bootstrap**: |
| 61 | +
|
| 62 | +```bash |
| 63 | +grain up |
| 64 | +grain image pull grain-ubuntu # or your custom image |
| 65 | +grain new --userdata-file ./bootstrap.yaml --wait bootstrap -n lab |
| 66 | +``` |
| 67 | + |
| 68 | +While it runs you should see create progress mention bootstrap / your `message`. When it returns successfully, bootstrap completed with no failures. |
| 69 | + |
| 70 | +```bash |
| 71 | +grain status lab |
| 72 | +grain health lab |
| 73 | +grain sh lab |
| 74 | +``` |
| 75 | + |
| 76 | +--- |
| 77 | + |
| 78 | +## 3. Report progress from a script |
| 79 | + |
| 80 | +Inside the guest (or in runcmd), use the same files — or copy [scripts/grain-ready-report.sh](https://github.com/cxdy/grain/blob/main/scripts/grain-ready-report.sh) into the image: |
| 81 | + |
| 82 | +```bash |
| 83 | +grain-ready-report running packages "apt-get install …" |
| 84 | +# … work … |
| 85 | +grain-ready-report ready |
| 86 | +# on error: |
| 87 | +# grain-ready-report failed "" "setup.sh exit 1" |
| 88 | +``` |
| 89 | + |
| 90 | +Files live under `/var/lib/grain/readiness/` (`state`, `phase`, `message`, `error`, …). |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +## 4. Watch status |
| 95 | + |
| 96 | +```bash |
| 97 | +grain status lab |
| 98 | +# lab status=running … readiness=running phase=packages "installing git" |
| 99 | + |
| 100 | +grain health lab # full JSON including readiness |
| 101 | +``` |
| 102 | + |
| 103 | +--- |
| 104 | + |
| 105 | +## 5. Common failures |
| 106 | + |
| 107 | +| Symptom | Check | |
| 108 | +|---------|--------| |
| 109 | +| Create hangs on bootstrap | Guest never wrote `state=ready` — look at `grain logs -f lab` | |
| 110 | +| Create errors, VM still there | Bootstrap wrote `state=failed` or timed out — `grain status` / logs, then `grain rm lab` | |
| 111 | +| Stock image, no custom setup | Use default wait (`agent` for goldens); you don’t need this guide | |
| 112 | + |
| 113 | +--- |
| 114 | + |
| 115 | +## Next |
| 116 | + |
| 117 | +- Full contract (states, wait modes, agent API): [Readiness protocol](../explain/readiness/) |
| 118 | +- Named create defaults: [Profiles & presets](../guides/profiles/) |
| 119 | +- Baking faster images later: [Images](../guides/images/) |
0 commit comments