Skip to main content

Migrate from a Global Policy Library or Data Source

Migrating policy or data from a deprecated Global resource to a Library enables the use of new features exclusive to Libraries as well as future new Library functionality. This page outlines the general steps required to migrate a Global resource to a Library, however additional changes may be required depending on your specific policies and data.

Library and Global Differences​

The primary differences between a Global and a Library resource include:

  • Namespace: Libraries use data.libraries while Globals use data.global
  • Access Control: Libraries support restricting access for users, SSO claims, and API tokens based on Library-level controls. Globals do not allow for user or SSO claim access controls.
  • UI Management: Libraries can be created and fully managed in the UI in the "LIBRARIES" section of the left-hand menu, including full policy authoring and managing Data Sources with data transforms. Existing Global resources can only be viewed and managed (update settings, delete) in the "GLOBAL" section of the left-hand menu.
  • API: Libraries use the dedicated /v1/libraries API to manage a Library resource.
  • Git: Libraries can optionally be configured with a Git repository connection and a read-only configuration. Globals are always read-only in the UI and are almost always Git-backed.
  • Root Data Source: While both Libraries and Globals support the creation of a root-level Data Source via the API, a root-level Global Data Source will not be shown nor can be managed in the UI. A root-level Library Data Source will be shown and can be managed in the LIBRARIES section of the UI.
  • Testing and Log Replay: Libraries introduce support for running tests and log replay via the Validate functionality in the DAS UI.
  • Policy SBOM inclusion: Git-backed Libraries are included in a System bundle's Policy SBOM.
  • Library dependency tracking: DAS tracks the usage of a Library in a System bundle and details the dependencies in the Systems and Libraries APIs.

Migrate Global Policy Libraries​

Global policy libraries can be directly migrated to a Library resource.

1. Package Changes​

Policies in an existing Global resource will use the global namespace (e.g., package global.my_helper_utils). Before creating a Library resource and adding those same policies, update each Rego file to use libraries in place of global. For example, package global.my_helper_utils would change to package libraries.my_helper_utils.

info

Because of the package namespace difference, a Library and a Global cannot use the same Git repository, path, and reference (e.g., branch, tag). Doing so could cause one or the other to lose its policies in DAS, affecting any Systems, Stacks, or Libraries using those policies. When using a Git repository to manage these policies, it is recommended to use a new Git branch or tag for these changes if the Library will use the same repository as the Global resource.

2. References Within Library Policies​

If policies in your Global library import or reference other packages within the library, update those references to use the libraries package path in place of global. For example, if a policy includes an import like import data.global.my_helper_utils.my_util_foo or a direct reference like foo := data.global.my_helper_utils.my_util_foo(params), those should be updated to import data.libraries.my_helper_utils.my_util_foo and foo := data.libraries.my_helper_utils.my_util_foo(params), respectively.

If your library policies also include imports or references to policies in other Globals which have not yet migrated to a Library, keep those references using data.global until those Globals are migrated.

3. Create and Configure the Library​

After updating the package names and any internal references, create a Library resource using the UI (refer to Create a Library) or the Upsert a new library API. The Git connection to your policy repository can be configured in the Upsert Library API call during creation, or it can be configured in the UI in the Library's Settings > Git Repository page.

4. Transition References to the Library​

With your policies now migrated to a Library, you can update policies in Systems, Stacks, and other Libraries/Globals to use data.libraries to reference the Library resource instead of the Global resource, similar to Step 2 above.

It is recommended to first transition single policies or single Systems, Stacks, or Libraries/Globals to test that the updated policies return the same results as before. After confirming policy behavior is correct, update remaining policy library references.

Migrate Global Data Sources​

Global Data Sources can be migrated to either a Data Source in a Library (recommended) or a root-level Library Data Source. While a root-level Library Data Source may be more easily discoverable within the Styra DAS UI, creating a Data Source within a Library provides a number of benefits:

  • Access controls for users, SSO claims, and API tokens
  • Organize Data Sources in nested namespaces
  • Group related Data Sources in a Library

1. Create and Configure Library Data Source​

Data Sources contained within a Library can be created either using the UI or the API. In the UI, Create a Library or select an existing Library, click the kebab icon (three dots ⋮) to the right of the Library, select Add Data Source, and configure your Data Source. This can also be accomplished via the UpsertDatasource API for an existing Library. For example, to create a Data Source in a Library named my_helper_data, make the UpsertDatasource API call to /v1/datasources/libraries/my_helper_data/{datasource_name}.

To create a root-level Library Data Source, make an UpsertDatasource API to /v1/datasources/libraries/{datasource_name}.

2. Transition References to the Library Data Source​

With your Data Source now migrated to a Library, you can update policies in Systems, Stacks, and other Libraries/Globals to use data.libraries to reference the Library Data Source instead of the Global Data Source. For example, if a policy includes an import like import data.global.my_data_source or a direct reference like foo := data.global.my_data_source, those should be updated to import data.libraries.my_helper_data.my_data_source and foo := data.libraries.my_helper_data.my_data_source, respectively. If your migrated Data Source is a root-level Library Data Source, the policies would reference data.libraries.my_data_source instead.

It is recommended to first transition single policies or single Systems, Stacks, or Libraries/Globals to test that the updated policies return the same results using the Library Data Source as before. After confirming policy behavior is correct, update remaining Data Source references.