Skip to main content

Enterprise OPA Preview in VS Code

With the Styra VS Code Tools extension, 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.

SettingDefaultDescription
Opa: Roots[${workspaceFolder}]Bundle roots to search when looking for Rego policies and data (inherited from the Open Policy Agent extension).
Enterprise OPA: Urlhttp://localhost:8181The URL where the Enterprise OPA HTTP API is accessible.
Enterprise OPA > Preview: Default QueryThe default query to run when performing an Enterprise OPA: Preview.
Enterprise OPA > Preview: PrefixA 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: StrategyallDetermine 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 LenstrueEnable or disable support for Enterprise OPA preview Code Lens links.
Enterprise OPA > Auth: TypenoneDetermine what kind of authorization to use when connecting to the Enterprise OPA API.
Enterprise OPA > Auth: Client Cert PemA file path to a PEM encoded client certificate used for TLS authentication.
Enterprise OPA > Auth: Client Key PemA file path to a PEM encoded client key used for TLS authentication.
Enterprise OPA > Auth: Client Cert CAA file path to a PEM encoded custom certificate authority certificate to trust when connecting to Enterprise OPA.
Enterprise OPA > Auth: Allow Unauthorized TLSfalseWhether 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:

NameDescription
instrumentInclude extended metrics in preview returns for more in depth debugging
printInclude output generated with print() in preview returns
provenanceInclude provenance data in preview returns
sandboxExclude existing policies and data when evaluating a preview request
strictCompile previewed rego modules in strict mode
strict-builtin-errorsReturn 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. 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 LensStyra 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 outputStyra VS Code Tools Enterprise OPA preview output