|
| 1 | +#!/usr/bin/env bash |
| 2 | +# Generic Antithesis launcher shared by every scenario. |
| 3 | +# |
| 4 | +# ./launch.sh <scenario> [extra snouty flags] |
| 5 | +# |
| 6 | +# <scenario> names a directory under `test/antithesis/scenarios/` holding a |
| 7 | +# docker-compose.yaml and a launch.env. launch.env supplies the per-scenario |
| 8 | +# bits; everything else -- image tagging, property-history key, the fault profile |
| 9 | +# shape, build-before-submit -- is common and lives here so every shot is |
| 10 | +# identical and comparable and no fault flag is ever fumbled or forgotten. Change |
| 11 | +# a shot's faults by editing launch.env's node list, not by passing one-off flags. |
| 12 | +# |
| 13 | +# launch.env, sourced from the scenario directory, sets: |
| 14 | +# SCENARIO_TEST_NAME test name reported to Antithesis |
| 15 | +# SCENARIO_DESCRIPTION human description; the git commit is appended |
| 16 | +# SCENARIO_FAULT_NODES space-separated SUT container names to node-fault; |
| 17 | +# empty means no node termination/hang/throttle at all |
| 18 | +# SCENARIO_WEBHOOK optional; tenant webhook, default persistent_storage |
| 19 | +# |
| 20 | +# Required environment, read by snouty: |
| 21 | +# ANTITHESIS_TENANT tenant name |
| 22 | +# ANTITHESIS_API_KEY api key, or ANTITHESIS_USERNAME + ANTITHESIS_PASSWORD |
| 23 | +# ANTITHESIS_REPOSITORY registry to push the built config + service images to |
| 24 | +# |
| 25 | +# Optional overrides win over launch.env / defaults: |
| 26 | +# DURATION=<minutes> default 30 |
| 27 | +# TEST_NAME=<name> default SCENARIO_TEST_NAME |
| 28 | +# DESCRIPTION=<text> default SCENARIO_DESCRIPTION; commit is appended |
| 29 | +# FAULT_NODES=<names> default SCENARIO_FAULT_NODES |
| 30 | +# WEBHOOK=<name> default SCENARIO_WEBHOOK or persistent_storage |
| 31 | +# SOURCE=<identifier> property-history key; default is the git branch |
| 32 | +# DRY_RUN=1 print the exact command and exit without submitting |
| 33 | +set -euo pipefail |
| 34 | + |
| 35 | +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" |
| 36 | +ANTITHESIS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" |
| 37 | +REPO_ROOT="$(cd "$ANTITHESIS_DIR/../.." && pwd)" |
| 38 | + |
| 39 | +SCENARIO="${1:?usage: launch.sh <scenario> [extra snouty flags]}" |
| 40 | +shift |
| 41 | +SCENARIO_DIR="$ANTITHESIS_DIR/scenarios/$SCENARIO" |
| 42 | +[ -d "$SCENARIO_DIR" ] || { echo "error: no scenario directory $SCENARIO_DIR" >&2; exit 1; } |
| 43 | +[ -f "$SCENARIO_DIR/docker-compose.yaml" ] || { echo "error: $SCENARIO_DIR/docker-compose.yaml not found" >&2; exit 1; } |
| 44 | +[ -f "$SCENARIO_DIR/launch.env" ] || { echo "error: $SCENARIO_DIR/launch.env not found" >&2; exit 1; } |
| 45 | + |
| 46 | +# Per-scenario settings. Declared here so a missing one is caught, not silently empty. |
| 47 | +SCENARIO_TEST_NAME="" |
| 48 | +SCENARIO_DESCRIPTION="" |
| 49 | +SCENARIO_FAULT_NODES="" |
| 50 | +SCENARIO_WEBHOOK="" |
| 51 | +# shellcheck source=/dev/null |
| 52 | +. "$SCENARIO_DIR/launch.env" |
| 53 | + |
| 54 | +# Immutable per-build revision: the short commit, marked -dirty when the working |
| 55 | +# tree has uncommitted changes so the tag never claims to be a clean commit it is |
| 56 | +# not. Images are tagged by this, never :latest, so a shot can never reuse a stale |
| 57 | +# mutable tag and every pushed image traces back to the source it was built from. |
| 58 | +GIT_SHA="$(git -C "$REPO_ROOT" rev-parse --short HEAD 2>/dev/null || echo unknown)" |
| 59 | +if [[ -n "$(git -C "$REPO_ROOT" status --porcelain 2>/dev/null)" ]]; then |
| 60 | + GIT_SHA="${GIT_SHA}-dirty" |
| 61 | +fi |
| 62 | +export ANTITHESIS_IMAGE_TAG="$GIT_SHA" |
| 63 | + |
| 64 | +WEBHOOK="${WEBHOOK:-${SCENARIO_WEBHOOK:-persistent_storage}}" |
| 65 | +DURATION="${DURATION:-30}" |
| 66 | +TEST_NAME="${TEST_NAME:-${SCENARIO_TEST_NAME:?launch.env must set SCENARIO_TEST_NAME}}" |
| 67 | +DESCRIPTION="${DESCRIPTION:-$SCENARIO_DESCRIPTION} (commit ${GIT_SHA})" |
| 68 | +# May be empty: an empty node list means no node faults for this scenario. |
| 69 | +FAULT_NODES="${FAULT_NODES-$SCENARIO_FAULT_NODES}" |
| 70 | + |
| 71 | +# Property-history key. Passing --source makes the run tracked, not ephemeral, |
| 72 | +# so findings are produced and each property's history is grouped by this key. |
| 73 | +# Default to the branch so history follows the branch; without it snouty runs |
| 74 | +# ephemeral and no findings are available to triage. |
| 75 | +SOURCE="${SOURCE:-$(git -C "$REPO_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)}" |
| 76 | + |
| 77 | +# Pinned fault profile, submitted to the persistent_storage endpoint. cpu_mod and |
| 78 | +# clock_jitter are global and symmetric, so every scenario gets them; clock_jitter |
| 79 | +# is what exercises the AWS-LC CPU-jitter entropy path. Network faults stay on |
| 80 | +# everywhere and heal before judging. |
| 81 | +# |
| 82 | +# Node termination, hang, and throttle apply only to the containers in FAULT_NODES, |
| 83 | +# so a scenario gets none by leaving it empty. The differential A/B does: node |
| 84 | +# termination, hang, or throttle on one SUT but not the other -- or on both at |
| 85 | +# different times -- drops data unevenly and manufactures a divergence that is a |
| 86 | +# fault artifact, not an ADP defect. All three are unfair for the same reason, so |
| 87 | +# all three are gated together on FAULT_NODES. |
| 88 | +FAULTS=( |
| 89 | + --param custom.cpu_mod=true |
| 90 | + --param custom.clock_jitter=true |
| 91 | +) |
| 92 | +if [[ -n "$FAULT_NODES" ]]; then |
| 93 | + FAULTS+=( |
| 94 | + --param custom.include_for_node_termination="$FAULT_NODES" |
| 95 | + --param custom.include_for_node_hang="$FAULT_NODES" |
| 96 | + --param custom.include_for_node_throttle="$FAULT_NODES" |
| 97 | + ) |
| 98 | +fi |
| 99 | + |
| 100 | +for v in ANTITHESIS_TENANT ANTITHESIS_REPOSITORY; do |
| 101 | + if [[ -z "${!v:-}" ]]; then |
| 102 | + echo "error: $v is not set (required to build and submit the run)" >&2 |
| 103 | + exit 1 |
| 104 | + fi |
| 105 | +done |
| 106 | + |
| 107 | +# Build via the Makefile's per-scenario target so the recipe -- converged base |
| 108 | +# image then scenario compose build -- lives in one place. snouty reuses a |
| 109 | +# matching tag instead of rebuilding, so without this a shot can ship stale code. |
| 110 | +# Layer caching keeps it near-instant when nothing changed. |
| 111 | +case "$SCENARIO" in |
| 112 | + general) build=(make -C "$REPO_ROOT" antithesis-build) ;; |
| 113 | + differential) build=(make -C "$REPO_ROOT" antithesis-build-differential) ;; |
| 114 | + *) echo "error: no antithesis-build make target for scenario $SCENARIO" >&2; exit 1 ;; |
| 115 | +esac |
| 116 | + |
| 117 | +# Launch from a rendered copy so the image tag is concrete. snouty ships the compose |
| 118 | +# uninterpolated, so an `${ANTITHESIS_IMAGE_TAG:-latest}` tag reaches the platform as |
| 119 | +# the never-pushed `:latest`; `docker compose config` bakes in the tag snouty pushed. |
| 120 | +LAUNCH_DIR="$SCENARIO_DIR/.launch" |
| 121 | +render=(docker compose -f "$SCENARIO_DIR/docker-compose.yaml" config) |
| 122 | + |
| 123 | +cmd=(snouty launch |
| 124 | + --webhook "$WEBHOOK" |
| 125 | + --config "$LAUNCH_DIR" |
| 126 | + --test-name "$TEST_NAME" |
| 127 | + --description "$DESCRIPTION" |
| 128 | + --source "$SOURCE" |
| 129 | + --duration "$DURATION" |
| 130 | + "${FAULTS[@]}" |
| 131 | + "$@") |
| 132 | + |
| 133 | +printf 'build:'; printf ' %q' "${build[@]}"; printf '\n' |
| 134 | +printf 'render:'; printf ' %q' "${render[@]}"; printf ' > %q\n' "$LAUNCH_DIR/docker-compose.yaml" |
| 135 | +printf 'launch:'; printf ' %q' "${cmd[@]}"; printf '\n' |
| 136 | +if [[ "${DRY_RUN:-0}" == "1" ]]; then |
| 137 | + echo "(dry run; not building or submitting)" |
| 138 | + exit 0 |
| 139 | +fi |
| 140 | +"${build[@]}" |
| 141 | +mkdir -p "$LAUNCH_DIR" |
| 142 | +"${render[@]}" >"$LAUNCH_DIR/docker-compose.yaml" |
| 143 | +exec "${cmd[@]}" |
0 commit comments