Enterprise OPA Preview in VS Code

With Styra VS Code Tools, you can preview decisions from your Enterprise OPA instance reflecting any new or updated policies and data in your project.

Configuration

Enterprise OPA preview configuration give you control over the connection to the Enterprise OPA instance, how files are mapped, and how preview requests are processed.

Setting	Default	Description
Opa: Roots	[${workspaceFolder}]	Bundle roots to search when looking for Rego policies and data (inherited from the Open Policy Agent extension).
Enterprise OPA: Url	http://localhost:8181	The URL where the Enterprise OPA HTTP API is accessible.
Enterprise OPA > Preview: Default Query		The default query to run when performing an Enterprise OPA: Preview.
Enterprise OPA > Preview: Prefix		A prefix to add to all policy paths when mapping for Enterprise OPA preview.
Enterprise OPA > Preview: Arguments	[]	Controls the behavior and features of Enterprise OPA preview calls.
Enterprise OPA > Preview: Strategy	all	Determine which files to map for Enterprise OPA preview calls.
Enterprise OPA > Preview: Ignore	[]	A set of glob patterns to omit when mapping for Enterprise OPA preview calls.
Enterprise OPA > Preview: Code Lens	true	Enable or disable support for Enterprise OPA preview Code Lens links.
Enterprise OPA > Auth: Type	none	Determine what kind of authorization to use when connecting to the Enterprise OPA API.
Enterprise OPA > Auth: Client Cert Pem		A file path to a PEM encoded client certificate used for TLS authentication.
Enterprise OPA > Auth: Client Key Pem		A file path to a PEM encoded client key used for TLS authentication.
Enterprise OPA > Auth: Client Cert CA		A file path to a PEM encoded custom certificate authority certificate to trust when connecting to Enterprise OPA.
Enterprise OPA > Auth: Allow Unauthorized TLS	false	Whether or not to trust Enterprise OPA when the returned TLS certificate is from an unknown authority.

Preview Arguments

Enterprise OPA > Preview: Arguments contains various settings which control the behavior of the Enterprise OPA preview API. The available options are as follows:

Name	Description
instrument	Include extended metrics in preview returns for more in depth debugging
print	Include output generated with print() in preview returns
provenance	Include provenance data in preview returns
sandbox	Exclude existing policies and data when evaluating a preview request
strict	Compile previewed rego modules in strict mode
strict-builtin-errors	Return an error in the event an error is generated from a built-in function instead of undefined

Set Up

Prerequisites

Before you can preview decisions you need access to the REST API of an Enterprise OPA instance configured to process preview requests (TODO: link to eopa config docs). This may be a locally running instance, or a remote instance accessed through something such as kubectl port-forward.

Configure your Workspace

Once you have access to the Enterprise OPA REST API, configure your workspace to access it.

Open up your VS Code settings using CMD + , and type 'OPA' in the search bar. provide the base URL of your Enterprise OPA instance in Enterprise OPA: Url. Next, if your policy files are in a subdirectory, configure Opa > Roots to include that subdirectory so that policy mapping is performed at the correct location in your project. Finally, if your project has a default query, configure Enterprise OPA > Preview: Default Query so you can run the query from any rego file in your project.

note

It is best to configure most of your settings at the 'Workspace' level in VS Code since each project is different, and likely requires a different preview configuration.

Run a Preview

Once your project is configured, you can begin running Previews against the Enterprise OPA instance. If you have the Enterprise OPA > Preview: Code Lens setting enabled (it is by default), you can click 'Run Preview' at the top of any Rego document to execute the default query. If no default query is configured, this will evaluate and return results for the Rego package associated with the active Rego file.

Styra VS Code Tools Enterprise OPA Preview Code Lens

In addition to the Code Lens link, you can run a preview from the right-click contextual menu, as well as through the command palette using the Enterprise OPA: Preview commands.

note

The right-click contextual menu will provide access to the Enterprise OPA: Preview Selection command only when the editor contains selected text.

The results of your Preview will appear in the 'Enterprise OPA Preview' output pane.

Styra VS Code Tools Enterprise OPA preview output