overlay policy: standardize the ccci overlay filename to compose.ccci.yml
Operator: use a single uniform filename `compose.ccci.yml` per recipe (one file
holding all cc-ci-side deploy tweaks) rather than per-purpose suffixes like
compose.ccci-health.yml. Updated §9 + plan-ccci-compose-overlay-policy.md; added
a DoD item to rename tests/{ghost,discourse}/compose.ccci-health.yml ->
compose.ccci.yml and update their install_steps.sh cp target + recipe_meta
COMPOSE_FILE.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@ -9,19 +9,21 @@
|
||||
|
||||
## 0. Policy (operator, 2026-05-30)
|
||||
|
||||
A cc-ci-authored compose overlay (`compose.ccci-*.yml` layered via `COMPOSE_FILE`) risks **drift** from
|
||||
the recipe users run — so **avoid where possible and justify each use**. But it is a **legitimate,
|
||||
uniform fallback pattern**, not forbidden:
|
||||
A cc-ci-authored compose overlay (the single `compose.ccci.yml`, layered via `COMPOSE_FILE`) risks
|
||||
**drift** from the recipe users run — so **avoid where possible and justify each use**. But it is a
|
||||
**legitimate, uniform fallback pattern**, not forbidden:
|
||||
|
||||
- **Prefer an upstream recipe PR** in most cases — a real robustness fix, or exposing a knob the recipe
|
||||
should expose. That's where a fix usually belongs.
|
||||
- **A ccci overlay is the right tool when the value can't be supplied any other way** — notably a
|
||||
healthcheck **`start_period`**, which **abra cannot take from an env var**. The ghost/discourse
|
||||
`start_period` bumps therefore **stay as overlays** (an env PR is impossible for that field).
|
||||
- **Uniform pattern (acceptable fallback):** an optional `compose.ccci-<purpose>.yml` per recipe,
|
||||
provided into the checkout by `install_steps.sh`, wired by `recipe_meta` `COMPOSE_FILE`, kept as an
|
||||
untracked file so it survives the upgrade `git checkout -f` (`CHAOS_BASE_DEPLOY=True`; `assert_upgraded`
|
||||
strips the `+U` marker — see DECISIONS 2026-05-30).
|
||||
- **Uniform pattern (acceptable fallback):** a single, fixed-name **`compose.ccci.yml`** per recipe
|
||||
(NOT per-purpose suffixes — one file holds all cc-ci-side deploy tweaks for that recipe), provided
|
||||
into the checkout by `install_steps.sh`, wired by `recipe_meta` `COMPOSE_FILE`
|
||||
(`compose.yml:compose.ccci.yml`), kept as an untracked file so it survives the upgrade
|
||||
`git checkout -f` (`CHAOS_BASE_DEPLOY=True`; `assert_upgraded` strips the `+U` marker — see
|
||||
DECISIONS 2026-05-30).
|
||||
- **Each overlay must:** be **minimal + single-purpose**, **document WHY** in its header (the exact
|
||||
abra/upstream limitation that forces it), and be **Adversary-confirmed** to not weaken a test or mask
|
||||
a recipe defect. Where the fix also belongs upstream (e.g. a `start_period` too tight for any slow
|
||||
@ -39,11 +41,16 @@ Don't drop the upgrade test because the *from* (older) version is awkward.
|
||||
|
||||
## 2. Disposition of the current overlays
|
||||
|
||||
- [ ] **ghost `compose.ccci-health.yml` (start_period 900s) — KEEP, justified.** abra can't env-param
|
||||
- [ ] **RENAME the overlay files to the uniform `compose.ccci.yml`.** `tests/ghost/compose.ccci-health.yml`
|
||||
and `tests/discourse/compose.ccci-health.yml` → `compose.ccci.yml`; update each recipe's
|
||||
`install_steps.sh` (the `cp` target) and `recipe_meta` `COMPOSE_FILE`
|
||||
(`compose.yml:compose.ccci-health.yml` → `compose.yml:compose.ccci.yml`). One fixed filename per
|
||||
recipe going forward.
|
||||
- [ ] **ghost `compose.ccci.yml` (start_period 900s) — KEEP, justified.** abra can't env-param
|
||||
`start_period`; the fresh-DB migration needs the larger grace or swarm kills it → deadlock.
|
||||
Confirm the header documents this; consider an upstream PR raising ghost's `start_period` (it's a
|
||||
real slow-host fragility) — but the overlay stays regardless.
|
||||
- [ ] **discourse `compose.ccci-health.yml` — KEEP, justified (both parts).** (a) `start_period 1200s`
|
||||
- [ ] **discourse `compose.ccci.yml` — KEEP, justified (both parts).** (a) `start_period 1200s`
|
||||
(same reason as ghost). (b) The `bitnami/discourse:3.3.1 → bitnamilegacy/discourse:3.3.1` re-pin
|
||||
makes the from-version (0.7.0, whose `bitnami/discourse` tag Docker Hub now 404s) **deployable so
|
||||
the upgrade-to-latest test can run** — namespace-only, identical discourse version, applied to
|
||||
|
||||
@ -834,8 +834,10 @@ Each default stands until the Adversary or reality forces a change; record the c
|
||||
cc-ci-authored compose overlay (an extra `compose.*.yml` layered via `COMPOSE_FILE`) risks **drift**
|
||||
from the recipe users actually run, so **avoid it where possible and justify each use**. In most
|
||||
cases the cleaner fix is an **upstream recipe PR** — either a genuine robustness fix, or exposing a
|
||||
knob the recipe should expose. **But a uniform, optional `compose.ccci-*.yml` overlay file per
|
||||
knob the recipe should expose. **But a single, uniform, optional `compose.ccci.yml` overlay file per
|
||||
recipe is an acceptable fallback** — especially for a value abra/compose can't take from an env var.
|
||||
(One fixed filename per recipe — `compose.ccci.yml` — holding all cc-ci-side deploy tweaks; not
|
||||
per-purpose suffixes.)
|
||||
**Known limitation (builder, 2026-05-30): abra does NOT support an env value for a healthcheck
|
||||
`start_period`.** So the ghost/discourse `start_period` bumps legitimately **need** the overlay (an
|
||||
env-var PR is not possible for that field) — these overlays **stay**, justified. When you do use an
|
||||
|
||||
Reference in New Issue
Block a user