This guide provides guidance and tips for how to effectively migrate from a third-party or homegrown feature flagging system to LaunchDarkly’s feature management platform.
There are many reasons why your organization may be ready to migrate to LaunchDarkly. Some of these include:
After you’ve decided to retire your old system, it’s time to begin planning your migration project, along with the challenges and opportunities it presents. We recommend careful planning as a preliminary step.
Successful migrations commonly take place over several incremental steps, rather than all at once. Tracking and visibility into the process helps you and your teams ensure a smooth rollout, as will having a failsafe in place if problems occur. A gradual migration also reduces opportunities for error.
To begin the process, divide your migration into three phases:
To complete this guide, you must have the following prerequisites:
This guide relies on the following concepts:
LaunchDarkly accounts can contain one or more projects. A project can contain multiple environments, and flags exist across all environments within a project. When you create a new feature flag, it is created in every environment in your LaunchDarkly project. However, flag configuration settings are specific to each environment. The changes you make in one environment do not apply to the same flag in any other environment. If you want to, you can configure the same flag in a unique way for every environment you have.
Many software projects have a test, staging, and production environment within each project. In LaunchDarkly, you can define any environment structure that suits your group’s needs. For example, your mobile team might need an android test, android prod, ios test, and ios prod environment in a “Mobile apps” project.
To learn more, read Projects and Environments.
Preparing for the migration may be the most important part of the process.
Here are the steps we recommend you take to prepare:
The organization schema you choose for your LaunchDarkly account informs the way your account members interact with the platform and how flags are managed. There are three approaches you can take to organizing your projects, and there are pros and cons to each.
Common organizational schemas options include:
If you don’t already have a naming convention or style guide in place for feature flags, take this opportunity to create one. Establishing conventions for flag names and flag keys can help identify which team owns a flag, what release it is associated with, and the purpose of a flag. These conventions can also help prevent technical debt from accumulating by making it easier to understand which flags can be archived when.
To learn more, read Flag conventions.
If you only have a handful of flags, it’s not time-consuming to find a flag in LaunchDarkly. As your number of flags grows and more teams use feature flags, this becomes harder. Tags help you organize and sort flags into groups. For example, if you have flags related to experiments you can create an ‘experiments’ tag. If you have flags for specific departments, you can create a tag with the department name. These tags can help you control which team members can read, write, or modify a flag.
Before migrating, brainstorm a list of relevant tags. You can always add more tags later. To learn more, read Tags.
In addition to your broad organizational schema, you can further organize your LaunchDarkly account members using teams. Teams allow you to set up fine-grained access rules and assign this access to specific groups of people, giving them precise control over their feature flags, experiments, and projects. While you don’t need to define your teams and their permissions before you migrate, thinking about how you might like to organize your teams can help you decide which schema makes sense for your organization.
To learn more, read Teams.
If your engineering organization contains many groups, we recommend starting with a single group or project rather than trying to migrate all groups and their projects at once. This allows you to focus your attention on helping one group at time rather than spreading it across many. Because new flags are being created all the time, it also allows you to narrow your scope when managing the multi-state period.
Begin by grouping your flags organizationally, and decide on a rough order you’d like to move groups over in. Your goal should be to cause the least disruption, try not to break code, and require groups to use both systems for as little time as possible.
When choosing a pilot group, pick one that won’t be under time pressure. Groups starting a new project or groups with a maintenance period coming up between projects are good candidates. The group should be ready to provide regular feedback on its migration process, as well as assist in creating lightweight migration tools and documentation for the rest of the organization to use in their migrations.
You can also show your teams how to self-serve to enable groups to migrate on their own.
Inform all of your engineering and other relevant teams of the plan. Provide your teams with a rough outline and a scheduled timeline.
Once you’ve completed your preparations, it’s time to start migrating your feature flags, one group at a time. Often our customers run their old and new systems in parallel for some time. Your migration can take as long as you need. If you have a feature currently in the middle of a rollout, or you’re running an experiment, leave those flags on the existing platform while you set up new flags in LaunchDarkly. It’s fine to run systems in parallel for a couple of months while things wind down in your legacy system and your teams are trained. By implementing the migration slowly, you may be able to avoid giant cut-over steps and downtime.
To begin, create an “evaluation mode” flag in LaunchDarkly. This flag tells your application which system to consult for feature flags: your legacy system, LaunchDarkly, or both. You can leverage targeting rules for granular control between your environments and applications. When this flag is ready, you can begin the migration process.
Here’s how to migrate your feature flags, group by group:
If you haven’t been regularly archiving flags in your legacy solution, you may have accumulated a lot of flag debt. You may have hundreds or thousands of flags that are no longer in use. Migrating every feature flag you’ve ever created would be an overwhelming task. Instead, consider the best way to address your flag debt, as well as how to avoid accumulating more in the future. To learn more about avoiding accumulating flag debt in LaunchDarkly, read Reducing technical debt from feature flags.
Identify all permanent flags in your legacy system used by your pilot group. Ideally, you should leave all temporary flags in the legacy system. If a group as temporary flags in use, wait until those flags are no longer needed before migrating. Moving only permanent flags greatly reduces the flags you need to handle, and helps reduce your existing technical debt. To learn more about how to classify flags, read Determine your flag’s use case.
If possible, keep your flag keys the same between the legacy system and LaunchDarkly. If you change keys between systems, it can cause problems with your wrappers. However, you may have to update keys for flags that use characters LaunchDarkly does not support. LaunchDarkly flag keys can contain only letters, numbers, periods (.), underscores (_), and dashes (-).
It may be helpful to organize your flags into a spreadsheet to help you decide which flags to migrate and which to leave in your legacy system. Here is an example:
If your legacy system only allows boolean flags, you may be able to simplify by combining multiple boolean flags into one multivariate flags.
For example, if you have three different possible background colors of red, blue, and yellow, your legacy system might have two boolean flags to determine the background color for a given context instance:
You could replace flags A and B in the legacy system with one multivariate flag in LaunchDarkly that serves either a red, blue, or yellow background depending on the flag’s targeting rules.
If you are migrating from a third-party system, you can import your flags directly into LaunchDarkly. You can import flags from Split.io or Unleash. To learn how, read Importing flags.
If you are migrating from a different system, you’ll need to recreate your flags in LaunchDarkly. Follow the flag naming convention you created during your planning phase. Ideally, you will migrate a small number of flags and it will not be burdensome to create them manually. You can use the LaunchDarkly REST API to preload all of your existing flags and targeting rules, but if you are migrating so many flags you need an automated process, consider whether you have eliminated legacy flags thoroughly enough. There may be more you can archive or delete.
Search for mismatches between flags in your legacy system and LaunchDarkly. These may be flags that exist in both systems but have different targeting rules, or flags in the legacy system that you marked for migration but haven’t been migrated yet. You can do this manually or by using an external application performance management (APM) tool like New Relic One. To learn more about available observability and APM tool integrations, read Monitoring tools.
Your legacy flag system may provide an API module. It likely contains flag evaluation functions that are called throughout the application code. Instead of changing all the application code that uses flags, change the implementation of the evaluation functions to use both the legacy system and LaunchDarkly. Internally, the new implementation evaluates flags by querying both the legacy system and LaunchDarkly and uses whichever flag it finds first. The order of querying is set by a dedicated “flag evaluation mode” flag, kept in LaunchDarkly. When the new wrapper is deployed, it should look to the legacy flag system first. After the group is comfortable with LaunchDarkly, and the most important flags have been migrated, you can switch the flag evaluation mode to query LaunchDarkly first.
To learn more, read Use cases for SDK wrappers.
Some customers use dual-writes so that any changes to feature flag states are automatically written to both LaunchDarkly and their legacy system. You can use webhooks to implement this in LaunchDarkly. You can then perform periodic comparisons of specific applications as you migrate, or of all flag data, across both systems to ensure they remain consistent over time. To learn more, read Webhooks.
Repeat the above steps for each group you are migrating to LaunchDarkly. When all of your groups have been migrated, you can retire your legacy system.
After you’ve maintained flags in both systems long enough to ensure things are working as expected, phase out your legacy system by creating all new flags in LaunchDarkly only, and ceasing to create flags in your legacy system. This is the point of no return, as now the data between your legacy system and LaunchDarkly will diverge. You may want to enforce this by turning off the ability to create new flags in the legacy system, because it’s common for engineers to default to using it out of habit.
Utilize your APM tool to identify any unexpected behavior going forward. When you’re confident your flags are performing as expected, you can decommission your legacy system.
Congratulations! You have now successfully implemented LaunchDarkly.
As your organization begins using LaunchDarkly in earnest, you can begin integrating other third-party tools and thinking about how to manage technical debt.
You likely use other third-party tools in your release process, such as applications like Slack, MS Teams, Jira, Azure DevOps, ServiceNow, Amazon Kinesis, or Azure Events Hub. You can integrate these tools, and many others, with LaunchDarkly. For a full list of LaunchDarkly integrations and instructions on how to add them to your LaunchDarkly account, read Integrations.
Accumulating technical debt with feature flags is unavoidable, but there are steps you can take to minimize it.
First, define what done means when it comes to a feature. When you create a flag, what processes do you have in place for ensuring the flag is removed? Is a feature done when it rolls out to 100% of your customer base, or is it done when the flag is removed from the code? Coding a flag is a two-part process: creating a flag and removing a flag. You shouldn’t consider these two separate processes. If you’re using Git to manage your work, we recommend submitting a pull request (PR) to remove the flag at the same time you submit the PR to add it.
To learn more about managing technical debt in LaunchDarkly, read Reducing technical debt from feature flags.
LaunchDarkly also provides code references to help you identify where in the codebase the feature flag is referenced for easier removal. To learn more, read Code references.
Here are some additional articles and talks about migrating to LaunchDarkly:
If you have more questions or need further assistance, start a Support ticket.