Octopus 2.6 uses RavenDB, while Octopus 3.0 uses SQL Server. Of course, this means that we need some way to help you migrate data from 2.6 to 3.0. Since we're putting so much effort into data migration, we may as well make it a feature: it's also going to be a general Octopus 3.0 exporter and importer.
The migrator tool will support the following four scenarios:
- Importing data from 2.6 into a 3.0 server
- Exporting data from a 3.0 server, and importing it back into a 3.0 server
- Splitting data from a 3.0 server into two or more
- Merging data from multiple 3.0 servers into one
The data that we'll import and export is limited to "configuration"-style data (i.e., projects, environments, machines, deployment processes, variable sets, teams, NuGet feeds, and so on). We don't plan to support exporting historical data (i.e., releases, deployments, and audit events), but we will eventually import historical data from 2.6 backups.
Exporting
The exporter tool exports data as JSON files inside a directory.
What can you do with this export?
- Commit it to a Git repository
We're making the JSON as friendly and predictable as possible so that if you commit multiple exports, the only differences that will appear are actual changes that have been made, and comparing the changes will be obvious. - Transfer it to a new Octopus server
You can delete files you don't want to import (e.g., if you're transferring one project, just delete everything except the files for that project) and then import it using the Importer.
While the JSON files contain ID's, when importing, we actually use the names to determine if something already exists. This means you can export from multiple Octopus servers, combine them together, and then import to a single Octopus server.
If you use sensitive variables, these will be encrypted in the JSON using a password (note that sensitive variables are normally stored in SQL encrypted with your master key; the exporter will decrypt them, then encrypt them with this new password). Assuming you use the same password between exports, you'll get the same output, so they won't appear as changed in your diff tool.
Importing
The importer tool can either take an exported directory and the password used to export it, or an Octopus 2.6 backup file (.octobak) and the Octopus master key. It will then import the data.
You'll get a chance to preview the changes first, and you can tell the tool to either:
- Overwrite documents if they already exist in the destination (e.g., if a project with the same name already exists, overwrite it)
- Skip documents if they already exist in the destination (e.g., if a project with the same name already exists, do nothing)
The importer wraps all data changes in a SQL transaction; if any problems are discovered during the import, the transaction will be rolled back and nothing will be imported.
Is history important?
As I mentioned, one feature we are currently leaving out for our upcoming public beta of 3.0 is exporting and importing deployment history (even from 2.6) - i.e., releases, deployments, tasks, artifacts, and audit events won't be exported or imported. Those are much more complicated, so we plan to ship this tool as-is, then add history later.
We definitely plan to extend the importer to import history from 2.6 backups before 3.0 ships. What we're not sure about, is whether it's important to import and export history in 3.0 - we figure the vast majority of people only care about project configuration data, not history. We'd love to hear some scenarios where 3.0 import of history might be useful.
PS: Like the new admin tool look?