Self-hosted Feature Flags Migration Playbook: Cut Switching Cost and Vendor Lock-in
Migrating from a SaaS feature flag platform to a self-hosted solution is a controlled, low-risk operation when done with a parallel-run approach. The switching cost is typically 2–4 weeks of engineering time and a short period of dual-write overhead — spread over the existing SaaS contract end date to eliminate sunk cost waste.
TL;DR
- ▸Migration risk is low when you run the old and new systems in parallel with dual-write before cutting over any flag evaluation traffic.
- ▸Initial setup + flag import: 1–2 days. SDK replacement in services: 1–3 days (batch). Parallel validation period: 1–2 weeks. Total: 2–4 weeks end-to-end.
- ▸Plan the cutover before your next SaaS renewal to avoid a wasted renewal cycle. Cancellation windows are often 30–60 days before renewal.
- ▸SDK lock-in is eliminated by adopting OpenFeature — FeatBit ships an OpenFeature provider, so you swap the provider without touching application code. Remaining lock-in surface: flag naming conventions and targeting rule semantics, both low-risk.
Migration Strategy Overview
The safest migration approach is a 4-phase parallel run strategy. No phase requires a “big bang” cutover. Each phase is independently reversible.
Deploy FeatBit alongside existing SaaS. Mirror all flag configurations. No production traffic moved yet.
Flag changes are written to both systems. SDK evaluation still on SaaS. Catch data drift early.
Route a shadow percentage of SDK evaluations to FeatBit. Compare results, log discrepancies.
Switch SDK evaluation traffic to FeatBit. Keep SaaS on standby for 1 week. Cancel at next renewal.
Phase 1: Parallel Run Setup
Provision infra for PostgreSQL plus FeatBit's self-host services in the staging environment. Use Docker Compose for initial evaluation, then migrate to production-grade IaC before cutover.
Export flag definitions from SaaS (most platforms offer JSON/YAML export). Import into FeatBit via API or UI. Map environments 1:1. Flag keys should match exactly to reduce SDK search-and-replace scope.
Validate that percentage rollouts, user attribute targeting, and segment definitions are faithfully reproduced. Create a test matrix of representative users and verify evaluation results match between systems.
Set up alerting for FeatBit API health before it handles any production traffic. This is also a good time to validate your ops runbook (restart procedure, backup schedule).
Phase 2: Dual-write Period
During dual-write, every flag change made by a developer or CI/CD pipeline is written to both systems via a thin middleware layer or a manual workflow. The goal is to catch data drift — cases where the systems diverge — before any SDK traffic is routed to FeatBit.
// When saving a flag change: await legacySaasClient.updateFlag(flagKey, config); await featbitClient.updateFlag(flagKey, config); // Log any divergence in flag state reconciliation: const saasFlags = await legacySaasClient.listFlags(); const featbitFlags = await featbitClient.listFlags(); const drift = detectDrift(saasFlags, featbitFlags); if (drift.length > 0) alertOncall(drift);
Run dual-write for at least 1 week and through at least one scheduled flag change cycle (e.g., a sprint deployment). Any discrepancies surfaced here are informational — you are not yet routing production evaluation traffic to FeatBit.
Phase 3: Validation & Shadow Reads
Before cutting over, validate that FeatBit evaluates flags identically to the SaaS platform for your actual user base. Route a shadow percentage (~5–10%) of SDK evaluation calls to FeatBit while still serving production responses from SaaS.
Phase 4: Cutover & Rollback
The cutover involves routing all SDK evaluation traffic to FeatBit. This is done by updating SDK configuration to point to your FeatBit instance endpoint. Rollback is equally fast: revert the endpoint configuration.
- ✓Update SDK endpoint in all services (config change, no code change)
- ✓Redeploy services in blue/green order
- ✓Monitor flag evaluation latency for 30 min
- ✓Verify audit log write rate matches expected
- ✓Announce migration complete to engineering team
- !P1 incident within 4h of cutover
- !Flag evaluation error rate > 0.1%
- !Evaluation latency p99 > 200ms
- !Data drift reappears after parallel run
- !On-call engineer judgment call
Keep the SaaS subscription active for at least 1 week post-cutover as a rollback safety net. Then initiate cancellation. Most SaaS platforms require 30–60 day cancellation notice before the next billing date.
Vendor Lock-in Risk Assessment
| Lock-in vector | Risk level | Mitigation |
|---|---|---|
| Proprietary SDK method names | None (w/ OpenFeature) | Use the OpenFeature standard — FeatBit ships an OpenFeature provider; swap providers without changing application code |
| Flag key naming conventions | Low | FeatBit flag keys are arbitrary strings; import preserves existing key names |
| Targeting rule semantics | Medium | Validate rule parity during parallel run; most semantics are standard |
| Webhook / integration ecosystem | Low–Medium | FeatBit exposes webhooks; most third-party integrations are re-configurable |
| SaaS-specific analytics / insights | Low | FeatBit emits flag events; ingest into existing observability stack |
FAQ
What is the total engineering time required for migration?
For a 50-engineer organization with 50–200 active flags: estimate 2–4 engineer-weeks total across the 4 phases. Most of this is parallel validation time, not active development time. Active coding is concentrated in Phase 1 (setup + import) and Phase 3 (shadow comparison tooling).
Can we migrate without interrupting existing feature flag usage?
Yes. The parallel-run approach means no production flag evaluation is ever in an undefined state. Your engineers continue using the SaaS product normally during Phases 1–2. Only in Phase 3 do you start routing any production traffic to FeatBit.
What if our SaaS platform does not support flag export?
Most platforms expose a flag definition API even if there is no built-in export UI. Use the API to dump flag configurations programmatically. If the platform does not expose flag data via API, that is itself a significant vendor lock-in risk to document for stakeholders.