v0.39.0

This release contains a number of fixes and enhancements.

Disk Storage

The on-disk storage backend has been fully integrated with the OPA server, and can now be enabled via configuration:

storage:
  disk:
    directory: /var/opa # put data here
    auto_create: true   # create directory if it doesn't exist
    partitions:         # partitioning is important for data storage,
    - /users/*          # please see the documentation

It is intended to enable the use of OPA in scenarios where the data needed for policy evaluation exceeds the available memory.

The on-disk contents will persist among restarts, but should not be used as a single source of truth: there are no backup mechanisms, and certain data partitioning changes will require a start-over. These are things that may get improved in the future.

For all the details, please refer to the configuration and detailled Disk Storage section of the documentations.

Tooling, SDK, and Runtime

• Server: Add warning when input attribute is missing in POST /v1/data API (#4386) authored by @aflmp
• SDK: Support partial evaluation (#4240), authored by @kroekle; with a fix to avoid using different state (authored by @Iceber)
• Runtime: Suppress payloads in debug logs for handlers that compress responses (/metrics and /debug/pprof) (authored by @christian1607)
• opa test: Add file path to failing tests to make debugging failing tests easier (#4457), authored by @liamg
• opa fmt: avoid whitespace mixed with tabs on with statements (#4376) reported by @tiwood
• Coverage reporting: Remove duplicates from coverage report (#4393) reported by @gianna7wu
• Plugins: Fix broken retry logic in decision logs plugin (#4486) reported by @iamatwork
• Plugins: Update regular polling fallback mechanism for downloader
• Plugins: Support for adding custom parameters and headers for OAuth2 Client Credentials Token request (authored by @srlk)
• Plugins: Log message on unexpected bundle content type (#4278)
• Plugins: Mask Authorization header value in debug logs (#4495)
• Docker images: Use GID 1000 in -rootless images (#4380); also warn when using UID/GID 0.
• Runtime: change processed file event log level to info

Rego and Topdown

• Type checker: Skip pattern JSON Schema attribute compilation (#4426): These are not supported, but could have caused the parsing of a JSON Schema document to fail.
• Topdown: Copy without modifying expr, fixing a bug that could occur when running multiple partial evaluation requests concurrently.
• Compiler strict mode: Raise error on unused imports (#4354) authored by @damienjburks
• AST: Fix print call rewriting in else rules (#4489)
• Compiler: Improve error message on missing with target (#4431) reported by @gabrielfern
• Parser: hint about 'every' future keyword import

Documentation and Website

• AWS CloudFormation Hook: New tutorial
• Community: Stretch background so it covers on larger screens (#4402) authored by @msorens
• Build: Make local dev and PR preview not build everything (#4379)
• Philosophy: Grammar fixes (authored by @ajonesiii)
• README: Add note about Hugo version mismatch errors (authored by @ogazitt)
• Integrations: Add GraphQL-Graphene (authored by @dolevf), Emissary-Ingress (authored by @tayyabjamadar), rekor-sidekick,
• Integrations CI: ensure referenced software is listed, and logo file names match; allow SVG logos
• Envoy: Update policy primer with new control headers
• Envoy: Update bob_token and alice_token in tutorial (authored by @rokkiter)
• Envoy: Include new configurable gRPC msg sizes (authored by @emaincourt)
• Annotations: add missing title to index (authored by @itaysk)

Miscellaneous

• Various dependency bumps, notably:
  • OpenTelemetry-go: 1.4.1 -> 1.6.1
  • Wasmtime-go: 0.34.0 -> 0.35.0
• Binaries and Docker images are now built using Go 1.18; CI runs build/test for Ubuntu and macos with Go 1.16 and 1.17.
• CI: remove go-fuzz, use native go 1.18 fuzzer

v0.38.1

This is a bug fix release that addresses one issue when using opa test with the
--bundle (-b) flag, and a policy that uses the every keyword.

There are no other code changes in this release.

Fixes

• Compiler: don't raise an error with unused declared+generated vars (every) (#4420), reported by @kristiansvalland

v0.38.0

This release contains a number of fixes and enhancements.

It contains one backwards-incompatible change to the JSON representation
of metrics in Status API payloads, please see the section below.

Rich Metadata

It is now possible to annotate Rego policies in a way that can be
processed programmatically, using Rich Metadata.

# METADATA
# title: My rule
# description: A rule that determines if x is allowed.
# authors:
# - Jane Austin <[email protected]>
allow {
  ...
}

The available keys are:

• title
• description
• authors
• organizations
• related_resources
• schemas
• scope
• custom

Custom annotations can be used to annotate rules, packages, and
documents with whatever you specifically need, beyond the generic
keywords.

Annotations can be retrieved using the Golang library
or via the CLI, opa inspect -a.

All the details can be found in the documentation on Annotations.

Every Keyword

A new keyword for explicit iteration is added to Rego: every.

It comes in two forms, iterating values, or keys and values, of a
collection, and asserting that the body evaluates successfully for
each binding of key and value to the collection's elements:

every k, v in {"foo": "FOO", "bar": "BAR" } {
  upper(k) == v
}

To use it, import future.keywords.every or future.keywords.

For further information, please refer to the Every Keyword docs
and the new section on FOR SOME and FOR ALL in the Intro docs.

Tooling, SDK, and Runtime

• Compile API: add disableInlining option (#4357) reported and fixed by @srlk
• Status API: add http_code to response (#4259) reported and fixed by @jkbschmid
• Status plugin: publish experimental bundle-related metrics via prometheus endpoint (authored by @rafaelreinert) -- See Status Metrics for details.
• SDK: don't panic without config (#4303) authored by @damienjburks
• Storage: Support index for array appends (for JSON Patch compatibility)
• opa deps: Fix pretty printed output to show virtual documents (#4342)

Rego and Topdown

• Parser: parse 'with' on 'some x in xs' expression (#4226)
• AST: hash containers on insert/update (#4345), fixing a data race reported by @skillcoder
• Planner: Fix bug related to undefined results in dynamic lookups

Documentation and Website

• Policy Reference: update EBNF to include "every" and "some x in ..." (#4216)
• REST API: Update docs on 400 response
• README: Include Google Analytic Instructions
• Envoy primer: use variables instead of objects
• Istio tutorial: expose application to outside traffic
• New "Community" Webpage (authored by @msorens)

WebAssembly

• OPA now uses Wasmtime 0.34.0 to evaluate its Wasm modules.

Miscellaneous

• Build: make build now builds without errors (by disabling Wasm) on darwin/arm64 (M1)
• Various dependency bumps.
  • OpenTelemetry SDK: 1.4.1
  • github.com/prometheus/client_golang: 1.12.1

Backwards incompatible changes

The JSON representation of the Status API's payloads -- both for GET /v1/status
responses and the metrics sent to a remote Status API endpoint -- have changed:

Previously, they had been serialized into JSON using the standard library "encoding/json"
methods. However, the metrics coming from the Prometheus integration are only available
in Golang structs generated from Protobuf definitions. For serializing these into JSON,
the standard library functions are unsuited:

• enums would be converted into numbers,
• field names would be snake_case, not camelCase,
• and NaNs would cause the encoder to panic.

Now, we're using the protobuf ecosystem's jsonpb package, to serialize the Prometheus
metrics into JSON in a way that is compliant with the Protobuf specification.

Concretely, what would before be

  "metrics": {
    "prometheus": {
      "go_gc_duration_seconds": {
        "help": "A summary of the GC invocation durations.",
        "metric": [
          {
            "summary": {
              "quantile": [
                {
                  "quantile": 0,
                  "value": 0.000011799
                },
                {
                  "quantile": 0.25,
                  "value": 0.000011905
                },
                {
                  "quantile": 0.5,
                  "value": 0.000040002
                },
                {
                  "quantile": 0.75,
                  "value": 0.000065238
                },
                {
                  "quantile": 1,
                  "value": 0.000104897
                }
              ],
              "sample_count": 7,
              "sample_sum": 0.000309117
            }
          }
        ],
        "name": "go_gc_duration_seconds",
        "type": 2
      },

is now:

  "metrics": {
    "prometheus": {
      "go_gc_duration_seconds": {
        "name": "go_gc_duration_seconds",
        "help": "A summary of the pause duration of garbage collection cycles.",
        "type": "SUMMARY",
        "metric": [
          {
            "summary": {
              "sampleCount": "1",
              "sampleSum": 4.1765e-05,
              "quantile": [
                {
                  "quantile": 0,
                  "value": 4.1765e-05
                },
                {
                  "quantile": 0.25,
                  "value": 4.1765e-05
                },
                {
                  "quantile": 0.5,
                  "value": 4.1765e-05
                },
                {
                  "quantile": 0.75,
                  "value": 4.1765e-05
                },
                {
                  "quantile": 1,
                  "value": 4.1765e-05
                }
              ]
            }
          }
        ]
      },

Note that sample_count is now sampleCount, and the type is using the enum's
string representation, "SUMMARY", not 2.

Note: For compatibility reasons (the Prometheus golang client doesn't use the V2
protobuf API), this change uses jsonpb and not protojson.

v0.37.2

This is a bugfix release addressing two bugs:

1. A regression introduced in the formatter fix for CVE-2022-23628.
2. Support indices for appending to an array, conforming to JSON Patch (RFC6902)
   for patch bundles.

Miscellaneous

• format: generated vars may have a proper location
• storage: Support index for array appends

v0.37.1

This is a bug fix release that reverts the github.com/prometheus/client_golang
upgrade in v0.37.0. The upgrade exposed an issue in the serialization of Go
runtime metrics in the Status API
(#4319).

Miscellaneous

• Revert "build(deps): bump github.com/prometheus/client_golang (#4307)"

v0.37.0

This release contains a number of fixes and enhancements.

This is the first release that includes a binary and a docker image for
linux/arm64, opa_linux_arm64_static and openpolicyagent/opa:0.37.0-static.
Thanks to @ngraef for contributing the build changes necessary.

Strict Mode

There have been numerous possible checks in the compiler that fall into this category:

1. They would help avoid common mistakes; but
2. Introducing them would potentially break some uncommon, but legitimate use.

We've thus far refrained from introducing them. Now, a new "strict mode"
allows you to opt-in to these checks, and we encourage you to do so!

With OPA 1.0, they will become the new default behaviour.

For more details, see the docs on Compiler Strict Mode.

Delta Bundles

Delta bundles provide a more efficient way to make data changes by containing
patches to data instead of snapshots.
Using them together with HTTP Long Polling,
you can propagate small changes to bundles without waiting for polling delays.

See the documentation
for more details.

Tooling and Runtime

• Bundles bug fix: Roundtrip manifest before hashing to allow changing the manifest
  and still using signature verification of bundles (#4233),
  reported by @CristianJena

• The test runner now also supports custom builtins, when invoked through the Golang
  interface (authored by @MIA-Deltat1995)

• The compile package and the opa build command support a new output format: "plan".
  It represents a query plan, steps needed to take to evaluate a query (with policies).
  The plan format is a JSON encoding of the intermediate representation (IR) used for
  compiling queries and policies into Wasm.

  When calling opa build -t plan ..., the plan can be found in plan.json at the top-
  level directory of the resulting bundle.tar.gz.
  See the documentation for details..

• Compiler+Bundles: Metadata to be added to a bundle's manifest can now be provided via WithMetadata
  (#4289), authored by @marensws, reported by @johanneslarsson

• Plugins: failures in auth plugin resolution are now output, previously panicked, authored by @jcchavezs

• Plugins: Fix error when initializing empty decision logging or status plugin (#4291)

• Bundles: Persisted bundle activation failures are treated like failures with
  non-persisted bundles (#3840), reported by @dsoguet

• Server: http.send caching now works in system policy system.authz (#3946),
  reported by @amrap030.

• Runtime: Apply credentials masking on opa.runtime().config (#4159)

• opa test: removing deprecated code for --show-failure-line (-l), authored by @damienjburks

• opa eval: add description to all output formats

• opa inspect: unhide command for bundle inspection

Rego and Topdown

Built-in function enhancements and fixes:

• object.union_n: New built-in for creating the union of more than two objects (#4012),
  reported by @eliw00d
• graph.reachable_paths: New built-in to calculate the set of reachable paths in a graph (authored by @justinlindh-wf)
• indexof_n: New built-in function to get all the indexes of a specific substring (or character) from a string (authored by @shuheiktgw)
• indexof: Improved performance (authored by @shuheiktgw)
• object.get: Support nested key array for deeper lookups with default (authored by @charlieegan3)
• json.is_valid: Use Golang's json.Valid to avoid unnecessary allocations (authored by @kristiansvalland)

Strict-mode features:

• Add duplicate imports check (#2698) reported by @mikol
• Deprecate any() and all() built-in functions (#2437)
• Make input and data reserved keywords (#2600) reported by @jpeach
• Add unused local assignment check (#2514)

Miscellaneous fixes and enhancements:

• format: don't group iterable when one has defaulted location
• topdown: ability to retrieve input and plug bindings in the Event, authored by @istalker2
• print() built-in: fix bug when used with with modifier and a function call value (#4227)
• ast: don't error when future keyword import is redundant during parsing

Documentation

• A new "CLI" docs section describes the various
  OPA CLI commands and their arguments (#3915)
• Policy Testing: Add reference to rule indexing in the context of test code coverage
  (#4170), reported by @EKCs
• Management: Add hint that S3 regional endpoint should be used with bundles (authored by @danoliver1)
• Many broken links were fixed, thanks to @phelewski
• Fix rendering of details: add detail-tab for collapsable markdown (authored by @bugg123)

WebAssembly

• Add native support for json.is_valid built-in function
  (#4140), authored by @kristiansvalland
• Dependencies: bump wasmtime-go from 0.32.0 to 0.33.1

Miscellaneous

• Publish multi-arch image manifest lists including linux/arm64 (#2233),
  authored by @ngraef, reported by @povilasv
• logging: Remove logger GetFields function (#4114),
  authored by @viovanov
• Website: add versioned docs for latest version, so when 0.37.0 is released, both
  https://www.openpolicyagent.org/docs/v0.37.0/ and https://www.openpolicyagent.org/docs/latest
  contain docs, and 0.37.0 can already be used for stable links to versioned docs pages.
• Community: Initial draft of the community badges program
• make test: fix "too many open files" issue on Mac OS
• Various dependency bumps

v0.36.1

This release includes a number of documentation fixes.
It also includes the experimental binary for darwin/arm64.

There are no code changes.

Documentation

• OpenTelemetry: fix configuration example, authored by @rvalkenaers
• Configuration: fix typo for tls-cert-refresh-period, authored by @mattmahn
• SSH and Sudo authorization: Add missing filename
• Integration: fix example policy

Release

• Build darwin/arm64 in post tag workflow

v0.36.0

This release contains a number of fixes and enhancements.

OpenTelemetry and opa exec

This release adds OpenTelemetry support to OPA. This makes it possible to emit spans to an OpenTelemetry collector via gRPC on both incoming and outgoing (i.e. http.send) calls in the server. See the updated docs on monitoring for more information and configuration options (#1469 authored by @rvalkenaers)

This release also adds a new opa exec command for doing one-off evaluations of policy against input similar to opa eval, but using the full capabilities of the server (config file, plugins, etc). This is particularly useful in contexts such as CI/CD or when enforcing policy for infrastructure as code, where one might want to run OPA with remote bundles and decision logs but without having a running server. See the updated docs on Terraform for an example use case.
(#3525)

Built-in Functions

• Four new functions for working with HMAC (crypto.hmac.md5, crypto.hmac.sha1, crypto.hmac.sha256, and crypto.hmac.sha512) was added (#1740 reported by @jshaw86)
• array.reverse(array) and strings.reverse(string) was added for reversing arrays and strings (#3736 authored by @kristiansvalland and @olamiko)
• The http.send built-in function now uses a metric for counting inter-query cache hits (#4023 authored by @mirayadav)
• An overflow issue with dates very far in the future has been fixed in the time.* built-in functions (#4098 reported by @morgante)

Tooling

• A problem with future keyword import of in was fixed for opa fmt (#4111, reported by @keshavprasadms)
• An issue with opa fmt when refs contained operators was fixed (authored by @jaspervdj-luminal)
• Fix file renaming check in optimization using opa build (authored by @davidmarne-wf)
• The allow_net capability was added, allowing setting limits on what hosts can be reached in built-ins like http.send and net.lookup_ip_addr (#3665)

Server

• A new credential provider for AWS credential files was added (#2786 reported by @rgueldem)
• The new --tls-cert-refresh-period flag can now be provided to opa run. If used with a positive duration, such as "5m" (5 minutes),
  "24h", etc, the server will track the certificate and key files' contents. When their content changes, the certificates will be
  reloaded (#2500 reported by @patoarvizu)
• A new v1/status endpoint was added, providing the same data as the status plugin would send to a remote endpoint (#4089)
• The HTTP router of OPA is now exposed to the plugin manager (#2777 authored by @bhoriuchi reported by @mneil)
• Calling print now works in decision masking policies
• An unintended switch between long/regular polling on 304 HTTP status was fixed (#3923 authored by @floriangasc)
• The error message about prohibited config in the discovery plugin has been improved
• The discovery plugin no longer panics in Trigger() if downloader is nil
• The bundle plugin now ignores service errors for file:// resources
• The bundle plugin file loader was updated to support directories
• A timer to HTTP request was added to the downloader
• The requested_by field in the logging plugin is now optional

Rego

• The error message raised when using - with a number and a set is now more specific (as opposed to the correct usage with two sets, or two numbers) (#1643)

• Fixed an edge case when using print and arrays in unification (#4078)

• Improved performance of some array operations by caching an array's groundness bit (#3679)

• ⚠️ Stricter check of arity in undefined function stage (#4054).
  This change will fail evaluation in some unusual cases where it previously would succeed, but these policies should be very uncommon.

  An example policy that previously would succeed but no longer will (wrong arity):

package policy

default p = false
p {
    x := is_blue()
    input.bar[x]
}

is_blue(fruit) = y { # doesn't use fruit
    y := input.foo
}

SDK

• The opa.runtime() built-in is now made available to the SDK (#4050 authored by @oren-zohar and @cmschuetz)
• Plugins are now exposed on the SDK object
• The SDK now supports graceful shutdown (#3980 reported by @brianchhun-chime)
• print output is now sent to the configured logger

Website and Documentation

• All pages in the docs now have a feedback button (#3664 authored by @alan-ma)
• The Kafka docs have been updated to use the new Kafka plugin, and to use the OPA management APIs
• The Terraform tutorial was updated to use opa exec (#3965)
• The docs on Contributing as well as the Vendor Guidelines have been updated
• The term "whitelist" has been replaced by "allowlist" across the docs
• A simple destructuring assignment example was added to the docs
• The docs have been reviewed on the use of assignment, equality and comparison operators, to make sure they follow best practice

CI

• SHA256 checksums of CI builds now published to release directory (#3448 authored by @johanneslarsson reported by @raesene)
• golangci-lint upgraded to v1.43.0 (authored by @shuheiktgw)
• The build now creates an executable for darwin/arm64. This should work as expected, but is currently tested in the CI pipeline like the other binaries
• PRs targeting the ecosystem page are now checked for mistakes using Rego policies

v0.35.0

This release contains a number of fixes and enhancements.

Early Exit Optimization

This release adds an early exit optimization to the evaluator. With this optimization, the evaluator stops evaluating rules when an answer has been found and subsequent evaluation would not yield any new answers. The optimization is automatically applied to complete rules and functions that meet specific requirements. For more information see the Early Exit in Rule Evaluation section in the docs. #2092

Built-in Functions

• The net.lookup_ip_addr function was added to allow policies to resolve hostnames to IPv4/IPv6 addresses (#3993)
• The http.send function has been improved to close TCP connections quickly after receiving the HTTP response and avoid creating HTTP clients unnecessarily when a cached response exists (#4015). This change reduces the number of open file descriptors required in high-throughput environments and prevents OPA from encountering ulimit errors.

Rego

• print() calls in the head of rules no longer cause runtime errors (#3967)
• Type errors for calls to undefined functions no longer contain rewritten variable names (#4031)
• The rego.SkipPartialNamespace option now correctly sets the flag on the partial evaluation queries (previously it would always set the value to true) (#3996) authored by @thomascoquet
• The internal set implementation has been updated to insert elements in sorted order rather than lazily sorting during comparisons.
• Fixed import alias parsing bug identified by fuzzer (#3988)

WebAssembly

• The Golang SDK will now issue a grow() call if the input document exceeds the available memory space.
• The malloc() implementation will now call opa_abort if the grow() call fails.

Server

• The decision logger adapts upload chunk sizes based on previous outputs. This allows the decision loggger to encode significantly more decisions into each upload chunk, thereby reducing heap usage for buffered decisions. For more information on the adapative chunking behaviour, see the Decision Logs page in the docs.
• The decision logger can be configured to send records to a custom plugin as well as an HTTP endpoint at the same time (#4013)
• print() calls from the system.authz policy are now included in the logs (#4048)
• OPA can use an Azure Managed Identities Token to authenticate with control plane services (#3916) authored by @Scowluga.
• The logging configuration will be correctly applied to service clients so that DEBUG logs are surfaced (#4071)

Tooling

• The opa fmt command will not generate a line-break when there are generated variables in a function call (#4018) reported by @torsrex
• The opa inspect command no longer prints a blank namespace when a data.json file is included at the root (#4022)
• The opa build command will output debug messages if an optimized entrypoint is discarded.

Website and Documentation

• The website has been updated to build with Hugo 0.88.1 (#3787)
• The version picker in the documentation is now scrollable (#3955) authored by @orweis
• The description of the urlquery built-in functions have been clarified (#1592) reported by @klarose
• The decision logger documentation has been improved to cover controls for large-scale environments (#3976)
• The "strict built-in errors" mode is now covered in the docs along with built-in function error behaviour (#3686)
• The OAuth2 and OIDC examples around key rotation and caching have been improved

CI

• Issues and PRs that have not seen activity in 30 days will be automatically marked as "inactive"
• The Makefile can now produce Docker images for other architectures. We do not yet publish binaries or images for non-amd64 architectures however if you want to build OPA yourself, the Makefile does not prohibit it.

Backwards Compatibility

• The diagnostics buffer in the OPA server has been completely removed as part of the deprecation and removal of the diagnostic feature (#1052)

v0.34.2

Fixes

• ast: Fix print call rewriting for calls in head (#3967)