feat(cassandra): install arbitrary versions/branches onto a live cluster without an AMI rebuild

.github/workflows/packer-lint.yml

@@ -13,6 +13,9 @@ on:
       - ".github/workflows/packer-lint.yml"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   validate-packer:
     name: Validate Packer HCL Files
@@ -22,7 +25,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Setup Packer
-        uses: hashicorp/setup-packer@main
+        uses: hashicorp/setup-packer@v3.1.0
         with:
           version: "latest"
 
@@ -51,7 +54,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Run ShellCheck
-        uses: ludeeus/action-shellcheck@master
+        uses: ludeeus/action-shellcheck@v2.0.0
         with:
           scandir: "./packer"
           severity: error

.github/workflows/packer-test.yml

@@ -29,6 +29,25 @@ jobs:
       - name: Run ref-resolution unit tests
         run: bash .github/cassandra-image/resolve-ref.test.sh
 
+  test-cassandra-install-scripts:
+    name: Test Cassandra install/use script logic
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Install yq
+        run: sudo snap install yq
+
+      - name: Test install-cassandra-version
+        run: bash packer/cassandra/bin/install-cassandra-version.test.sh
+
+      - name: Test the bake-time install loop
+        run: bash packer/cassandra/install/install_cassandra.test.sh
+
+      - name: Test use-cassandra
+        run: bash packer/cassandra/bin/use-cassandra.test.sh
+
   test-individual-scripts:
     name: Test Individual Scripts
     runs-on: ubuntu-latest

build.gradle.kts

@@ -379,6 +379,38 @@ tasks.register<Exec>("testCassandraResolveRef") {
     commandLine = listOf("bash", ".github/cassandra-image/resolve-ref.test.sh")
 }
 
