github.com/open-policy-agent/opa

Fixes

• compile: Change name of result var for wasm binary (#2441)
• format: Deep copy inputs to avoid mutating the caller's copy (#2439)

Miscellaneous

• docs: Add opa_println to wasm required imports

Fixes

• format: Refactor wildcard names to rewrite early (#2430)

Fixes

• docs/content small output correction on terraform page (#1772)
• format: Fix wildcards in nested refs

Fixes

• format: Fix panic with else blocks and comments (#2420)

This release fixes an issue in the Docker image build. The default ca-certificates were not being included becasue the Docker image is FROM scratch now.

Major Features

This release includes a number of features, optimizations, and bugfixes.

Version Reporting

OPA now determines the latest stable release version using https://telemetry.openpolicyagent.org. The only information provided to the telemetry service is the version (e.g., 0.20.0), a UUIDv4 generated on startup, and the build platform/architecture (e.g., darwin, amd64). This feature is on by default in opa run however it can be easily disabled by specifying --skip-version-check on the command-line. If you are inside the REPL, type help to see the latest version information. If you are running OPA as a server, OPA will log an INFO level message indicating if OPA is out of date. Version checking is best-effort. Any errors that occur while communicating with https://telemetry.openpolicyagent.org are only logged at DEBUG level. For more information see https://openpolicyagent.org/docs/latest/privacy/.

New opa build command

The opa build command can now be used to package OPA policy and data files into bundles that can be easily distributed via HTTP. See opa build --help for details. This change is backwards incompatible. If you were previously relying on opa build to compile policies to wasm, you can still do so:

# before v0.20.0
opa build -d policy.rego 'data.example.allow'

# v0.20.0 and newer
opa build policy.rego -e example/allow -t wasm

Built-in Functions

This release includes a number of new built-in functions:

• graph.reachable for computing the transitive closure from edge sets. This function allows users to write policies that traverse organization charts, security groups, etc. (thanks to @jaspervdj-luminal!)
• io.jwt.verify_rs512 and other variants (rs/es/hs/ps, 384/512) were added (thanks to @GBrawl!)
• uuid.rfc4122 for generating UUIDv4s (thanks to @reneklootwijk!)

This release also includes a few fixes to existing built-in functions:

• units.parse_bytes now supports units without the B or b suffix (thanks to @GBrawl!)
• io.jwt.verify_decode now supports floating-point nbf and exp claims (thanks to @GBrawl!)
• array.slice clamping logic fixed to prevent panic (#2320).

Operations

• The opa run command now supports a --diagnostic-addr flag that causes the server to expose the /health and /metric endpoint on a different address. This makes it easier to secure sidecar deployments in Kubernetes because the main API endpoints can be served on localhost and the diagnostic endpoints can be served on 0.0.0.0 so that the kubelet and other components can access them (#2002). The envoy tutorial has been updated to show this in action.

• The AWS credential provided has been updated to support the standard AWS_SESSION_TOKEN and AWS_SECURITY_TOKEN environment variables. These are used when signing S3 bundle requests for an AWS IAM assumed role (thanks to @kpiotrowski!)

WebAssembly

This release includes a number of improvements for wasm compiled policies.

• UTF-8 and UTF-16 strings are now fully supported in the internal string representation (#1885)
• Numeric values are implemented on top of arbitrary-precision floating point numbers to avoid loss-of-precision issues.
• The arithemetic, set, array, and type checking built-in function categories are now supported by the wasm library. This means they do not have to be implemented by the language-specific opa-wasm SDKs.
• The set and object implementations now use a chained hash set under the hood (#2225)

Performance

• OPA will attempt to index collections generated by comprehensions to ensure linear runtime for policies performing "group-by" operations (e.g., inverting an objects.) For more information see the Policy Performance page (#2276).

Tooling

• The OPA extension for VS Code now supports Go To Definition inside policies. This feature uses the new opa oracle find-definition command.
• The opa test command now includes location information on trace output.
• The opa fmt command now preserves else block style when possible (thanks to @mikaelcabot!)

Documentation

This release includes several improvements to the website and documentation.

• Improved terraform tutorial example (#1772) (thanks to @princespaghetti!)
• Fixed token validation logic in envoy tutorial example (#2395) (thanks to @princespaghetti!)
• Usability issues on the frontpage have been resolved (#2205, #2206 (thanks to @arunbsar!)
• The Policy Performance page now includes resource utilization guidelines (#1601)
• By popular demand, the "document model" explanation has been brought back into existence. It now lives in the Philosophy section (#2284).
• The Ecosystem page implements a simple sorting algorithm that ranks items by amount of related content.
• The policy cheat sheet has been merged into the Policy Reference page.

Fixes

• REPL now correctly displays booleans in tabled output (#2338, thanks to @timakin!)
• Discovery now supports service configuration updates. This makes token refresh easier in distributed environments on AWS. (#2058)
• Fixed compiler panic if body omitted from else statement (#2353)
• Fixed panic in /health API with the envoy plugin (#2396)
• Partial Evaluation no longer generates unsafe queries for certain negated expressions (#2045)
• Partial Evaluation no longer saves an incorrect binding list in some cases (#2368)
• Output variable analysis no longer visits closures. This makes the analysis easier to use outside of the safety check.
• Rules parsed from expressions now have location information set correctly.

Miscellaneous

• If you are building OPA for debian systems, the Makefile now supports a make deb target. The target requires dpkg-deb to be installed. Thanks to @keshto for contributing this!
• OPA is now built, by default, with CGO disabled. Also, the default Docker image (openpolicyagent/opa) is back to using FROM scratch.

Backwards Compatibility

• An internal utility function that unmarshals JSON (util.UnmarshalJSON) has been fixed to return an error if the input bytes contain garbage following a valid JSON value. In the past, the util.UnmarshalJSON function would just return the valid JSON value and ignore the garbage following it. This change is backwards incompatible since clients that were previously transmitting bad data will now receive an error, however, we think it's important to surface errors rather than hide them (#2331).

• The Go plugin/shared library loading feature that was deprecated in v0.14.0 has finally been removed completely. If you are interested in extending OPA, see the Extensions for how to do so at compile-time (#2049).

• The github.com/open-policy-agent/opa/metrics#Counter interface has been extended to require an Add(uint64) function. This change only affects users that have implemented their own version of the github.com/open-policy-agent/opa/metrics#Metrics interface (which is the factory for counters.)

• As mentioned above, the opa build command-line syntax has changed. We think this is the right time to refresh the command and we are more confident that the new syntax will remain stable going forward.

Deprecation

• This release deprecates opa test -l flag. Since we now display the trace with line information, this flag is no longer needed.

• In the next release we plan to deprecate the ?watch and ?partial HTTP API parameters. The ?watch feature is unused and introduces significant complexity in the server implementation. The ?partial parameter lazily invokes Partial Evaluation inline with policy invocation. This is useful for development and debug purposes, however, it's not recommended for enforcement points ot use (since PE optimization can introduce significant latency.) Users should rely on the new opa build command to perform PE on their policies. See opa build --help for more information.

Fixes

• plugins: Fix race between manager and plugin startup (#2343)