Skip to main content

Operations

This page describes the various operations on a Data Source.

Create a Data Source​

Data Sources are created within Systems. For each Data Source, run a PUT under v1/datasources and provide the location and hierarchical name of the data source.

The following examples show the API calls to create a Data Source named foo/bar (referenced in policy as foo.bar) in each location.

note

For Systems and Stacks, replace YYY with the ID of the corresponding System or Stack.

  • System: PUT https://<das-id>.styra.com/v1/datasources/systems/YYY/foo/bar.

  • Stack: PUT https://<das-id>.styra.com/v1/datasources/stacks/YYY/foo/bar.

  • Library: PUT https://<das-id>.styra.com/v1/datasources/global/foo/bar.

You can mount your Data Sources in locations other than Systems, Stacks, and Libraries; however, those Data Sources are not used by the Policies.

Run the following curl command to create a data source under system YYY.

curl -H 'Authorization: Bearer XXX' -H 'Content-Type: application/json' \
  -X PUT https://<das-id>.styra.com/v1/datasources/global/foo/bar \
  -d '
{
  "category": "rest"
}'

The category and type fields describe what kind of Data Source you want to create. The Data Source described here requires that you push the data through the DAS REST API.

tip

To configure the Data Source agents for Kubernetes systems, see the Kubernetes Data Source documentation.

Limitations​

The following limitations apply to Data Sources.

  • The Data Source name should not be a prefix of another Data Source name. For example, the Data Source foo should not be created if the data source foo/bar already exists (or vice versa).

  • The Data Source name should not be a prefix of a Policy name (or vice versa). For example, if the Policy package foo.bar exists then the data source foo does not exist.

Use a Data Source​

After a Data Source is created, you can read and write the JSON data through the DAS API by using v1/data instead of v1/datasources as follows:

  1. Read the JSON data with GET https://<das-id>.styra.com/v1/data/global/foo/bar. For example, run the following curl command to read the JSON data from the data source.

    curl -H 'Authorization: Bearer XXX' \
      -X GET https://<das-id>.styra.com/v1/data/global/foo/bar

  2. Update the JSON data with PUT https://<das-id>.styra.com/v1/data/global/foo/bar <data>. For example, run the following curl command to write the JSON data into the data source.

    curl -H 'Authorization: Bearer XXX' -H 'Content-Type: application/json' \
      -X PUT https://<das-id>.styra.com/v1/data/global/foo/bar \
      -d '{"baz": {"qux": 7}}'

Additionally, when writing policies you can use the data source with the keyword data. A slightly different Rego reference is used for each of the Systems, Stacks, and Libraries.

  • Systems: A Styra DAS System provides a sandbox so that anything located under v1/data/system/YYY/ appears as if it is in the root data namespace. A System's data sources (or policies) are not accessible by other Systems. For example, data source v1/datasource/system/YYY/foo/bar is referenced as data.foo.bar.

  • Stacks: A Styra DAS Stack exists in the global namespace so that it can be used across many Systems. The Data Source v1/datasource/stack/YYY/foo/bar is referenced from Rego as data.stack.YYY.foo.bar.

  • Libraries: The Styra DAS Library is a global collection of Rego that all Systems and all Stacks can import and use. The Data Source v1/datasource/global/foo/bar is referenced from Rego as data.global.foo.bar.

The following shows an example when the Data Source is created in the Library.

package rules

datasource_succeeded { data.global.foo.bar.baz.qux == 7 }

Preview a Data Source​

You can preview a Data Source by clicking on the Refresh data button that appears in the right hand side of Your System >> Add Data Source dialog. The Refresh data button allows you to preview the data that are retrieved from the Data Source. It also allows you to optionally transform if a Rego transform is specified on the Data Source. You can modify the Data Source parameters to adjust either the data retrieved or the transformation performed on it. Also, modify the settings of a created Data Source with the preview capability and ability to adjust the Data Source parameters. Click on the Refresh data to refresh the changes you made during Data Source creation. For more information on Data Sources APIs, see the ExecuteDatasource API documentation.

Delete a Data Source​

You can delete a Data Source by running a DELETE command on the Data Source's name located under v1/datasources.

For example, run the following curl command to delete the data source constructed earlier.

curl -H 'Authorization: Bearer XXX' -H 'Content-Type: application/json' \
  -X DELETE https://<das-id>.styra.com/v1/datasources/global/foo/bar

Once the Data Source is deleted, subsequent PUT commands will return errors. However, a Policy referencing the Data Source will not produce an error. Instead, the value of that data reference will be undefined in Rego.