+// Unit-test install-cassandra-version's decisions (argument handling, already-installed no-op,
+// source-build guards, JDK selection). sudo/curl/git/dpkg are stubbed; no Docker, no network.
+tasks.register<Exec>("testCassandraInstallScript") {
+    group = "Verification"
+    description = "Unit-test the install-cassandra-version script"
+    workingDir = file(".")
+    commandLine = listOf("bash", "packer/cassandra/bin/install-cassandra-version.test.sh")
+}
+
+// Unit-test the bake-time loop's version resolution (yq-driven flags, lazy skip). Sources
+// install_cassandra.sh without INSTALL_CASSANDRA, so none of its effects run.
+tasks.register<Exec>("testCassandraInstallLoop") {
+    group = "Verification"
+    description = "Unit-test the bake-time Cassandra version install loop"
+    workingDir = file(".")
+    commandLine = listOf("bash", "packer/cassandra/install/install_cassandra.test.sh")
+}
+
+// Unit-test use-cassandra's guard against selecting a version the node never installed.
+tasks.register<Exec>("testCassandraUseScript") {
+    group = "Verification"
+    description = "Unit-test the use-cassandra script"
+    workingDir = file(".")
+    commandLine = listOf("bash", "packer/cassandra/bin/use-cassandra.test.sh")
+}
+
+tasks.register("testCassandraScripts") {
+    group = "Verification"
+    description = "Run all Cassandra shell script unit tests"
+    dependsOn("testCassandraInstallScript", "testCassandraInstallLoop", "testCassandraUseScript")
+}
+
 tasks.register<Exec>("testPackerScript") {
     group = "Verification"
     description = "Test a specific packer script (use -Pscript=path/to/script.sh)"

docs/development/building-cassandra-refs.md

@@ -111,8 +111,16 @@ Pin the release's tarball URL in `packer/cassandra/cassandra_versions.yaml`:
   python: "3.11.9"
 ```
 
-`install_cassandra.sh` downloads the URL and expects it to unpack into a single
-top-level `*cassandra*` directory, which the `ant artifacts` tarball satisfies.
+`install-cassandra-version` downloads the URL and expects it to unpack into a
+single top-level `*cassandra*` directory, which the `ant artifacts` tarball
+satisfies. The same script runs at AMI bake time and at runtime, so you can skip
+the rebuild entirely and install the tarball onto a running cluster:
+
+```bash
+easy-db-lab cassandra install my-branch \
+  --url https://github.com/<owner>/<repo>/releases/download/.../apache-cassandra-<version>-<short-sha>-bin.tar.gz \
+  --java 17
+```
 
 ## Image assembly
 

docs/reference/commands.md

@@ -198,6 +198,33 @@ easy-db-lab cassandra use <version> [options]
 
 Versions: 3.0, 3.11, 4.0, 4.1, 5.0, 5.0-HEAD, 6.0-HEAD, trunk
 
+Fails if the version is not installed on a targeted node — install it first with
+`cassandra install`.
+
+### cassandra install
+
+Install an additional Cassandra version onto a running cluster, without rebuilding the AMI.
+
+```bash
+easy-db-lab cassandra install <version> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--url` | Tarball URL (`.tar.gz`) or git repository URL (with `--branch`) | from the declared entry |
+| `--branch` | Git branch to clone and build, requires `--url` | from the declared entry |
+| `--java`, `-j` | Java version to build and run this version with | from the declared entry |
+| `--python` | Python version cqlsh runs under | `3.11.9` |
+| `--ant-flags` | Extra flags passed to ant when building from a branch | from the declared entry |
+| `--hosts` | Filter to specific hosts | all Cassandra nodes |
+
+Each option falls back to the version's `cassandra_versions.yaml` entry when not supplied, so a
+declared version needs no options at all. Installing a version that is already installed on a node
+is a no-op, and a failure on any node exits non-zero with the reason reported against that node.
+
+See [Configuring Cassandra](../user-guide/installing-cassandra.md#custom-builds) for the full
+workflow.
+
 ### cassandra write-config
 
 Generate a new configuration patch file.
@@ -295,6 +322,9 @@ easy-db-lab cassandra list
 
 **Aliases:** `ls`
 
+Versions installed on the node are listed first. A version declared with `lazy: true` that is not
+installed on that node is listed too, marked `(declared, not installed)`.
+
 ---
 
 ## Cassandra Stress Commands

docs/user-guide/installing-cassandra.md

@@ -182,8 +182,59 @@ Configuration is located at `/etc/cassandra-sidecar/cassandra-sidecar.yaml` on e
 ## Custom Builds
 
 To run a custom Cassandra build (your own fork, a feature branch, or a prebuilt
-tarball), add a version entry and rebuild the AMI. easy-db-lab bakes every listed
-version into the image — there is no separate build-from-path command.
+tarball), you can either install it onto a cluster that is already running, or
+bake it into the AMI so every future cluster has it.
+
+### Install onto a running cluster
+
+```bash
+easy-db-lab cassandra install <version>
+easy-db-lab cassandra use <version>
+```
+
+This downloads (or clones and builds) the version on every Cassandra node and
+records it in each node's version list, so `cassandra use` works afterward. It
+never rebuilds the AMI, so nothing is preserved across a `down`/`up` cycle —
+install it again on the new cluster.
+
+Where the install parameters come from:
+
+- **A declared entry** (the default): whatever you declared in your profile's
+  extras directory, described below. Nothing else to pass.
+- **CLI options**, for a genuinely one-off test with no file to edit:
+
+  ```bash
+  easy-db-lab cassandra install my-build \
+    --url https://example.com/apache-cassandra-my-build-bin.tar.gz \
+    --java 11
+  ```
+
+  Or from a branch, built with ant on each node:
+
+  ```bash
+  easy-db-lab cassandra install my-build \
+    --url https://github.com/myuser/cassandra.git \
+    --branch my-feature-branch \
+    --java 11 \
+    --ant-flags "-Duse.jdk11=true"
+  ```
+
+  An option you pass overrides the declared entry's value for that field;
+  anything you leave out falls back to the declared entry. `--python` defaults
+  to `3.11.9`.
+
+Useful details:
+
+- `--hosts db0,db1` installs on a subset of nodes only.
+- Installing a version a node already has is a no-op.
+- If a node fails, the command exits non-zero and names the node and the reason;
+  nodes that succeeded keep their install.
+- A branch build runs a full `ant` build on every targeted node, which is
+  CPU-heavy and takes several minutes. It is safe while Cassandra is running —
+  the install only writes to `/usr/local/cassandra/<version>` — but it is not
+  free. Tarball installs are much cheaper.
+
+### Bake into the AMI
 
 You don't edit the repository's `cassandra_versions.yaml`. Instead, drop one or
 more YAML files into your profile's extras directory:
@@ -234,6 +285,25 @@ easy-db-lab build-cassandra
 easy-db-lab cassandra use my-build
 ```
 
+### Declaring a version without baking it
+
+Add `lazy: true` to an entry to declare a version without spending AMI build
+time on it:
+
+```yaml
+- version: "my-build"
+  java: "11"
+  python: "3.11.9"
+  url: "https://github.com/myuser/cassandra.git"
+  branch: "my-feature-branch"
+  lazy: true
+```
+
+The AMI build skips the download/clone/build for that entry, but the entry
+still ships in the image. `easy-db-lab cassandra list` shows it as
+`(declared, not installed)`, and `easy-db-lab cassandra install my-build`
+installs it on a running cluster without you re-specifying any of its fields.
+
 ## Next Steps
 
 - [Tutorial](tutorial.md) - Complete walkthrough

openspec/changes/issue-876/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-14