cc-ci-orchestrator/cc-ci-plan/plan-prepull-images.md

Sub-plan — pre-pull a recipe's images at the start of its test sequence

Status: QUEUED — a small harness addition to runner/run_recipe_ci.py (+ harness). Picks up as a near-term Phase-2 harness unit (not a phase-pause). Auto-applies in the nightly all-recipes run. Owner: Builder + Adversary loops. This file: /srv/cc-ci/cc-ci-plan/plan-prepull-images.md

---

What

At the start of a recipe's test sequence — before the first abra app deploy (and before the upgrade tier's new-version deploy) — resolve the recipe's images and docker pull them so they are in the local store before the deploy runs.

# at the top of the per-recipe run, after `abra app new` + checkout + .env set:
imgs = docker compose --env-file <app .env> -f <COMPOSE_FILE> config --images   # resolves interpolation
for img in imgs:
    docker image inspect "$img" >/dev/null 2>&1 || docker pull "$img"   # skip-if-present (pinned tags)
# then the normal:  abra app deploy …    (unchanged — real abra)
# repeat the pre-pull for the UPGRADE target image set before `abra app upgrade`.

Why

• Separate "pull" from "converge." A rate-limit / bad-tag / slow-pull then fails fast and clearly as a pull error, instead of surfacing later as a murky not converged deploy timeout (the F2-12-class confusion).
• Faster, more reliable convergence. Images already local → swarm starts services immediately → the deploy fits abra's native convergence window better (supports "prefer abra convergence" — can reduce the -c/READY_PROBE workaround for pull-bound cases).
• Nightly: the all-recipes nightly run pre-pulls implicitly, warming the cache for everything.

Cheap on a warm cache (the key property)

docker pull image:tag does not re-download cached layers — it does a cheap manifest check and reports Already exists; only missing/changed layers download. With coop-cloud's pinned (immutable) tags, the skip-if-present check (docker image inspect) makes it zero network when already cached. So per-test pre-pull is near-free after the first/nightly pull; it only does real work on a cold image or an upgrade to a genuinely new version.

Honest caveats

• Removes pull time/variance from convergence, NOT app-init time. Slow-starting apps (collabora's heavy init, F2-12) still need the recipe healthcheck/start_period (plan-lasuite-drive-recipe-pr.md). Pre-pull is complementary, not a replacement.
• Resolve via docker compose config --images (handles $VERSION-style interpolation) using the same COMPOSE_FILE set abra uses (read from the app .env) — a naive grep image: misses interpolated tags and multi-compose recipes.
• Not an abra bypass. docker pull only warms the local store; the deploy is still real abra app deploy/upgrade. Consistent with the "real abra commands" guardrail.
• Don't weaken anything — a failed pre-pull is a real (clearer) test failure, reported as such.

Definition of done (Adversary cold-verifies)

• Pre-pull step runs at the start of the recipe sequence (before the deploy) and before the upgrade tier's new-version deploy; images resolved correctly (incl. interpolation, multi-compose).
• Cheap on warm cache: a 2nd run's pre-pull does no layer re-download (skip-if-present, or Already exists); proven.
• Clear failure mode: a pull failure (e.g. a deliberately-bad tag) is reported as a pull error before deploy, not as a deploy/convergence timeout.
• No test weakened; deploy path unchanged (real abra). Bounded — this one step only.

Scope note

Per-test pre-pull only (at the recipe sequence start + upgrade). NOT a boot-time "pull all enrolled recipes" sweep — the local cache already accumulates across runs and the nightly all-recipes run warms everything, so per-test is the simple, targeted form.