open-policy-agent · charlieegan3 · Jul 3, 2023 · Jun 20, 2023 · Jul 3, 2023 · Jul 3, 2023
diff --git a/docs/content/ecosystem/_index.md b/docs/content/ecosystem/_index.md
@@ -2,8 +2,18 @@
 title: "OPA Ecosystem"
 layout: ecosystem-section
 kind: support
-toc: false
 edit_link: https://github.com/open-policy-agent/opa/edit/main/docs/website/data/integrations.yaml
+categories:
+- key: rego
+  title: Rego Language
+- key: production
+  title: OPA at Scale
+- key: tool
+  title: Tool Integrations
+- key: language
+  title: Language Integrations
+- key: builtwithopa
+  title: Built with OPA
 ---
 
 Showcase of OPA integrations, use-cases, and related projects.
diff --git a/docs/content/ecosystem/external-data-realtime-push.md b/docs/content/ecosystem/external-data-realtime-push.md
@@ -0,0 +1,10 @@
+---
+title: 'External Data: Push'
+layout: ecosystem-single
+description: Manage and update external data loaded into OPA
+category: production 
+---
+
+These projects make use of OPA APIs to manage and update data in realtime.
+See [External Data: Push Data](../../external-data/#option-4-push-data) for more information
+about this functionality.
diff --git a/docs/content/ecosystem/external-data-runtime.md b/docs/content/ecosystem/external-data-runtime.md
@@ -0,0 +1,9 @@
+---
+title: 'External Data: Runtime'
+layout: ecosystem-single
+description: Load in on demand at runtime
+category: production 
+---
+
+These projects extend OPA to support the
+[pulling of data at evaluation time](../../external-data/#option-5-pull-data-during-evaluation).
diff --git a/docs/content/ecosystem/external-data.md b/docs/content/ecosystem/external-data.md
@@ -0,0 +1,10 @@
+---
+title: External Data
+layout: ecosystem-single
+description: Manage and update external data loaded into OPA
+category: production
+---
+
+These projects make use of OPA APIs to manage and update external data.
+See [External Data](../../external-data) for more information about this
+functionality.
diff --git a/docs/content/ecosystem/go-integration.md b/docs/content/ecosystem/go-integration.md
@@ -0,0 +1,8 @@
+---
+title: Go Integrations
+layout: ecosystem-single
+description: Projects using OPA as a Go module
+category: builtwithopa
+---
+
+Projects using OPA as a Go module to implement policy-based functionality.
diff --git a/docs/content/ecosystem/kubernetes.md b/docs/content/ecosystem/kubernetes.md
@@ -0,0 +1,8 @@
+---
+title: Kubernetes
+layout: ecosystem-single
+description: Integrate OPA with Kubernetes
+category: tool
+---
+
+These projects from the OPA ecosystem make it easier to use OPA in Kubernetes use cases.
diff --git a/docs/content/ecosystem/learning-rego.md b/docs/content/ecosystem/learning-rego.md
@@ -0,0 +1,8 @@
+---
+title: Learning Rego
+layout: ecosystem-single
+description: Learn and write Rego
+category: rego
+---
+
+Learn and write [Rego](../../policy-language) with these tools from the OPA Ecosystem.
diff --git a/docs/content/ecosystem/opa-bundles.md b/docs/content/ecosystem/opa-bundles.md
@@ -0,0 +1,8 @@
+---
+title: Bundles
+layout: ecosystem-single
+description: Distribute policy and data to OPA instances
+category: production
+---
+
+These projects from the OPA ecosystem make use of OPA Bundles.
diff --git a/docs/content/ecosystem/policy-testing.md b/docs/content/ecosystem/policy-testing.md
@@ -0,0 +1,9 @@
+---
+title: Policy Testing
+layout: ecosystem-single
+description: Test and validate Rego policies
+category: rego
+---
+
+These projects from the OPA ecosystem help with or support running of
+tests on [Rego](../../policy-language) code.
diff --git a/docs/content/ecosystem/rest-api-integration.md b/docs/content/ecosystem/rest-api-integration.md
@@ -0,0 +1,8 @@
+---
+title: REST API Integrations
+layout: ecosystem-single
+description: Examples of projects which integrate with the OPA REST API.
+category: builtwithopa
+---
+
+OPA’s [REST API](../../rest-api) is the foundation for many integrations. Public examples are listed below.
diff --git a/docs/content/ecosystem/terraform.md b/docs/content/ecosystem/terraform.md
@@ -0,0 +1,8 @@
+---
+title: Terraform
+layout: ecosystem-single
+description: Integrate OPA with Terraform
+category: tool
+---
+
+These projects from the OPA ecosystem integrate OPA with either Terraform source code in HCL or Terraform plans in JSON.
diff --git a/docs/content/ecosystem/wasm-integration.md b/docs/content/ecosystem/wasm-integration.md
@@ -0,0 +1,8 @@
+---
+title: Wasm Integrations
+layout: ecosystem-single
+description: Projects using the Wasm functionality of OPA.
+category: language
+---
+
+OPA’s [Wasm Functionality](../../wasm) has been used to build the following projects.
diff --git a/docs/content/external-data.md b/docs/content/external-data.md
@@ -103,6 +103,22 @@ This approach is more flexible than the JWT and `input` cases above because you
 
 The drawback is that the consistency of the data with the source of truth is worse than the `input` case and could be better or worse than the consistency for the JWT case (because JWTs only get updated on login).  One feature currently under design is a delta-based bundle protocol, which could improve the data consistency model significantly by lowering the cost of frequent updates.  But as it stands this approach is ideal when the data is relatively static and the data fits into memory.
 
+### Ecosystem Projects
+
+Loading policy and data via Bundles is an important part of the OPA API. A number of
+ecosystem projects make use of this functionality to share code and keep data
+up-to-date. 
+{{<
+  ecosystem_feature_link
+  key="opa-bundles"
+  singular_intro="There is currently 1 project"
+  singular_link="listed in the OPA Ecosystem"
+  plural_outro="which integrates with Bundles."
+  plural_intro="There are"
+  plural_link="COUNT projects"
+  plural_outro="which are listed in the OPA Ecosystem which use or work with Bundles."
+>}}
+
 ## Option 4: Push Data
 
 Another way to replicate external data in its entirety into OPA is to use OPA's API for injecting arbitrary JSON data.  You can build a replicator that pulls information out of the external data source and pushes that information in OPA through its API.  This approach is similar in most respects to the bundle API, except it lets you optimize for update latency and network traffic.
@@ -136,6 +152,20 @@ The entirety of the external data source is stored in memory, which can obviousl
 
 This approach is very similar to the bundle approach except it updates the data stored in OPA with deltas instead of an entire snapshot at a time.  Because the data is updated as deltas, this approach is well-suited for data that changes frequently.  It assumes the data can fit entirely in memory and so is well-suited to small and medium-sized data sets.
 
+### Ecosystem Projects
+
+Some OPA Ecosystem projects support pushing data into OPA.
+{{<
+ecosystem_feature_link
+key="external-data-realtime-push"
+singular_intro="There is currently 1 project"
+singular_link="listed on the OPA Ecosystem page"
+singular_outro="which implements push updates to OPA data."
+plural_intro="There are"
+plural_link="COUNT projects"
+plural_outro="listed in the OPA Ecosystem which implement push updates to OPA data."
+>}}
+
 ## Option 5: Pull Data during Evaluation
 
 OPA includes functionality for reaching out to external servers during evaluation.  This functionality handles those cases where there is too much data to synchronize into OPA, JWTs are ineffective, or policy requires information that must be as up to date as possible.
@@ -174,6 +204,20 @@ If the data is too large to fit into memory, or it changes too frequently to cac
 
 The downside to pulling data on demand is reduced performance and availability because of the network, which can be mitigated via caching.  In the `input` case, caching is under the control of the OPA-enabled service and can therefore be tailored to fit the properties of the data.  In the `http.send` case, caching is largely under the control of the remote service that sets HTTP response headers to indicate how long the response can be cached for.  It is crucial in this approach for the OPA-enabled service to handle the case when OPA returns no decision.
 
+### Ecosystem Projects
+
+Loading data at evaluation time has been an area of focus for some projects in the OPA community.  
+{{<
+  ecosystem_feature_link
+  key="external-data-runtime"
+  singular_intro="There is currently 1 project"
+  singular_link="listed on the OPA Ecosystem page"
+  singular_outro="which implements additional evaluation-time data sources."
+  plural_intro="There are"
+  plural_link="COUNT projects"
+  plural_outro="listed in the OPA Ecosystem which implement additional evaluation-time data sources."
+>}}
+
 ## Summary
 
 | Approach | Perf/Avail | Limitations | Recommended Data |
@@ -183,3 +227,7 @@ The downside to pulling data on demand is reduced performance and availability b
 | Bundle | High | Updates to policy/data at the same time.  Size an issue. | Static, medium |
 | Push | High | Control data refresh rate.  Size an issue. | Dynamic, medium |
 | Evaluation Pull | Dependent on network | Perfectly up to date.  No size limit. | Dynamic or large |
+
+## Ecosystem Projects
+
+{{< ecosystem_feature_embed key="external-data" topic="External Data" >}}
diff --git a/docs/content/integration.md b/docs/content/integration.md
@@ -167,6 +167,21 @@ Content-Type: application/json
 For another example of how to integrate with OPA via HTTP see the [HTTP
 API Authorization](../http-api-authorization) tutorial.
 
+#### Ecosystem Projects
+
+The REST API is a common way to build integrations with OPA in distributed systems.
+{{<
+  ecosystem_feature_link
+  key="rest-api-integration"
+  singular_intro="There is currently 1 project"
+  singular_link="listed in the OPA Ecosystem"
+  singular_outro="which is building on the OPA REST API."
+  plural_intro="The"
+  plural_link="COUNT projects listed in the OPA Ecosystem"
+  plural_outro="building on the OPA REST API might be good inspiration for your own integration - many are open source."
+>}}
+The [reference documentation](../rest-api) is also a good place to start.
+
 ### Integrating with the Go SDK
 
 The [SDK](https://pkg.go.dev/github.com/open-policy-agent/opa/sdk) package contains high-level APIs for embedding OPA
@@ -378,11 +393,36 @@ For more examples of embedding OPA as a library see the
 [`rego`](https://pkg.go.dev/github.com/open-policy-agent/opa/rego#pkg-examples)
 package in the Go documentation.
 
-### WebAssembly (Wasm)
+#### Ecosystem Projects
+
+The Go API is made available to allow other projects to build policy functionality into their
+applications. 
+{{<
+  ecosystem_feature_link
+  key="go-integration"
+  singular_intro="Currently 1 project"
+  singular_link="listed in the OPA Ecosystem"
+  singular_outro="is using the OPA Go API in this way."
+  plural_intro="View the"
+  plural_link="COUNT projects"
+  plural_outro="listed in the OPA Ecosystem already using the API in Go applications - many of which are open source and may serve as a good reference."
+>}}
 
-Policies can be evaluated as compiled Wasm binaries.
+### WebAssembly (Wasm)
 
-See [OPA Wasm docs](../wasm) for more details.
+Policies can be evaluated as compiled Wasm binaries. See [OPA Wasm docs](../wasm) for more details.
+
+There are a number of projects already built on OPA Wasm, 
+{{<
+  ecosystem_feature_link
+  key="wasm-integration"
+  singular_intro="including 1 project"
+  singular_link="listed in the OPA Ecosystem page."
+  singular_outro="."
+  plural_intro=" including "
+  plural_link="COUNT projects"
+  plural_outro="listed in the OPA Ecosystem page."
+>}}
 
 ### Intermediate Representation (IR)
 

diff --git a/docs/content/kubernetes-introduction.md b/docs/content/kubernetes-introduction.md
@@ -265,3 +265,10 @@ information on admission control:
 * [Dynamic Admission
   Control](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
   for details on configuring external admission controllers.
+
+## Ecosystem Projects
+
+Kubernetes is a popular integration with OPA and there are number of projects already in this space
+which might work for your use case.
+
+{{< ecosystem_feature_embed key="kubernetes" topic="Kubernetes" >}}
diff --git a/docs/content/management-decision-logs.md b/docs/content/management-decision-logs.md
@@ -295,4 +295,11 @@ OPA provides a user-specified buffer size limit in bytes, it may be difficult to
 allow the service to consume logs without being overwhelmed. The `max_decisions_per_second` config option allows users
 to set the maximum number of decision log events to buffer per second. OPA will drop events if the rate limit is exceeded.
 This option provides users more control over how OPA buffers log events and is an effective mechanism to make sure the
-service can successfully process incoming log events.
+service can successfully process incoming log events.
+
+## Ecosystem Projects
+
+Decision Logging is an important feature of OPA which supports, in particular, auditing and debugging. The following OPA
+ecosystem projects implement functionality related to Decision Logging:
+
+{{< ecosystem_feature_embed key="decision-logging" topic="Decision Logging" >}}
diff --git a/docs/content/policy-language.md b/docs/content/policy-language.md
@@ -45,6 +45,25 @@ concise than the equivalent in an imperative language.
 Like other applications which support declarative query languages, OPA is able
 to optimize queries to improve performance.
 
+## Learning Rego
+
+In while reviewing the examples below, you might find it helpful to follow along
+using the online [OPA playground](http://play.openpolicyagent.org). The
+playground also allows sharing of examples via URL which can be helpful when 
+asking questions on the [OPA Slack](https://slack.openpolicyagent.org).
+In addition to these official resources, you may also be interested to check
+out the community learning materials and tools.
+{{<
+  ecosystem_feature_link
+  key="learning-rego"
+  singular_intro="There is currently 1 project"
+  singular_link="listed in the OPA Ecosystem"
+  singular_outro="which can help you learn Rego."
+  plural_intro="These "
+  plural_link="COUNT projects"
+  plural_outro="are listed on the OPA Ecosystem page as related to learning Rego."
+>}}
+
 ## The Basics
 
 This section introduces the main aspects of Rego.
@@ -3605,6 +3624,6 @@ Unused imports | Unused [imports](../policy-language/#imports) are prohibited.
 `input` and `data` reserved keywords | `input` and `data` are reserved keywords, and may not be used as names for rules and variable assignment.                                                                                                                                                      | 1.0
 Use of deprecated built-ins | Use of deprecated functions is prohibited, and these will be removed in OPA 1.0. Deprecated built-in functions: `any`, `all`, `re_match`,  `net.cidr_overlap`, `set_diff`, `cast_array`, `cast_set`, `cast_string`, `cast_boolean`, `cast_null`, `cast_object` | 1.0
 
-# Ecosystem Language Tooling
+## Ecosystem Projects
 
-[View ecosystem projects](../ecosystem/language-tooling) which can help you write, test OPA policies in Rego.
+{{< ecosystem_feature_embed key="learning-rego" topic="learning Rego" >}}
diff --git a/docs/content/policy-testing.md b/docs/content/policy-testing.md
@@ -3,6 +3,7 @@ title: Policy Testing
 kind: documentation
 weight: 4
 restrictedtoc: true
+has_side_notes: true
 ---
 
 OPA gives you a high-level declarative language
@@ -509,3 +510,7 @@ opa test --coverage --format=json example.rego example_test.rego
   }
 }
 ```
+
+## Ecosystem Projects
+
+{{< ecosystem_feature_embed key="policy-testing" topic="Policy Testing" >}}
diff --git a/docs/content/rest-api.md b/docs/content/rest-api.md
@@ -5,7 +5,30 @@ weight: 80
 restrictedtoc: true
 ---
 
-This document is the authoritative specification of the OPA REST API.
+This document is the authoritative specification of the OPA REST API. The API can be broken down into the following
+groups:
+
+* [Policy API](#policy-api) - manage policy loaded into the OPA instance.
+* [Data API](#data-api) - evaluate rules and retrieve data.
+* [Query API](#query-api) - execute adhoc queries.
+* [Compile API](#compile-api) - access Rego's [Partial Evaluation](https://blog.openpolicyagent.org/partial-evaluation-162750eaf422) functionality.
+* [Health API](#health-api) - access instance operational health information.
+* [Config API](#config-api) - view instance configuration.
+* [Status API](#status-api) - view instance [status](../management-status) state.
+
+The REST API is a very common way to integrate with OPA.
+{{<
+  ecosystem_feature_link
+  key="rest-api-integration"
+  singular_intro="There is currently 1 project"
+  singular_link="listed in the OPA Ecosystem"
+  singular_outro="which is built on the REST API."
+  plural_intro="There are"
+  plural_link="COUNT OPA Ecosystem projects"
+  plural_outro="- many of which are open source - built on the REST API which might serve as inspiration."
+>}}
+You may also want to review the [integration documentation](../integration) for other options
+to build on OPA by embedding functionality directly into your application.
 
 ##  Policy API
 
@@ -2135,3 +2158,9 @@ OPA currently supports the following query provenance information:
 - **bundles**: A set of key-value pairs describing each bundle activated on the server. Includes
   the `revision` field which is the _revision_ string included in a .manifest file (if present)
   within a bundle
+
+## Ecosystem Projects
+
+OPA's REST API has already been used by many projects in the OPA Ecosystem to support a variety of use cases. 
+
+{{< ecosystem_feature_embed key="rest-api-integration" topic="built on the OPA REST API" >}}