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