docs: Add section on the OPA document model #2314
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tsandall
force-pushed
the
docs-document-model
branch
4 times, most recently
from
0f0c818 to
f47cbfd
Compare
tsandall
changed the title
tsandall
requested review from
patrick-east,
ashutosh-narkar and
timothyhinrichs
tsandall
changed the title
tsandall
dismissed stale reviews from patrick-east and ashutosh-narkar
via
0950f1b
tsandall
force-pushed
the
docs-document-model
branch
from
f47cbfd to
0950f1b
Compare
tsandall
force-pushed
the
docs-document-model
branch
5 times, most recently
from
f02a846 to
9f219f0
Compare
docs/content/philosophy.md
Outdated
| in the language. | ||
|
|
||
| Sometimes base documents need to be loaded into OPA synchronously with respect to policy |
There was a problem hiding this comment.
A sentence defining synchronous versus asynchrous would help. "Base documents are loaded at 2 different times: (i) when a piece of software asks for a decision (synchronous) and (ii) whenever the external state of the world changes and those changes need to be replicated into OPA (asynchronous).
There was a problem hiding this comment.
I'd be tempted to have 3 choices: synchronous -> input, asynchronous -> data, dynamic (http.send) -> local variables, possibly under data.
docs/content/philosophy.md
Outdated
| during policy evaluation. Similarly, policies are also cached in-memory to ensure | ||
| high-performance and and high-availability. For more information on loading external data | ||
| into OPA, including tradeoffs, see the [External Data](../external-data) page. |
There was a problem hiding this comment.
Data loaded synchronously is also cached in-memory.
When we refreshed the docs last year we removed the page titled 'how OPA works' and in the process lost the description of the OPA document model that explains the base and virtual document concepts. Since then a bunch of people have referred back to those docs after getting started. This change re-introduces the model and provides an explanation of _why_ the model exists. This change also replaces the infographic with text containing the same content as that feels a bit more inline with the rest of the page. Fixes open-policy-agent#2284 Signed-off-by: Torin Sandall <torinsandall@gmail.com>
tsandall
force-pushed
the
docs-document-model
branch
from
9f219f0 to
6bf8653
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
When we refreshed the docs last year we removed the page titled 'how
OPA works' and in the process lost the description of the OPA document
model that explains the base and virtual document concepts. Since then
a bunch of people have referred back to those docs after getting
started.
This change re-introduces the model and provides an explanation of
why the model exists.
Fixes #2284
Signed-off-by: Torin Sandall torinsandall@gmail.com