From 7bfd6997ece0652815dbf93dfbe3ceb211fec153 Mon Sep 17 00:00:00 2001 From: rcourtman Date: Tue, 21 Oct 2025 10:48:35 +0000 Subject: [PATCH] docs: remove outdated installer v2 rollout planning doc The v2 installer rollout is complete - dist/install-docker-agent.sh now contains the bundled v2 installer with embedded library modules. This planning document served its purpose and is no longer relevant. --- docs/installer-v2-rollout.md | 142 ----------------------------------- 1 file changed, 142 deletions(-) delete mode 100644 docs/installer-v2-rollout.md diff --git a/docs/installer-v2-rollout.md b/docs/installer-v2-rollout.md deleted file mode 100644 index 5dce3cd..0000000 --- a/docs/installer-v2-rollout.md +++ /dev/null @@ -1,142 +0,0 @@ -# Installer v2 Rollout Plan - -## 1. Overview - -The Docker agent installer (`install-docker-agent.sh`) has been refactored into a -modular, testable v2. Key improvements include: - -- Shared library usage (`scripts/lib/*.sh`) for logging, HTTP, and systemd - helpers, reducing duplication and easing maintenance. -- Support for `--dry-run`, enabling administrators to preview actions safely. -- Bundled single-file distribution generated by `scripts/bundle.sh` for curl - based installs, while keeping modular sources in the repository. -- New smoke and integration tests to catch regressions. - -Benefits: - -- **Users:** Clearer logging, dry-run validation, safer rollbacks, and improved - error handling. -- **Developers:** Consistent helper functions, faster iteration on fixes, and - reusable testing infrastructure. - -## 2. Rollout Strategy - -### Phase 1: Alpha Testing (Internal) -- Enable v2 via feature flag for internal environments only. -- Exercise on development clusters, CI agents, and dogfood installations. -- Validate dry-run, full install, multi-target, and uninstall scenarios. -- Duration: ~1 week. - -### Phase 2: Beta Testing (Early Adopters) -- Announce availability in release notes and internal channels. -- Provide explicit opt-in instructions (`PULSE_INSTALLER_V2=1`). -- Monitor install success metrics, support channels, and gather structured - feedback from operators. -- Duration: ~2 weeks. - -### Phase 3: General Availability -- Flip feature flag default to v2 while retaining v1 as fallback for one full - release cycle. -- Publish deprecation notice for the legacy installer. -- After the grace period, remove v1 from distribution. -- Duration: 1 release cadence (approx. 4–6 weeks). - -## 3. Feature Flag Mechanism - -Users can select installer versions via environment variable: - -```bash -# Enable v2 (early adopter) -export PULSE_INSTALLER_V2=1 -curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- ... - -# Force legacy v1 -export PULSE_INSTALLER_V2=0 -curl -fsSL https://download.pulse.example/install-docker-agent.sh | bash -s -- ... - -# Server-side pseudo-code -if [[ "${PULSE_INSTALLER_V2:-0}" == "1" ]]; then - serve dist/install-docker-agent.sh -else - serve scripts/install-docker-agent-legacy.sh -fi -``` - -The download endpoint should inspect the flag (query parameter, header, or -environment variable) and serve the appropriate script. - -## 4. Testing Checklist - -### Before Rollout -- [ ] Smoke tests (`scripts/tests/run.sh`) passing -- [ ] Integration tests (`scripts/tests/integration/...`) passing -- [ ] Ubuntu 20.04 & 22.04 validated -- [ ] Debian 11 & 12 validated -- [ ] With and without Docker binary -- [ ] Multi-target configuration verified -- [ ] Uninstall path verified -- [ ] Documentation updated (INSTALL, FAQ, etc.) -- [ ] Release notes drafted - -### During Rollout -- [ ] Monitor error rates (CI dashboards, telemetry) -- [ ] Watch support channels/tickets for installer issues -- [ ] Sample successful installations daily -- [ ] Collect structured feedback from early adopters - -## 5. Success Metrics - -- Installation success rate ≥ 99% -- Median installation duration (baseline ±10%) -- Top error categories and frequency trending downward -- Positive/neutral user feedback (no significant negative trend) -- Rollback requests < 1% - -## 6. Rollback Plan - -If blocking issues surface: - -### Quick Rollback (< 5 minutes) -1. Replace served script with v1 variant: - ```bash - cp scripts/install-docker-agent-legacy.sh /var/www/html/install-docker-agent.sh - # or update symlink pointing to dist/install-docker-agent.sh - ``` -2. Update documentation to reflect temporary rollback. -3. Broadcast notice in release channels/support chat. - -**File references** -- Legacy: `scripts/install-docker-agent-legacy.sh` -- Bundled v2: `dist/install-docker-agent.sh` -- Served location: `/download/install-docker-agent.sh` (symlink/HTTP root) - -## 7. Communication Plan - -**Announcements** -- Release notes covering v2 highlights and rollout phases. -- Update product docs (`INSTALL.md`, quick reference). -- Post in GitHub Discussions / community forums. -- Optional blog post for broader awareness. - -**User Guidance** -- Explain how to opt-in/out using `PULSE_INSTALLER_V2`. -- Highlight new capabilities (`--dry-run`, improved messaging). -- Provide support contact and bug-reporting instructions. -- Link to troubleshooting resources. - -## 8. Known Limitations - -- Limited testing on non-`systemd` init systems (manual startup handled but not - optimized). -- ARM architectures covered via dry-run and download stubs; on-device testing - pending. -- Requires Bash 4.0+ (same as v1) — document for older environments. - -## 9. Post-Rollout Tasks - -- [ ] Remove feature flag after one successful release cycle. -- [ ] Retire legacy installer artifacts and adjust CI pipelines. -- [ ] Update all docs to reference v2 only. -- [ ] Apply modular pattern to remaining installers (install.sh, - install-sensor-proxy.sh, pulse-auto-update.sh). -- [ ] Expand integration tests to cover additional distributions and scenarios.