We pulled the config docs out into their own section from the
/management page. In the process we missed some links that needed
updating.
Signed-off-by: Patrick East <east.patrick@gmail.com>
Previously the behavior of the type-checking functions was arguably
underdescribed in the docs when the type-check failed.
This change specifies that the result is undefined.
Signed-off-by: Tim Hinrichs <tim@styra.com>
Users frequently ask how to implement custom built-in functions and up
until now the information has been a bit hidden. This change improves
the visibility of the docs that describe how to customize/extend
OPA. We should revisit the section on how to customize the OPA daemon
to demonstrate how to use dep or modules as well as how to instantiate
only select portions of OPA (e.g., the plugin manager with a custom
gRPC server.)
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
* Move the integration guide into the core docs. This is one of the
most common questions when people get started.
* Split the configuration and monitoring sections into their own
pages. This prepares the management page for an introduction that
explains the control plane concept.
* Move bundle section up to the top of the page since basic policy
distribution is usually the first concern.
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
This commit updates the introduction page to focus on Rego and
integrating with OPA (whereas the old introduction content focused on
high-level concepts like policy-decoupling, the data document, etc.)
The new introduction content provides a concise overview of OPA and
then launches into an tour of Rego (by example) that shows the core
concepts in the language. The content ends with an overview of
different ways you can interact with OPA.
The old introduction content has been moved into the Philosophy page
and the How Does OPA Work? page has been removed/replaced by the new
introduction page.
With these changes we can update the frontpage with links to core OPA
introduction and then different use cases (e.g., Kubernetes, Envoy,
etc.)
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
Any links that were caught by the link checker have been
repaired. This also standardizes some to ensure we are
always using URLs with trailing `/` when possible.
Signed-off-by: Patrick East <east.patrick@gmail.com>
With #1715 we updated opa.runtime() to include the OPA semantic
version in the output. This change extends that to include the build
commit which is useful for development purposes.
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
We no longer describe OPA as policy-enabling a service. Instead we talk about
OPA as decoupling policy from a service. This seems to be the one place we
talk about it.
Also modify the introduction to describe authentication versus authorization.
Signed-off-by: Tim Hinrichs <tim@styra.com>
The docs have grown organically and it was time for a reorganization, specifically
helping people understand at a single glance the information
that is available in the docs.
The new docs are organized as follows:
- Core docs (policy and data)
- Use-case specific docs
- Operations
- Support
As part of the reorganization, several files were renamed and/or combined.
Also made an editing pass over what was previously the user-attribute docs
and generalized them to focus on data-replication, an issue that is
now promoted to the core docs. As part of that, updated the images
and removed the old ones; new image sources are in google slides.
Tweaked the navigation bar to give more space on the left-hand column
so that more of the topics are visible without scrolling.
Signed-off-by: Tim Hinrichs <tim@styra.com>
There are a few issues with the Ceph tutorial in it's current
state. I've documented a few of them in the commit message on this
branch: https://github.com/tsandall/opa/tree/fix-ceph-authz.
Once those issues are addressed we can re-introduce the Ceph tutorial.
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
These changes update most of the docs to use live blocks. The
following pages have not been touched or updated significantly:
* Get Started - this page is based entirely on the REPL. We should
revisit the "Get Started" page once these changes have
landed. The existing page can live on as an introduction to the REPL
while the Get Started page can be tailored to live blocks.
* Ceph Authorization - this page has not been updated aside from
making the policy example use the live blocks for syntax
highlighting. We need to revisit the policy example and refactor the
tutorial a bit to emphasize the policy as opposed to the manifests
required to install.
* Terraform - this page has not been touched because @vgramer is
planning to update for Terraform v0.12. We can update this page once
those changes are in to avoid conflicts.
These changes also remove the use of non-Markdown code examples. All
the examples are inlined into Markdown now.
A few OPA deployment examples have been updated to enable the console
decision logging. This is better than the request/response debug logs.
Fixes#1650
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
The behavior has since changed and we do check for overlaps.
The warning has been updated to give advice on monitoring for errors
and to describe the somewhat racy nature of loading multiple bundles.
Signed-off-by: Patrick East <east.patrick@gmail.com>
This commit adds a postprocessor to the docs build that enables
examples to be edited and have the results show up live. See the
additions to `docs/README.md` for more about what writing these
blocks looks like or the netlify PR preview
(e.g. at `docs/edge/how-do-i-write-policies/`)
to see them in action (you'll need to disable CORS for live output).
Signed-off-by: David Boles <me@davidbol.es>
* Remove metric provider config to avoid introducing new public
interfaces. Since there is only one provider (prometheus) and it
doesn't have any configurable settings, remove the configuration
changes for now. We can always add these in the future.
* Remove dummy metric provider implementation. This isn't needed now
that we're using the metrics.Metrics interface instead of
metrics.GlobalMetrics.
* Remove metrics.GlobalMetrics in favour of metrics.Metrics. Move the
HTTP handler instrumentation interfaces into the server package to
avoid coupling the metrics package to the net/http package.
* Refactor the prometheus provider to implement the metrics.Metrics
interface. Since the prometheus registry can error on Gather()
calls, the provider has been updated to accept a logger and use ti
when the Gather() call fails. This doesn't affect any public
interfaces so it can be revisited in future if needed. Alteratnively
we could add a Gather() interface onto metrics.Metrics which could
return the error.
* Refactor status plugin to include metrics in status update by
default. Users implementing the status API are likely to need
performance metrics to gauge the OPA's health. Moreover if they are
implementing the status API it's unlikely they will want to poll the
/metrics endpoint on the OPA HTTP API (which may not even be
exposed.)
* Move the prometheus endpoint test case into the e2e package so the
server package has no dependencies on prometheus anymore.
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
Prometheus metrics can give much of insight into OPA's health.
Run-time metrics are a natural part of the application state
so having them in status update seems like a right change
that can help server understand what's going in with the OPA
instance.
The commit also encapsulates all prometheus-related code in one package
and abstracts it with generic interface so that it would be possible
to add other metrics providers
Addresses #1606
Signed-off-by: Stan Lagun <stan@styra.com>
The goal is to have the Kubernetes admission control content organized
into one section. This should make it easier to incorporate Gatekeeper
content in the future.
Since the layouts are not versioned the layout logic had to be
enhanced to filter out sections that have no content for the current
version. Doing a semantic version comparison was considered but it was
unclear how to implement that properly within the Hugo template
system. Since it's unlikely that we will want to ever display empty
sections this approach seems fine.
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
This is not complete (e.g., more detail on management APIs would be
great, detail on CLI invocation would be nice, detail on partial
evaluation would be very helpful, etc.) but it provides a starting
point.
Fixes#372
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
This commit removes the deprecated diagnostic feature from the
server. The feature has been deprecated since November 2018 and it was
essentially unused at the time so it should be safe to
remove. Removing the diagnostic support from the server saves having
to perform an extra policy evaluation in the server.
Once the buffer is removed from the runtime.Params struct the related
issue can be closed (there is still one known user of that so it has
been left intact for backwards compatibility.)
Ref #1052
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
This change brings in support for multiple bundles to be downloaded
and activated OPA.
This is enabled by using the new config option `bundles` to define
the bundles, and deprecates the older `bundle` option.
The new `bundles` keyword and structure is propagated through to the
decision logs, status API, provenance, stored manifests, etc. Check
out the doc changes for all the updated structures.
That being said any existing configuration using `bundle` will *not*
see the new structure, everything is intended to be backwards
compatible (almost to a fault).
Fixes: #721
Signed-off-by: Patrick East <east.patrick@gmail.com>
It is not very discoverable as to how the `--set` options work when
keys have `.` characters in them. This adds in a section to the config
docs on how to do it.
Signed-off-by: Patrick East <east.patrick@gmail.com>
This is a common question that comes up. Until we have a keyword that
lets users express "FOR ALL" we should have docs we can point to.
Fixes#1307
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
Clarify the requirements/caveats for using the local decision logger
and include a blurb on the decision log.
Signed-off-by: Patrick East <east.patrick@gmail.com>
These changes update the rule index to support glob.match calls. The
changes update the build step to transform glob.match(pattern,
delimiter, match) calls into ref/value pairs like equality
expressions. In addition, the build step creates a mapper function
that transforms resolved values into lookup values during traversal.
As part of these changes, the build operation has been refactored so
that most of the process is encapsulated by a new refindices struct
that's separate from the actual rule index/trie. Hopefully this makes
the code easier to follow.
The index build step for glob.match only recognizes statements where
the match operand was given as a reference (and then was rewritten by
the earlier step in the compiler.) If this is too brittle we could
revisit the build step and close over all intermediate assignments.
Fixes#1496
Signed-off-by: Torin Sandall <torinsandall@gmail.com>
Add specific example using array indexes to show what expression is
allowed and what is not explicitly.
Signed-off-by: Ken Fukuyama <kenfdev@gmail.com>
Add option to log decision logs locally. They'll get logged via
Logrus at info level.
To enable configure OPA with something like:
```
decision_logs:
console: true
```
This will work alongside remote services and plugins. It will also
log the masked events in the case a masking policy is set.
Fixes: #1334
Signed-off-by: Patrick East <east.patrick@gmail.com>
Patrick East