Migrate Data and Policies

Oso Cloud is stateful, much like a database: it stores your policies and your authorization data (like role assignments and group memberships). As with any stateful system, there will be times when you need to update the data stored in Oso Cloud. Perhaps you're performing a data migration in your app that changes the hierarchy of resources. Or maybe you're refactoring your policy code to add a new authorization feature. In these cases it's necessary to think about how the system will work for the duration of the change.

Example scenario: Renaming a role

Imagine a simple RBAC scenario: you have a User type and and an Org type, and users can have roles on orgs:

But now you want to rename the admin role to owner -- perhaps you're planning to broaden the capabilities of admins and make it a separate role. You can't just update the policy and replace all instances of admin with owner. If you did, the existing admins would lose their permissions until you updated the has_role facts to use owner roles.

Because Oso uses a configuration language (Polar), it's possible to write rules in your policy that "bridge the gap" between old and new versions of application code and data formats.

Migration steps

The way to do this is with four steps:

1. Deploy your new policy, with extra "bridge" rules that maps old facts to new facts. In this case, mapping old facts to new facts looks like this:

2. Deploy your new application code that writes owner facts to Oso Cloud. At this point, other than the rule you wrote in part (1), no policy or application code needs to know about the old admin role.
   Note that you could be done here if you didn't mind keeping your old admin facts around. However, we recommend cleaning up old facts and interim "bridge" rules from your policy.

3. To migrate all the admin facts to new owner facts, you can use a combination of the Get API and the Bulk Insert API. You'll insert a new has_role(User, "owner", Org) fact for each existing has_role(User, "admin", Org) fact. If you want to clean up old facts, you can use the Bulk Delete API to do so.
4. Once all the role facts have been migrated to their new versions, you can clean up the "bridge" rules from your policy.

Oso Cloud Migration feature

To help facilitate the process above, we're designing a Migration feature built into Oso Cloud. This would help perform the data rewriting, and would effectively eliminate steps 3 and 4 from each of your migrations. To learn more, or to provide input on the design of the feature, reach out to us below:

Talk to an Oso engineer

If you have additional questions about performing data migrations in Oso Cloud, schedule a 1x1 with an Oso engineer. We're happy to help.

Get started with Oso Cloud →