OPA upgrade guide

Migration to OPA v1.x from can be easily done from OPA v0.59 and later (M22 and later releases). For migration from earlier versions please migrate to v0.70 first (as it is latest tested) as they don't support v1 syntax. All rules in codebase are written with v1 import so they are backward compatible with OPA 0.59+

Rules migration guide

Description how migrate your custom rules is in Rules migration guide

Rules backup

Before running the upgrade rules backup is recommended using Backup API

Upgrade process

Upgrade consists of 2 major steps: 1. Upgrade default rules to new syntax 2. Upgrade server to v1.x

Default instance and partition policy rules can be simply upgraded by running existing bootstrap processes, but when server is using bundles you might not want to upgrade partition policies with it due to bundling impact

OPA server upgrade will require changing OPA container version to new one and add --v0-compatible to it's running command to maintain backwards compatibility (recommended).

The order what should be migrated first rules or service have the following impact:

Upgrading rules to newer version first might be beneficial as providers might decide to upgrade without v0 compatible enforcing users to write rules in new format without a downtime. However, rules created by other users won't be updated, so they might cause issues. It is also important to understand bundling impact for policies.

Bundling impact

System policies are in single bundle and replacing bundle with the new one should be enough. However, there is a problem with partition policies. Currently, all partition policies for single partition are stored in the single bundle. There will be both default partition policies and all user provided policies. Overriding the entire bundle would remove all policies provided by the user. They should be rather updated by API one by one instead unless we will reload user policies from backup.