Skip to content

Add versioned blue-green Tentacle install + upgrade

Placeholder ppxd requested to merge feat/tentacle-versioned-blue-green into main

Summary

Builds on the versioned-layout foundation (#402) to make Tentacle upgrades failure-isolated: an upgrade never touches the directory of the version that is running, so any failure — download, verify, stage, activate, restart, health check, or even a failed rollback — leaves the previous version byte-for-byte intact and instantly restorable.

  • Install (install-tentacle.{sh,ps1}): fresh tarball/zip installs lay down a versioned layout — binary in versions/<v>, selected by a stable current pointer (symlink on Linux, junction on Windows) — and register the service against the pointer. Best-effort: if the extracted binary can't report its version, both scripts fall back to the prior flat extraction, so an install that used to succeed never starts failing. apt/yum latest installs stay flat.
  • Upgrade (upgrade-{linux,windows}-tentacle.*): when a versioned install is detected, extract the new version into versions/<target> and atomically repoint current (Linux mv -T rename; Windows non-recursive junction replace); roll back by repointing current back to the previous version dir.

Strictly non-breaking

The entire blue-green path is gated on the versioned layout (current symlink/junction). Flat installs — every existing agent, plus apt/yum installs — keep today's install + apt/yum/tarball + .bak/.failed swap/restore byte-for-byte. Nothing creates a versioned layout for an existing agent, so existing fleets are unaffected until they are freshly reinstalled.

Test plan

  • Unit / drift (runnable everywhere): TentacleLayout contract (19); layout-aware ResolveServiceExecution (7); install-script drift detector ties versions/current literals to the C# constants + pins the atomic-swap mechanics + the flat fallback (5); Linux upgrade blue-green assertions + bash -n on the rendered script with real method snippets (UpgradeLinuxTentacleScriptTests, 71); Windows upgrade blue-green assertions + flat-path-unchanged guard (WindowsTentacleUpgradeStrategyTests). All 690 upgrade unit tests pass.
  • Linux install E2E migrated to assert the versioned layout (versions/<v> + current symlink + reachable through the pointer); incidental checks use the stable squid-tentacle entry point (resolves in both layouts).
  • Non-breaking verified by stashing for the foundation change; flat paths covered byte-for-byte by the existing green suites.
  • Remaining before merge (see notes): a real versioned-upgrade E2E per OS (happy + health-fail→rollback, asserting the previous version dir is byte-unchanged); Windows needs a version-reporting test shim to exercise the versioned path (today's fake-binary install E2E hits the flat fallback).

Notes

  • flat→versioned migration is intentionally deferred — it modifies a running service's registration and is the riskiest sub-step. It is not required for correctness: existing flat agents keep their (working) flat upgrades; only fresh installs are versioned. Migration can land as a separate, guarded change.
  • Squashed history: foundation (#402) + versioned install scripts + Linux install E2E migration + Linux upgrade + Windows upgrade.

Merge request reports