Move configuration between servers
Copy an organization's projects, flags and segments to another server, or keep a backup, by exporting one file and importing it after a check.
- Time
- About 12 min
- Who can do it
- Admins (config.export to export, config.import to import)
- Where
- Settings, Export and import
- You finish with
- The same configuration on a second server, or a backup file
What and why#
Export and import move an organization's configuration as one JSON file. Use it to seed a new server from staging, to take a backup before a risky change, or to move to a different deployment. Importing always checks the whole file first and shows you what would change before anything is written.
Configuration, not state#
The file holds the things you would otherwise build by hand: projects, environments, segments, flags with every environment's configuration, and custom roles. It leaves out everything that belongs to a running system: people and their roles, API keys, flag history, audit entries, metrics, code references, releases and alert rules.
Safe by design#
The import is a dry run until you apply it, it is all or nothing, and it never deletes. A second import of the same file reports nothing to change, so you can run it repeatedly.
Before you start#
- You need the
config.exportpermission on the source andconfig.importon the target. Administrators have both. The Settings panel shows only the half you hold. - Know what travels. The file holds projects, environments, segments, flags with every environment's configuration, and custom roles.
- Know what does not. People and their roles, API keys, flag history, audit entries, metrics, code references, releases and alert rules stay behind, so create keys on the target yourself.
- On the target, the projects you import into must not be archived, and the environments the flags use must exist there or be in the file.
Walk through it#
Export from the source
Open Settings, find Export and import and press Export. You get a JSON file named
flagswift-config-YYYY-MM-DD.jsonwith everything in the organization. The export is recorded in the audit log asconfig.exported. The file is marked as formatflagswift.config, version 1.The Export and import panel on a signed-in Admin's Settings page. Each half shows only if you hold that permission. You should see. Your browser downloads the file. It opens as readable JSON withprojects,environments,segments,flagsandroleslists.Choose the file on the target
On the target server open the same panel and press Choose file. The file is checked straight away and nothing is written. The panel lists, for each of projects, environments, segments, flags and roles, how many would be new, updated or unchanged, plus any problems in red and warnings in grey.
Pick how to treat what already exists
When something already exists Choice API mode Description Keep what is here skip (default) Only adds what is missing. Existing projects, segments, flags and roles are left exactly as they are. Replace with the file overwrite Updates existing projects, segments, flags and roles to match the file. A flag's type cannot change. Things the file does not mention are left alone. The dry-run report after choosing a file. Apply import stays off while there are problems in red or nothing to change. Changing the choice re-checks the file, so the counts always match what Apply will do.
Apply it
When the report shows the changes you expect and no problems, press Apply import and confirm Apply this import?. The button stays off while the file has problems or there is nothing to change. The import is recorded once in the audit log as
config.importedwith the counts.You should see. A Configuration imported message appears. Choosing the same file again reports nothing to change.
Do it with the API
Send the same body with "dryRun": false to apply. The export file is not wrapped in the usual envelope: it is the document itself. A file with problems is still a 200 with errors and nothing changed. See Export and import.
# The Dashboard API acts as a signed-in person: POST /api/auth/login first (keep the cookie).
# 1. Export (config.export). "projects" is optional and narrows it to those project keys.
curl -s -b jar.txt -o flagswift-config.json \
"https://flags.example.com/api/config/export?projects=web,api"
# 2. Dry run on the target (config.import). dryRun defaults to true.
jq -n --slurpfile doc flagswift-config.json \
'{document: $doc[0], mode: "skip", dryRun: true}' |
curl -s -b jar-target.txt -X POST https://target.example.com/api/config/import \
-H "Content-Type: application/json" --data @-{
"status": "success",
"message": "Checked. Nothing was changed.",
"data": {
"applied": false,
"dryRun": true,
"mode": "skip",
"summary": {
"projects": { "create": 1, "update": 0, "skip": 0 },
"environments": { "create": 0, "update": 0, "skip": 3 },
"segments": { "create": 2, "update": 0, "skip": 0 },
"flags": { "create": 14, "update": 0, "skip": 0 },
"roles": { "create": 0, "update": 0, "skip": 0 }
},
"errors": [],
"warnings": []
}
}Apply the import
Check the dry run first and apply only when errors is empty. A request body over 8 MB is refused with a 400 saying The file is too large. The limit is 8 MB. before the file is read. When a file has problems the message reads The file has problems. Nothing was changed.
jq -n --slurpfile doc flagswift-config.json \
'{document: $doc[0], mode: "skip", dryRun: false}' |
curl -s -b jar-target.txt -X POST https://target.example.com/api/config/import \
-H "Content-Type: application/json" --data @-{
"status": "success",
"message": "Configuration imported",
"data": { "applied": true, "dryRun": false, "mode": "skip", "errors": [], "warnings": [] }
}Rules to know#
- Importing is all or nothing. One problem anywhere and nothing is written.
- It never deletes. A flag that is not in the file stays where it is.
- Environments are only created, never changed, because production and approval settings protect everyone.
- In an environment that requires approval, existing flags are not changed and new flags arrive switched off. You get a warning with the count.
- A flag whose kill switch is active is left unchanged, and a flag's type cannot change.
- You cannot import a role with permissions you do not hold, or a role that allows production changes if you cannot make them yourself.
- A file can be up to 8 MB, with at most 200 projects, 50 environments, 5,000 flags, 2,000 segments and 25 custom roles. For larger estates, export and import project by project with the API's
projectsfilter.
Scripting it
POST /api/config/import takes dryRun, which defaults to true, so you must send false to write. Console API calls need a signed-in session, not an API key.Good to know#
Take a backup before you replace
Do the keys last
Can I export just one project in the console?
?projects=key1,key2. Environments and custom roles always come along.Will flag history come across?
Can I import into an organization that already has flags?
Is the export safe to store?
If something goes wrong#
That file is not valid JSON
Why: The file was edited or truncated, or is not an export.
Fix: Export again, or restore the original file.
This is not a FlagSwift configuration file, or Unsupported version
Why: The file does not have format flagswift.config, or it has a version this server does not read (this one reads version 1).
Fix: Use a file exported from FlagSwift, and upgrade the target if it is older than the source.
Project is not in the file or this organization / Configures environment which is not in this organization or the file
Why: A flag points at a project or environment that does not exist on the target.
Fix: Re-export with the project and environments included, or create the environment on the target first. Environments in the file are created for you.
Is a boolean flag here and a string flag in the file
Why: A flag with the same key has a different type on the target, and a flag's type cannot change.
Fix: Rename or archive the flag on one side, then import again.
Apply import is greyed out
Why: The report has problems, or there is nothing to change.
Fix: Fix the problems listed in red. If the report says nothing to change, the target already matches the file.
The file is too large
Why: The file is over 8 MB, or has more projects, flags, segments or roles than the limits allow.
Fix: Export and import project by project.
What to check#
- Import the same file again as a check. It should report nothing to change.
- Open a few flags on the target and compare their rollout and targeting with the source.
- Find the
config.exportedandconfig.importedentries in the audit log. - Create API keys for the target and update your apps to use them.