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.
This commit is contained in:
rcourtman
parent
10d52244f8
commit
7bfd6997ec
1 changed files with 0 additions and 142 deletions
|
|
@ -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.
|
||||
Loading…
Reference in a new issue