From 1c50349195dfd0aabde99f6c7ac8c6a0130dd580 Mon Sep 17 00:00:00 2001 From: Mikol Graves Date: Wed, 13 Jul 2016 17:37:59 -0700 Subject: [PATCH 1/3] Midsummer site refresh --- docs/{docs/development.md => DEVELOPMENT.md} | 0 docs/{dev => }/RELEASE.md | 0 docs/_includes/head.html | 12 - docs/_includes/icon-github.html | 1 - docs/_includes/icon-github.svg | 1 - docs/_layouts/docs.html | 46 -- docs/_sass/_base.scss | 206 ------- docs/_sass/_layout.scss | 226 ------- docs/about.md | 26 - docs/{docs/overview.svg => block-diagram.svg} | 0 docs/css/main.scss | 53 -- docs/dev/readme.txt | 2 - docs/docs/arch.md | 297 --------- docs/docs/deployment.svg | 3 - docs/docs/examples/authz.md | 287 --------- docs/docs/examples/repl.md | 225 ------- docs/docs/intro.md | 48 -- docs/index.html | 89 --- site/.gitignore | 4 + docs/dev/SITE.md => site/README.md | 19 +- .../_assets/highlight.scss | 0 site/_assets/images/benefits.svg | 1 + .../images/community-github-issues.svg | 39 ++ .../images/community-google-groups.svg | 37 ++ site/_assets/images/community-slack.svg | 39 ++ .../images}/data-model-dependencies.svg | 0 .../_assets/images}/data-model-logical.svg | 2 +- site/_assets/images/experience.svg | 1 + site/_assets/images/github-corner-right.svg | 1 + site/_assets/images/icon-download-white.svg | 1 + site/_assets/images/icon-github.svg | 1 + site/_assets/stylesheets/highlight.scss | 64 ++ site/_assets/stylesheets/reset.scss | 83 +++ site/_assets/stylesheets/style.scss | 563 ++++++++++++++++++ {docs => site}/_config.yml | 21 +- {docs => site}/_includes/footer.html | 0 site/_includes/head.html | 9 + site/_includes/nav-documentation.html | 28 + site/_includes/nav-examples.html | 22 + .../_includes/nav-main.html | 0 site/_layouts/default.html | 21 + site/_layouts/documentation.html | 25 + site/_layouts/examples.html | 25 + site/_layouts/homepage.html | 35 ++ site/community/index.md | 28 + .../how-do-i-write-policies/index.md | 538 ++++++++++------- site/documentation/how-does-opa-work/index.md | 512 ++++++++++++++++ .../what-is-policy-enablement/index.md | 51 ++ site/examples/docker-authorization/index.md | 347 +++++++++++ .../working-with-the-opa-repl/index.md | 270 +++++++++ site/get-opa/index.md | 51 ++ site/index.md | 117 ++++ 52 files changed, 2707 insertions(+), 1770 deletions(-) rename docs/{docs/development.md => DEVELOPMENT.md} (100%) rename docs/{dev => }/RELEASE.md (100%) delete mode 100644 docs/_includes/head.html delete mode 100644 docs/_includes/icon-github.html delete mode 100644 docs/_includes/icon-github.svg delete mode 100644 docs/_layouts/docs.html delete mode 100644 docs/_sass/_base.scss delete mode 100644 docs/_sass/_layout.scss delete mode 100644 docs/about.md rename docs/{docs/overview.svg => block-diagram.svg} (100%) delete mode 100644 docs/css/main.scss delete mode 100644 docs/dev/readme.txt delete mode 100644 docs/docs/arch.md delete mode 100644 docs/docs/deployment.svg delete mode 100644 docs/docs/examples/authz.md delete mode 100644 docs/docs/examples/repl.md delete mode 100644 docs/docs/intro.md delete mode 100644 docs/index.html create mode 100644 site/.gitignore rename docs/dev/SITE.md => site/README.md (60%) rename docs/_sass/_syntax-highlighting.scss => site/_assets/highlight.scss (100%) create mode 100644 site/_assets/images/benefits.svg create mode 100644 site/_assets/images/community-github-issues.svg create mode 100644 site/_assets/images/community-google-groups.svg create mode 100644 site/_assets/images/community-slack.svg rename {docs/docs => site/_assets/images}/data-model-dependencies.svg (100%) rename {docs/docs => site/_assets/images}/data-model-logical.svg (65%) create mode 100644 site/_assets/images/experience.svg create mode 100644 site/_assets/images/github-corner-right.svg create mode 100644 site/_assets/images/icon-download-white.svg create mode 100644 site/_assets/images/icon-github.svg create mode 100644 site/_assets/stylesheets/highlight.scss create mode 100644 site/_assets/stylesheets/reset.scss create mode 100644 site/_assets/stylesheets/style.scss rename {docs => site}/_config.yml (68%) rename {docs => site}/_includes/footer.html (100%) create mode 100644 site/_includes/head.html create mode 100644 site/_includes/nav-documentation.html create mode 100644 site/_includes/nav-examples.html rename docs/_includes/header.html => site/_includes/nav-main.html (100%) create mode 100644 site/_layouts/default.html create mode 100644 site/_layouts/documentation.html create mode 100644 site/_layouts/examples.html create mode 100644 site/_layouts/homepage.html create mode 100644 site/community/index.md rename docs/docs/lang.md => site/documentation/how-do-i-write-policies/index.md (66%) create mode 100644 site/documentation/how-does-opa-work/index.md create mode 100644 site/documentation/what-is-policy-enablement/index.md create mode 100644 site/examples/docker-authorization/index.md create mode 100644 site/examples/working-with-the-opa-repl/index.md create mode 100644 site/get-opa/index.md create mode 100644 site/index.md diff --git a/docs/docs/development.md b/docs/DEVELOPMENT.md similarity index 100% rename from docs/docs/development.md rename to docs/DEVELOPMENT.md diff --git a/docs/dev/RELEASE.md b/docs/RELEASE.md similarity index 100% rename from docs/dev/RELEASE.md rename to docs/RELEASE.md diff --git a/docs/_includes/head.html b/docs/_includes/head.html deleted file mode 100644 index 1598d6fe77..0000000000 --- a/docs/_includes/head.html +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - {% if page.title %}{{ page.title | escape }}{% else %}{{ site.title | escape }}{% endif %} - - - - - - diff --git a/docs/_includes/icon-github.html b/docs/_includes/icon-github.html deleted file mode 100644 index 6b4be633d6..0000000000 --- a/docs/_includes/icon-github.html +++ /dev/null @@ -1 +0,0 @@ -{% include icon-github.svg %}{{include.username}}/{{ include.repo }} diff --git a/docs/_includes/icon-github.svg b/docs/_includes/icon-github.svg deleted file mode 100644 index 4422c4f5dc..0000000000 --- a/docs/_includes/icon-github.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/_layouts/docs.html b/docs/_layouts/docs.html deleted file mode 100644 index 8c95c8e3e2..0000000000 --- a/docs/_layouts/docs.html +++ /dev/null @@ -1,46 +0,0 @@ ---- -layout: default ---- -
- -
-
    - {% assign pages = site.pages | sort:"sort_order" %} - {% for page in pages %} - {% if page.section == 'docs' %} -
  • - {{page.title}} -
    • -
    - {% endif %} - {% endfor %} -
  • References
    • -
      - {% assign pages = site.pages | sort:"sort_order" %} - {% for page in pages %} - {% if page.section == 'references' %} -
    • - {{page.title}} -
      • - {% endif %} - {% endfor %} -
    -
  • Examples
    • -
      - {% assign pages = site.pages | sort:"sort_order" %} - {% for page in pages %} - {% if page.section == 'examples' %} -
    • - {{page.title}} -
      • - {% endif %} - {% endfor %} -
    -
-
- -
- {{ content }} -
- -
diff --git a/docs/_sass/_base.scss b/docs/_sass/_base.scss deleted file mode 100644 index 5be22fdeae..0000000000 --- a/docs/_sass/_base.scss +++ /dev/null @@ -1,206 +0,0 @@ -/** - * Reset some basic elements - */ -body, h1, h2, h3, h4, h5, h6, -p, blockquote, pre, hr, -dl, dd, ol, ul, figure { - margin: 0; - padding: 0; -} - - - -/** - * Basic styling - */ -body { - font: $base-font-weight #{$base-font-size}/#{$base-line-height} $base-font-family; - color: $text-color; - background-color: $background-color; - -webkit-text-size-adjust: 100%; - -webkit-font-feature-settings: "kern" 1; - -moz-font-feature-settings: "kern" 1; - -o-font-feature-settings: "kern" 1; - font-feature-settings: "kern" 1; - font-kerning: normal; -} - - - -/** - * Set `margin-bottom` to maintain vertical rhythm - */ -h1, h2, h3, h4, h5, h6, -p, blockquote, pre, -ul, ol, dl, figure, -%vertical-rhythm { - margin-bottom: $spacing-unit / 2; -} - - - -/** - * Images - */ -img { - max-width: 100%; - vertical-align: middle; -} - - - -/** - * Figures - */ -figure > img { - display: block; -} - -figcaption { - font-size: $small-font-size; -} - - - -/** - * Lists - */ -ul, ol { - margin-left: $spacing-unit; -} - -li { - > ul, - > ol { - margin-bottom: 0; - } -} - - - -/** - * Headings - */ -h1, h2, h3, h4, h5, h6 { - font-weight: $base-font-weight; -} - - - -/** - * Links - */ -a { - color: $brand-color; - text-decoration: none; - - &:visited { - color: darken($brand-color, 15%); - } - - &:hover { - color: $text-color; - text-decoration: underline; - } -} - - - -/** - * Blockquotes - */ -blockquote { - color: $grey-color; - border-left: 4px solid $grey-color-light; - padding-left: $spacing-unit / 2; - font-size: 18px; - letter-spacing: -1px; - font-style: italic; - - > :last-child { - margin-bottom: 0; - } -} - - - -/** - * Code formatting - */ -pre, -code { - font-size: 15px; - border: 1px solid $grey-color-light; - border-radius: 3px; - background-color: #eef; -} - -code { - padding: 1px 5px; -} - -pre { - padding: 8px 12px; - overflow-x: auto; - - > code { - border: 0; - padding-right: 0; - padding-left: 0; - } -} - - - -/** - * Wrapper - */ -.wrapper { - max-width: -webkit-calc(#{$content-width} - (#{$spacing-unit} * 2)); - max-width: calc(#{$content-width} - (#{$spacing-unit} * 2)); - margin-right: auto; - margin-left: auto; - padding-right: $spacing-unit; - padding-left: $spacing-unit; - @extend %clearfix; - - @include media-query($on-laptop) { - max-width: -webkit-calc(#{$content-width} - (#{$spacing-unit})); - max-width: calc(#{$content-width} - (#{$spacing-unit})); - padding-right: $spacing-unit / 2; - padding-left: $spacing-unit / 2; - } -} - - - -/** - * Clearfix - */ -%clearfix { - - &:after { - content: ""; - display: table; - clear: both; - } -} - - - -/** - * Icons - */ -.icon { - - > svg { - display: inline-block; - width: 16px; - height: 16px; - vertical-align: middle; - - path { - fill: $grey-color; - } - } -} \ No newline at end of file diff --git a/docs/_sass/_layout.scss b/docs/_sass/_layout.scss deleted file mode 100644 index e505909c19..0000000000 --- a/docs/_sass/_layout.scss +++ /dev/null @@ -1,226 +0,0 @@ -/** - * Site header - */ -.site-header { - border-top: 5px solid $grey-color-dark; - border-bottom: 1px solid $grey-color-light; - min-height: 56px; - - // Positioning context for the mobile navigation icon - position: relative; -} - -.site-title { - font-size: 26px; - font-weight: 300; - line-height: 56px; - letter-spacing: -1px; - margin-bottom: 0; - float: left; - - &, - &:visited { - color: $grey-color-dark; - } -} - -.site-nav { - float: right; - line-height: 56px; - - .menu-icon { - display: none; - } - - .page-link { - color: $text-color; - line-height: $base-line-height; - - // Gaps between nav items, but not on the last one - &:not(:last-child) { - margin-right: 20px; - } - } - - @include media-query($on-palm) { - position: absolute; - top: 9px; - right: $spacing-unit / 2; - background-color: $background-color; - border: 1px solid $grey-color-light; - border-radius: 5px; - text-align: right; - - .menu-icon { - display: block; - float: right; - width: 36px; - height: 26px; - line-height: 0; - padding-top: 10px; - text-align: center; - - > svg { - width: 18px; - height: 15px; - - path { - fill: $grey-color-dark; - } - } - } - - .trigger { - clear: both; - display: none; - } - - &:hover .trigger { - display: block; - padding-bottom: 5px; - } - - .page-link { - display: block; - padding: 5px 10px; - - &:not(:last-child) { - margin-right: 0; - } - margin-left: 20px; - } - } -} - - - -/** - * Site footer - */ -.site-footer { - border-top: 1px solid $grey-color-light; - padding: $spacing-unit 0; -} - -.footer-heading { - font-size: 18px; - margin-bottom: $spacing-unit / 2; -} - -.contact-list, -.social-media-list { - list-style: none; - margin-left: 0; -} - -.footer-col-wrapper { - font-size: 15px; - color: $grey-color; - margin-left: -$spacing-unit / 2; - @extend %clearfix; -} - -.footer-col { - float: left; - margin-bottom: $spacing-unit / 2; - padding-left: $spacing-unit / 2; -} - -.footer-col-1 { - width: -webkit-calc(35% - (#{$spacing-unit} / 2)); - width: calc(35% - (#{$spacing-unit} / 2)); -} - -.footer-col-2 { - width: -webkit-calc(65% - (#{$spacing-unit} / 2)); - width: calc(65% - (#{$spacing-unit} / 2)); -} - -// .footer-col-3 { -// width: -webkit-calc(45% - (#{$spacing-unit} / 2)); -// width: calc(45% - (#{$spacing-unit} / 2)); -// } - -@include media-query($on-laptop) { - .footer-col-1, - .footer-col-2 { - width: -webkit-calc(100% - (#{$spacing-unit} / 2)); - width: calc(100% - (#{$spacing-unit} / 2)); - } - - // .footer-col-3 { - // width: -webkit-calc(100% - (#{$spacing-unit} / 2)); - // width: calc(100% - (#{$spacing-unit} / 2)); - // } -} - -@include media-query($on-palm) { - .footer-col { - float: none; - width: -webkit-calc(100% - (#{$spacing-unit} / 2)); - width: calc(100% - (#{$spacing-unit} / 2)); - } -} - - - -/** - * Page content - */ - -.page-content { - padding: $spacing-unit 0; -} - -.page-heading { - font-size: 20px; -} - -.post-list { - margin-left: 0; - list-style: none; - - > li { - margin-bottom: $spacing-unit; - } -} - -.post-meta { - font-size: $small-font-size; - color: $grey-color; -} - -.post-link { - display: block; - font-size: 24px; -} - - -/** - * Features section in index.html. - */ - - .col { - float: left; - width: 30%; - padding: 1%; - } - - .features-grid:after { - content: ""; - display: table; - clear: both; - } - - /** - * Docs pages, i.e., everything under /docs. - */ -.docs-nav { - float: left; - width: 25%; -} - -.docs-content { - float: left; - width: 75%; -} diff --git a/docs/about.md b/docs/about.md deleted file mode 100644 index eb183144ac..0000000000 --- a/docs/about.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: default -title: About -header_title: About -show_in_header: true ---- - -About -===== - -The Open Policy Agent (OPA) project is under active development. - -For information on contributing to OPA, see the [CONTRIBUTING.md](https://github.com/open-policy-agent/opa/blob/master/CONTRIBUTING.md) file in the repository. - -Contact -------- - -- Bugs: [Github Issues](https://github.com/open-policy-agent/opa/issues) -- Features: [Github Issues](https://github.com/open-policy-agent/opa/issues) -- Discussions: [Google Groups](https://groups.google.com/forum/?hl=en#!forum/open-policy-agent) - -Project Information -------------------- - -- License: [Apache Version 2.0](https://raw.githubusercontent.com/open-policy-agent/opa/master/LICENSE) -- Continuous Integration: [![Build Status](https://travis-ci.org/open-policy-agent/opa.svg?branch=master)](https://travis-ci.org/open-policy-agent/opa) diff --git a/docs/docs/overview.svg b/docs/block-diagram.svg similarity index 100% rename from docs/docs/overview.svg rename to docs/block-diagram.svg diff --git a/docs/css/main.scss b/docs/css/main.scss deleted file mode 100644 index f2e566e2a1..0000000000 --- a/docs/css/main.scss +++ /dev/null @@ -1,53 +0,0 @@ ---- -# Only the main Sass file needs front matter (the dashes are enough) ---- -@charset "utf-8"; - - - -// Our variables -$base-font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; -$base-font-size: 16px; -$base-font-weight: 400; -$small-font-size: $base-font-size * 0.875; -$base-line-height: 1.5; - -$spacing-unit: 30px; - -$text-color: #111; -$background-color: #fdfdfd; -$brand-color: #2a7ae2; - -$grey-color: #828282; -$grey-color-light: lighten($grey-color, 40%); -$grey-color-dark: darken($grey-color, 25%); - -// Width of the content area -$content-width: 800px; - -$on-palm: 600px; -$on-laptop: 800px; - - - -// Use media queries like this: -// @include media-query($on-palm) { -// .wrapper { -// padding-right: $spacing-unit / 2; -// padding-left: $spacing-unit / 2; -// } -// } -@mixin media-query($device) { - @media screen and (max-width: $device) { - @content; - } -} - - - -// Import partials from `sass_dir` (defaults to `_sass`) -@import - "base", - "layout", - "syntax-highlighting" -; diff --git a/docs/dev/readme.txt b/docs/dev/readme.txt deleted file mode 100644 index ad803dfcf2..0000000000 --- a/docs/dev/readme.txt +++ /dev/null @@ -1,2 +0,0 @@ -This directory contains internal documentation that is not included -on the site. \ No newline at end of file diff --git a/docs/docs/arch.md b/docs/docs/arch.md deleted file mode 100644 index 18b223883a..0000000000 --- a/docs/docs/arch.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -layout: docs -title: Architecture -section: references -sort_order: 2 ---- - -Architecture ------------- - -OPA provides an open source policy engine that can be used to policy enable applications. Policy enabling applications decouples the policy that governs how applications behave from the implementation of those applications. This allows administrators to create and manage policy without requiring changes to the application. This eases some of the challenges of maintaining applications in complex modern deployment environments. - -Because policies are defined declaratively and outside the application, administrators and other developers can more readily understand the policies that govern how the application must behave and are empowered to safely and efficiently make changes to policy. - -OPA is purpose built for modern deployment environments and can be integrated with various types of applications to provide rich policy control over various functions such as: - -- API authorization -- VM and container placement -- Auto-scaling and auto-healing clusters -- CI/CD pipeline gating -- Network ACLs -- Feature flags - -This document describes the main concepts in OPA. After reading this document you should have a better idea of how OPA is deployed and interacted with by applications and users. - -Requirements ------------- - -Before diving into the concepts behind OPA, it is useful to review the requirements placed on a policy engine to successfully policy enable applications. - -1. **The policy definitions must be decoupled from the application's implementation.** - - Policy authors must be empowered to define and manage policy without requiring changes to the application which necessitate costly development, testing, and deployment cycles. - -1. **The policy definitions must be accessible to administrators and other developers.** - - Policy must be readily understood by administrators and other developers. In some cases, policy definitions also need to be understood by non-technical team members. Furthermore, administrators and other developers must be empowered to safely modify policy. - -1. **The engine must be highly available.** - - Applications must be able to treat policy engine downtime as an extremely rare event (which likely requires manual intervention). The decision about what to do when the policy engine is unavailable is itself a policy question. It would be counter productive to the goals of policy enablement to re-implement policy decisions in the application to deal with policy engine downtime. - -1. **The engine must introduce minimal latency when evaluating policy.** - - Applications must be able to assume that the performance cost of decoupling the policy implementation from the application is negligible. If the performance cost of doing so is too high, applications will not use the engine. - -1. **The engine must integrate with applications written in any programming language.** - - Applications must not have to be developed using a specific programming language in order to benefit from the engine. If the cost of integrating with the engine involves developing the application in a specific programming language, far fewer applications will be able to use the engine. - -1. **The engine must easily ingest the state of world that is relevant to policy.** - - Applications must be able to leverage their respective programming language ecosystems to push data into the policy engine. Furthermore, the process for reading and writing data stored in the policy engine must be as simple as possible. - -These core requirements capture the guiding principles behind the concepts and design of OPA. - -Overview --------- - -Conceptually, OPA is a collection of algorithms that answer questions about policy. - - -At a high level, using OPA involves: - -- Deploying OPA on servers alongside applications. -- Writing policies a declarative language ("Rego") and loading them into OPA. -- Pushing application state that is relevant to policy into OPA. -- Executing queries via OPA's APIs to answer questions about operations governed by policy. -- Reacting to notifications delivered by OPA when policy is violated. - -Deployment ----------- - -In order to support arbitrary languages, frameworks and runtimes, OPA is deployed as a host-local daemon ("opad") alongside applications. OPA can be deployed directly on hosts as an operating system daemon or in a container. - -Deploying OPA as a host-local daemon helps ensure low latency transactions and high availability (through fate sharing) of the policy engine. If OPA is deployed on a separate server, significant consideration must be given to ensure that hardware failures and network partitions do not result in downtime of the policy engine. - -When OPA is started for the first time it contains no policies or data. Applications or deployment automation may load policies into OPA at deploy time and update policies during upgrades. Administrators can manually add, remove, and change policies as needed. - -Applications interact with OPA via HTTP. - - - -APIs ----- - -OPA exposes its APIs over HTTP and uses JSON as the default interchange format. The APIs are RESTful with the exception of certain streaming operations. HTTP and JSON are used because they are well supported in most application development languages and provide a low barrier to integration. - -### Policy API - -OPA's Policy API exposes CRUD operations on policies within OPA. Applications and administrators can use the Policy API to manage policies. - -For example, the request below creates a policy named "example-policy": - -``` -PUT /v1/policies/example-policy -Content-Type: text/plain - -package opa.examples - -violations[server] :- - server = data.servers[_], - server.protocols[_] = "http", - server.ports[_] = data.ports[i].id, - data.ports[i].networks[_] = data.networks[j].id, - data.networks[j].public = true -``` - -Policy names are only used to identify policies for management purposes. Policy names are not used in policy definitions or when issuing requests against the Data API. - -### Data API - -In order to evaluate policy and compute violations, OPA needs to have access to the state of the world which is relevant to policy. OPA's Data API deals with data from applications or the environment that is relevant to policy. - -Applications use the Data API to push state relevant to policy into OPA. Applications are responsible for updating the relevant data stored in OPA when state changes. - -For example, an application can push a list of servers into OPA by issuing an HTTP PATCH on /v1/data/servers: - -``` -PATCH /v1/data/servers HTTP/1.1 -Content-Type: application/json-patch+json - -[ - { - "op": "add", - "path": "-", - "value": {"id": "s1", "name": "app", "protocols": ["http", "https", "ssh"], "ports": ["p1", "p2", "p3"]} - }, - { - "op": "add", - "path": "-", - "value": {"id": "s2", "name": "db", "protocols": ["mysql"], "ports": ["p3"]} - }, - { - "op": "add", - "path": "-", - "value": {"id": "s3", "name": "cache", "protocols": ["memcache"], "ports": ["p3"]} - }, - { - "op": "add", - "path": "-", - "value": {"id": "s4", "name": "dev", "protocols": ["http", "https", "ssh"], "ports": ["p1", "p2"]} - } -] -``` - -Conceptually, all data stored in OPA exists within a single document ("data"). - -Applications execute queries when handling operations that are governed by policy. The query response tells the application what to do with the operation, e.g., reject the API call or place the VM on a specific host. Queries are executed via the Data API by performing a GET on the appropriate path. See the [Policies](#policies) section for examples. - -Queries can also be performed against data pushed into OPA. For example, the request below queries for the "servers" added above. - -``` -GET /v1/data/servers HTTP/1.1 -``` - -The response: - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -[ - {"id": "s1", "name": "app", "protocols": ["http", "https", "ssh"], "ports": ["p1", "p2", "p3"]}, - {"id": "s2", "name": "db", "protocols": ["mysql"], "ports": ["p3"]}, - {"id": "s3", "name": "cache", "protocols": ["memcache"], "ports": ["p3"]}, - {"id": "s4", "name": "dev", "protocols": ["http"], "ports": ["p1", "p2"]} -] -``` - -### Triggers - -Applications can register for asynchronous notifications when policy is violated. This allows applications to take corrective action when the system exits the expected state. - -For example, to receive notifications when services should be migrated to a new host, the application responsible for service deployment would create a rule which asserts that running services must be placed on a host which is not in the "terminated" state. If a host was shutdown unexpectedly, the system would notify OPA and the host state (stored in OPA) would be updated. OPA will detect that a rule has been violated and deliver a notification to the service deployment application (which can handle the event by redeploying the service on a running host.) - -### Transactions - -OPA exposes transactional APIs to operate on consistent snapshots of data stored in OPA. For example, when deploying a new VM, the application would open a transaction and perform the following steps: - -1. Query OPA for a list of hosts where the VM can be deployed. -2. Choose a host from the list and deploy the VM. -3. Push new data to OPA to reflect that the VM has been deployed. -4. Close the transaction. - -Lastly, policy writers can use OPA's APIs to obtain detailed explanations of query processing to understand why queries are returning specific results. This is useful for debugging queries. - -Data Model ----------- - -OPA is designed to support document-oriented models such as JSON. Documents consist of scalars (i.e., booleans, strings, numbers, and null) and collections (i.e., objects, arrays, and sets). The document model was selected for OPA because of its prevalence in modern application stacks. For example, most applications today expose APIs which produce and consume JSON and many modern applications rely on document-oriented databases or document support in existing relational databases. - -Conceptually, there are two kinds of documents in OPA: - -- **Base documents** representing application state relevant to policy. -- **Virtual documents** representing higher level information defined by policies. - -**Base documents** represent the raw information relevant to policy that is pushed by applications integrated with OPA. Base documents are stored in-memory and can be written to disk for resilience. - -**Virtual documents** are defined by rules inside policies. OPA computes the contents of virtual documents when callers execute queries against rules or when dependant documents are modified. Virtual documents are defined in terms of base documents and other virtual documents. Policy authors can use virtual documents to define abstractions which are useful for expressing high level policy and insulating policy from schema changes in low level data. - - - -When defining policies, rules are written which contain expressions that reference documents. The language that rules are written in ("Rego") lets you reference base documents and virtual documents in exactly the same way. - - - - Policies --------------------------------- - -Policies are defined in OPA's native query language: Rego. - -Rego is a declarative language based on [Datalog](https://en.wikipedia.org/wiki/Datalog). Rego allows policy writers to define modules which contain rules. Rules contain expressions which assert facts about the expected state of documents stored in OPA. The documents referenced in rules may be base documents pushed by applications integrated with OPA or virtual documents defined by other rules. - -To support document-oriented models such as JSON, Rego has rich support for referencing nested documents (i.e., documents inside arrays or objects). The syntax for referencing nested documents is based on dictionary and array access in languages like Python as well as JSON Path. - -Let's look at an example. - -Assume we have the following data stored in OPA: - -``` -GET /v1/data HTTP/1.1 -``` - -The response: - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "servers": [ - {"id": "s1", "name": "app", "protocols": ["https", "ssh"], "ports": ["p1", "p2", "p3"]}, - {"id": "s2", "name": "db", "protocols": ["mysql"], "ports": ["p3"]}, - {"id": "s3", "name": "cache", "protocols": ["memcache", "http"], "ports": ["p3"]}, - {"id": "s4", "name": "dev", "protocols": ["http"], "ports": ["p1", "p2"]} - ], - "networks": [ - {"id": "n1", "public": false}, - {"id": "n2", "public": false}, - {"id": "n3", "public": true} - ], - "ports": [ - {"id": "p1", "networks": ["n1"]}, - {"id": "p2", "networks": ["n3"]}, - {"id": "p3", "networks": ["n2"]} - ] -} -``` - -We can write a rule which enumerates servers that expose HTTP (but not HTTPS) and are connected to public networks. These represent violations of policy. - -```rego -package opa.example # this policy belongs the opa.example package - -import data.servers # import the data.servers document to refer to it as "servers" instead of "data.servers" -import data.networks # same but for data.networks -import data.ports # same but for data.ports - -violations[server] :- # a server exists in the violations set if: - server = servers[_], # the server exists in the servers collection - server.protocols[_] = "http", # and the server has http in its protocols collection - public_servers[server] # and the server exists in the public_servers set - -public_servers[server] :- # a server exists in the public_servers set if: - server = servers[_], # the server exists in the servers collection - server.ports[_] = ports[i].id, # and the server is connected to a port in the ports collection - ports[i].networks[_] = networks[j].id, # and the port is connected to a network in the networks collection - networks[j].public = true # and the network is public -``` - -The key aspects of Rego are illustrated by this example: - -- Rules define the content of virtual documents. In this case, we create two virtual documents: `violations` and `public_servers`. - -- Rules consist of assertions against data stored in OPA. In this case the assertions are expressions which test for equality and membership of `servers`, `networks`, and `ports` documents. - -- Expressions can referenced nested documents, e.g., `ports[i].networks[_]` references the network IDs stored in an array on each port document. - -- Expressions can reference elements in a collection using the `[_]` and `[]` syntax. When this is done, OPA knows to iterate over elements of the collection when processing queries. - -If we query for the document produced by this rule, we receive an array of servers that expose an HTTP server and are connected to a public network: - -``` -GET /v1/data/opa/examples/violations HTTP/1.1 -``` - -The response: - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -[ - {"id": "s4", "name": "dev", "protocols": ["http"], "ports": ["p2"]} -] -``` diff --git a/docs/docs/deployment.svg b/docs/docs/deployment.svg deleted file mode 100644 index b4ac3a5277..0000000000 --- a/docs/docs/deployment.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - Produced by OmniGraffle 6.5 2016-03-18 04:17:26 +0000DeploymentLayer 1serveropadAPPAPPappprocessIPC (http) diff --git a/docs/docs/examples/authz.md b/docs/docs/examples/authz.md deleted file mode 100644 index 76e7a63790..0000000000 --- a/docs/docs/examples/authz.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -layout: docs -title: Authorization -section: examples -sort_order: 1000 ---- - -Authorization -------------- - -This example helps you get started with OPA and shows how you can start policy enabling an existing -app or service. This example introduces core concepts in OPA including the language used to define policies. - -> Policy enabling an application decouples the policy implementation from the business logic so that administrators can define policy without changing the application while still keeping up with the size, complexity, and dynamic nature of modern applications. - -In this example, we will write policies to authorize access to Docker. There are many examples of policies around access control. For demonstration purposes, we want to prevent the following: - -- Containers with insecure configurations. -- Users modifying the system without sufficient read+write access. - -There are two key ideas that this example illustrates: - -1. The policy definition is decoupled from the implementation of the app (in this case Docker). The administrator is empowered to define and manage policies without requiring changes to any of the apps. - -1. Both the data relevant to policy and the policy definitions themselves can change rapidly. - -Once you finish this example, you will be familiar with: - -- Running OPA as a server/daemon. -- Loading policy definitions and data via the REST APIs. -- Querying data via the REST APIs. - -You will also be introduced to the language used to write policies in OPA: [Rego](/docs/lang.html). - -Prerequisites -============= - -The example has been tested on the following platforms: - -- Ubuntu 16.04 (64-bit) - -If you are using a different distro, OS, or architecture the steps will be the same however there will be slight differences in the commands you need to run. - -- This example requires Docker Engine 1.11 or newer to be installed on your machine. - -- This examples requires that you have root or sudo access on your machine. - -Steps -===== - -1. Create a directory that OPA can store policy definitions in: - - mkdir -p policies - -1. Download the latest version of OPA: - - curl -L https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_linux_amd64 > opa - chmod u+x opa - -1. Run OPA in server mode with logging enabled: - - ./opa run -s --alsologtostderr 1 --v 2 --policy-dir policies - - OPA will run until it receives a signal to stop. Open another terminal to continue with the rest of the example. - -1. Download the [open-policy-agent/docker-authz-plugin](https://github.com/open-policy-agent/docker-authz-plugin) executable from GitHub: - - curl -L https://github.com/open-policy-agent/docker-authz-plugin/releases/download/v0.1.0-rc1/docker-authz-plugin_linux_amd64 > docker-authz-plugin - chmod u+x docker-authz-plugin - - The open-policy-agent/docker-authz-plugin repository hosts a small [Docker Authorization Plugin](https://docs.docker.com/engine/extend/plugins_authorization/). - Docker's authorization plugin system allows an external process to receive all requests sent to the Docker daemon. The - authorization plugin replies, instructing the Docker daemon to allow or reject the request. - -1. Create an empty policy definition that will allow all requests: - - cat >example.rego < This step requires sudo access because the Docker plugin framework will attempt to update the Docker daemon configuration. - If you run without sudo you may encounter a permission error. - -1. Update Docker's configuration to include the following command line argument: - - --authorization-plugin=docker-authz-plugin - - On Ubuntu 16.04 with systemd, this can be done as follows (requires root): - - sudo mkdir -p /etc/systemd/system/docker.service.d - sudo tee -a /etc/systemd/system/docker.service.d/override.conf > /dev/null <example.rego <example.rego <~/.docker/config.json <users.json <example.rego < ~/.docker/config.json < true - true - > 3.14 - 3.14 - > ["hello", "world"] - [ - "hello", - "world" - ] - - You can also test simple boolean expressions: - - > true = false - false - > 3.14 > 3 - true - > "hello" != "goodbye" - true - - Most REPLs let you define variables that you can reference later on. OPA allows you to do something similiar. For example, we can define a "pi" constant as follows: - - > pi = 3.14 - - Once "pi" is defined, you query for the value and write expressions in terms of it: - - > pi - 3.14 - > pi > 3 - true - - One thing to watch out for in the REPL is that = is used both for assigning variables values and for testing the value of variables. For example p = q sometimes assigns p the value of q and sometimes checks if the values of p and q are the same. The REPL decides between assignment and test based on whether p already has a value or not. If p has a value, p = q is a test (returning true or false), and if p has no value p = q is an assignment. To unset a value for a variable, use the 'unset' command. (This ambiguity is only really an issue in the REPL--when writing policy the duality of = is actually beneficial.) - - > pi = 3 - false - > unset pi - > pi = 3 - > pi - 3 - - In addition to running queries, the REPL also lets you define rules: - - > p[x] :- a = [1,2,3,4], a[x] - > p[x], x > 1 - +---+ - | x | - +---+ - | 2 | - | 3 | - +---+ - - The rule above defines a set of values that are the indices of elements in the array "a". - - When you enter expressions into the REPL, you are effectively running *queries* against OPA. The REPL output shows the values of variables in the expression that make the query **true**. If there is no set of variables that would make the query true, the REPL prints **false**. If there are no variables in the query and the query evaluates successfully, then the REPL just prints **true**. - - Quit out of the REPL by pressing Control-C or typing "exit": - - > exit - Exiting - -1. The REPL can also take policies and data as input. Let's define a bit of JSON data that will be used in the example: - - cat >data.json <example.rego < data.servers[_].id - +--------------------+ - | data.servers[_].id | - +--------------------+ - | "s1" | - | "s2" | - | "s3" | - | "s4" | - +--------------------+ - > data.opa.example.public_servers[x] - +-------------------------------------------------------------------------------+ - | x | - +-------------------------------------------------------------------------------+ - | {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} | - | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | - +-------------------------------------------------------------------------------+ - - One powerful thing about Rego and the REPL is that you can run queries using the same syntax that you would use to lookup values. - - For example if `i` has value 0 then `data.servers[i]` returns the first value in the `data.servers` array: - - > i = 0 - > data.servers[i] - { - "id": "s1", - "name": "app", - "ports": [ - "p1", - "p2", - "p3" - ], - "protocols": [ - "https", - "ssh" - ] - } - - That same expression `data.servers[i]` when `i` has no value defines a query that returns all the values of `i` and `data.servers[i]`: - - > unset i - > data.servers[i] - +---+-------------------------------------------------------------------------------+ - | i | data.servers[i] | - +---+-------------------------------------------------------------------------------+ - | 0 | {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} | - | 1 | {"id":"s2","name":"db","ports":["p3"],"protocols":["mysql"]} | - | 2 | {"id":"s3","name":"cache","ports":["p3"],"protocols":["memcache"]} | - | 3 | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | - +---+-------------------------------------------------------------------------------+ - -1. The REPL also understands the [Import and Package](/docs/lang.html#modules) directives. - - > import data.servers - > servers[i].ports[_] = "p2", servers[i].id = id - +---+------+ - | i | id | - +---+------+ - | 0 | "s1" | - | 3 | "s4" | - +---+------+ - > package opa.example - > public_servers[x], x.protocols[_] = "http" - +-------------------------------------------------------------------+ - | x | - +-------------------------------------------------------------------+ - | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | - +-------------------------------------------------------------------+ - -1. Finally, we can define a rule to identify servers in violation of our security policy: - - > import data.servers - > violations[s] :- - s = servers[_], - s.protocols[_] = "http", - public_servers[s] - > violations[server] - +-------------------------------------------------------------------+ - | server | - +-------------------------------------------------------------------+ - | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | - +-------------------------------------------------------------------+ - - > The REPL will accept multi-line input. The REPL prompt will change to indicate that it's accepting multi-line input. \ No newline at end of file diff --git a/docs/docs/intro.md b/docs/docs/intro.md deleted file mode 100644 index 84678847d5..0000000000 --- a/docs/docs/intro.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: docs -header_title: Docs -title: Introduction -section: docs -show_in_header: true -sort_order: 1 ---- - -Introduction -============ - -Policy defines expected behavior in response to specific events within an application. - -There are many examples of functionality within applications which can benefit from rich policy control, e.g, API authorization, VM and container placement, auto-scaling, auto-healing, etc. - -The approach to policy can vary greatly within and across applications. For example, policy is often written in natural language (English), stored in documents such as wiki pages, and enforced manually by the administrators of the the application. - -When the cost of manually maintaining and enforcing policy is too high, policy is often defined in way that computers can understand: the application's implementation is updated to include the definition of policy and the means for enforcing it. Because most applications are implemented in **imperative languages** (such as Java or Python) the policy definition tends to focus on *how* the policy is enforced rather than *what* the expected behavior or state should be. This makes it hard for people unfamiliar with the application's implementation to know what the expected behavior or state should be. Furthermore, because policy is defined in the application's implementation, it is hard to adapt the policy without rebuilding, retesting, and redeploying the application. Deploy-time configuration may address this to some extent but is often incomplete or too course-grained. - -A better approach is to define policy in a **declarative language** which can be understood by a computer. By using a declarative language, the policy definition can focus on *what* the expected behavior or state should be. This approach decouples policy from the application's implementation and lifecycle so that policy can be updated independently. When policy is defined this way, it can be readily reused in multiple systems. Finally, this approach to policy enables various features such as conflict detection, change tracking and access control independent from the application's source, sharing and re-use of policy, visualization, etc. - -What is Policy Enabling? -======================== - -Policy enabling an application decouples the policy implementation from the business logic so that administrators can define policy without changing the application while still keeping up with the size, complexity, and dynamic nature of modern applications. - -Policy enabling an application involves providing policy statements to an engine and then integrating the application with the engine to provide answers to questions such as: - -- Can a specific operation be performed? -- What options are available for some operation? -- What policy violations currently exist? - -To answer questions like these, policies must be written in a declarative language and then compiled and executed by a policy engine that knows about the state of the world (which is relevant to policy). - -What does OPA provide? -====================== - -OPA provides an open source policy engine that simplifies the task of policy enabling applications. - -OPA exposes several APIs to simplify integration: - -- Query APIs with rich support for accessing stored data. -- Simple CRUD APIs to manage policies and data. -- Transactional APIs to operate on consistent snapshots of data. -- Asynchronous APIs to register for notification when policy is violated. - -OPA's policy engine supports a purpose built declarative language for policy. Developers do not have to design a policy language, build a compiler or interpreter, or implement other language analysis tools to policy enable their applications. diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 853fa0f807..0000000000 --- a/docs/index.html +++ /dev/null @@ -1,89 +0,0 @@ ---- -layout: default ---- -
-

- The Open Policy Agent (OPA) is an open source project that helps policy enable your - application. By integrating with OPA, your application's operators will be empowered to - manage the size, complexity, and scale of modern deployments. -

-

Get OPA

- Latest binary (Linux/64-bit):

- 
-curl -L https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_linux_amd64 > opa
-chmod u+x opa
-./opa version
-
- Latest binary (Mac OSX/64-bit):

- 
-curl -L https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_darwin_amd64 > opa
-chmod u+x opa
-./opa version
-
- From source (requires Go):

- 
-git clone https://github.com/open-policy-agent/opa.git $GOPATH/src/github.com/open-policy-agent/opa
-cd $GOPATH/src/github.com/open-policy-agent/opa
-make deps
-make
-./opa version
-
-
-

Features

-
-
-
-

Declarative Language

-

- OPA features a purpose-built declarative language for describing the expected - state of your application. Policies written in Rego are readily understood - and easy to maintain. -

-
-
-

Zero Dependencies

-

- There are zero deployment dependencies in OPA. Furthermore, OPA is designed - around the fate-sharing philosophy for highly available systems. -

-
-
-

Language Agnostic

-

- OPA exposes RESTful APIs for managing policy modules and state relevant to policy - enforcement. The APIs produce and consume JSON data and are accessed via HTTP. -

-
-
-

Low Latency

-

- OPA's policy engine is designed from scratch with latency sensitive applications in mind. - OPA introduces as little latency as possible while still decoupling policy definitions - from application business logic. -

-
-
-

Interactive Shell

-

- OPA features an interactive shell that you can use to quickly experiment with - queries and data sets. -

-
-
-

Embeddable

-

- OPA is written in Go with the intention of being embeddable. Applications written - in Go can use OPA as a library if needed. -

-
-
-
-
-
-

License

-

- OPA is licensed under the Apache 2.0 open source license. OPA is under - active development. -

-
-
diff --git a/site/.gitignore b/site/.gitignore new file mode 100644 index 0000000000..7269ec4566 --- /dev/null +++ b/site/.gitignore @@ -0,0 +1,4 @@ +.asset-cache +.jekyll-metadata +.sass-cache +_site diff --git a/docs/dev/SITE.md b/site/README.md similarity index 60% rename from docs/dev/SITE.md rename to site/README.md index af17e2ade1..67917ef29d 100644 --- a/docs/dev/SITE.md +++ b/site/README.md @@ -1,15 +1,17 @@ # Site Updates -We use GitHub pages to host the website that includes all of the OPA documentation. In order -to update the website, you need to have write permission on the open-policy-agent/opa repository. +We use GitHub pages to host the website that includes all of the OPA documentation. In order to update the website, you need to have write permission on the open-policy-agent/opa repository. -You also need to have [Jekyll](http://jekyllrb.com) installed to build the site. If you are -not sure how to install Jekyll, see the link for details. Assuming you have Ruby installed, -all you should need to do is run: +You also need to have [Jekyll](http://jekyllrb.com) installed to build the site. If you are not sure how to install Jekyll, see the link for details. + +Assuming you have Ruby installed, all you should need to do is run: ``` gem install --user-install jekyll -gem install --user-install redcarpet +gem install --user-install autoprefixer-rails +gem install --user-install jekyll-assets +gem install --user-install jekyll-contentblocks +gem install --user-install jekyll-minifier ``` To update the website perform the following steps: @@ -20,13 +22,12 @@ To update the website perform the following steps: git clone git@github.com:open-policy-agent/opa.git opa-site ``` - - Note: if you are preparing documentation for a specific release, checkout the release - tag in this step as well. + - Note: if you are preparing documentation for a specific release, checkout the release tag in this step as well. 1. Build the site content and save the output: ``` - cd opa-site/docs + cd opa-site/site jekyll build . tar czvf ~/site.tar.gz -C _site . ``` diff --git a/docs/_sass/_syntax-highlighting.scss b/site/_assets/highlight.scss similarity index 100% rename from docs/_sass/_syntax-highlighting.scss rename to site/_assets/highlight.scss diff --git a/site/_assets/images/benefits.svg b/site/_assets/images/benefits.svg new file mode 100644 index 0000000000..b57ce10061 --- /dev/null +++ b/site/_assets/images/benefits.svg @@ -0,0 +1 @@ +infographicCreated using Figma 0.90 \ No newline at end of file diff --git a/site/_assets/images/community-github-issues.svg b/site/_assets/images/community-github-issues.svg new file mode 100644 index 0000000000..a0d7bdf973 --- /dev/null +++ b/site/_assets/images/community-github-issues.svg @@ -0,0 +1,39 @@ + +github issues +Created using Figma 0.90 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/site/_assets/images/community-google-groups.svg b/site/_assets/images/community-google-groups.svg new file mode 100644 index 0000000000..88b5ef05e5 --- /dev/null +++ b/site/_assets/images/community-google-groups.svg @@ -0,0 +1,37 @@ + +google groups +Created using Figma 0.90 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/site/_assets/images/community-slack.svg b/site/_assets/images/community-slack.svg new file mode 100644 index 0000000000..1cc1f5028f --- /dev/null +++ b/site/_assets/images/community-slack.svg @@ -0,0 +1,39 @@ + +slack +Created using Figma 0.90 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/docs/data-model-dependencies.svg b/site/_assets/images/data-model-dependencies.svg similarity index 100% rename from docs/docs/data-model-dependencies.svg rename to site/_assets/images/data-model-dependencies.svg diff --git a/docs/docs/data-model-logical.svg b/site/_assets/images/data-model-logical.svg similarity index 65% rename from docs/docs/data-model-logical.svg rename to site/_assets/images/data-model-logical.svg index a50aedddad..8d116bba9b 100644 --- a/docs/docs/data-model-logical.svg +++ b/site/_assets/images/data-model-logical.svg @@ -1,3 +1,3 @@ - Produced by OmniGraffle 6.5 2016-03-24 23:16:41 +0000Data Model Logical 2Layer 1data {}opa {}examples {}package opa.examplesimport ...public_servers[server] :- server = servers[_], server.ports[_] = ports[i].id, ports[i].network = networks[j].id, networks[j].public = truepackage opa.examplesimport data.serversviolations[server] :- server = servers[_], server.protocols[_] = “http”, public_servers[server]ports [ … ]networks [ … ]servers [ … ]public_servers [ … ]violations [ … ]appapp + Produced by OmniGraffle 6.5 2016-03-24 23:16:41 +0000Data Model Logical 2Layer 1data {}opa {}examples {}package opa.examplesimport ...public_servers[server] :- server = servers[_], server.ports[_] = ports[i].id, ports[i].network = networks[j].id, networks[j].public = truepackage opa.examplesimport data.serversviolations[server] :- server = servers[_], server.protocols[_] = “http”, public_servers[server]ports [ … ]networks [ … ]servers [ … ]public_servers [ … ]violations [ … ]serviceuser diff --git a/site/_assets/images/experience.svg b/site/_assets/images/experience.svg new file mode 100644 index 0000000000..da2d7ccb14 --- /dev/null +++ b/site/_assets/images/experience.svg @@ -0,0 +1 @@ +write-enforceCreated using Figma 0.90 \ No newline at end of file diff --git a/site/_assets/images/github-corner-right.svg b/site/_assets/images/github-corner-right.svg new file mode 100644 index 0000000000..6483dc190d --- /dev/null +++ b/site/_assets/images/github-corner-right.svg @@ -0,0 +1 @@ + diff --git a/site/_assets/images/icon-download-white.svg b/site/_assets/images/icon-download-white.svg new file mode 100644 index 0000000000..0aae329890 --- /dev/null +++ b/site/_assets/images/icon-download-white.svg @@ -0,0 +1 @@ + diff --git a/site/_assets/images/icon-github.svg b/site/_assets/images/icon-github.svg new file mode 100644 index 0000000000..ca798dadbd --- /dev/null +++ b/site/_assets/images/icon-github.svg @@ -0,0 +1 @@ +icon-github \ No newline at end of file diff --git a/site/_assets/stylesheets/highlight.scss b/site/_assets/stylesheets/highlight.scss new file mode 100644 index 0000000000..a6d05d072e --- /dev/null +++ b/site/_assets/stylesheets/highlight.scss @@ -0,0 +1,64 @@ +/** + * Syntax highlighting styles + */ +.highlight { + .c { color: #998; font-style: italic } // Comment + .err { color: #a61717; background-color: #e3d2d2 } // Error + .k { font-weight: bold } // Keyword + .o { font-weight: bold } // Operator + .cm { color: #998; font-style: italic } // Comment.Multiline + .cp { color: #999; font-weight: bold } // Comment.Preproc + .c1 { color: #998; font-style: italic } // Comment.Single + .cs { color: #999; font-weight: bold; font-style: italic } // Comment.Special + .gd { color: #000; background-color: #fdd } // Generic.Deleted + .gd .x { color: #000; background-color: #faa } // Generic.Deleted.Specific + .ge { font-style: italic } // Generic.Emph + .gr { color: #a00 } // Generic.Error + .gh { color: #999 } // Generic.Heading + .gi { color: #000; background-color: #dfd } // Generic.Inserted + .gi .x { color: #000; background-color: #afa } // Generic.Inserted.Specific + .go { color: #888 } // Generic.Output + .gp { color: #555 } // Generic.Prompt + .gs { font-weight: bold } // Generic.Strong + .gu { color: #aaa } // Generic.Subheading + .gt { color: #a00 } // Generic.Traceback + .kc { font-weight: bold } // Keyword.Constant + .kd { font-weight: bold } // Keyword.Declaration + .kp { font-weight: bold } // Keyword.Pseudo + .kr { font-weight: bold } // Keyword.Reserved + .kt { color: #458; font-weight: bold } // Keyword.Type + .m { color: #099 } // Literal.Number + .s { color: #d14 } // Literal.String + .na { color: #008080 } // Name.Attribute + .nb { color: #0086B3 } // Name.Builtin + .nc { color: #458; font-weight: bold } // Name.Class + .no { color: #008080 } // Name.Constant + .ni { color: #800080 } // Name.Entity + .ne { color: #900; font-weight: bold } // Name.Exception + .nf { color: #900; font-weight: bold } // Name.Function + .nn { color: #555 } // Name.Namespace + .nt { color: #000080 } // Name.Tag + .nv { color: #008080 } // Name.Variable + .ow { font-weight: bold } // Operator.Word + .w { color: #bbb } // Text.Whitespace + .mf { color: #099 } // Literal.Number.Float + .mh { color: #099 } // Literal.Number.Hex + .mi { color: #099 } // Literal.Number.Integer + .mo { color: #099 } // Literal.Number.Oct + .sb { color: #d14 } // Literal.String.Backtick + .sc { color: #d14 } // Literal.String.Char + .sd { color: #d14 } // Literal.String.Doc + .s2 { color: #d14 } // Literal.String.Double + .se { color: #d14 } // Literal.String.Escape + .sh { color: #d14 } // Literal.String.Heredoc + .si { color: #d14 } // Literal.String.Interpol + .sx { color: #d14 } // Literal.String.Other + .sr { color: #009926 } // Literal.String.Regex + .s1 { color: #d14 } // Literal.String.Single + .ss { color: #990073 } // Literal.String.Symbol + .bp { color: #999 } // Name.Builtin.Pseudo + .vc { color: #008080 } // Name.Variable.Class + .vg { color: #008080 } // Name.Variable.Global + .vi { color: #008080 } // Name.Variable.Instance + .il { color: #099 } // Literal.Number.Integer.Long +} diff --git a/site/_assets/stylesheets/reset.scss b/site/_assets/stylesheets/reset.scss new file mode 100644 index 0000000000..8ca216791f --- /dev/null +++ b/site/_assets/stylesheets/reset.scss @@ -0,0 +1,83 @@ +*, +*:after, +*:before { + box-sizing: border-box; + border: 0; + font: inherit; + font-size: 100%; + margin: 0; + padding: 0; + vertical-align: baseline; +} + +*:after, +*:before { + content: none; +} + +address, +article, +aside, +audio, +body, +blockquote, +canvas, +dd, +details, +dialog, +div, +dl, +dt, +fieldset, +figcaption, +figure, +footer, +form, +h1, +h2, +h3, +h4, +h5, +h6, +header, +hgroup, +hr, +html, +legend, +li, +main, +menu, +nav, +noscript, +ol, +p, +pre, +section, +summary, +ul, +video { + display: block; +} + +button, +input, +keygen, +meter, +progress, +select, +textarea, { + display: inline-block; +} + +html { + text-size-adjust: 100%; +} + +ol, ul { + list-style: none; +} + +table { + border-collapse: collapse; + border-spacing: 0; +} diff --git a/site/_assets/stylesheets/style.scss b/site/_assets/stylesheets/style.scss new file mode 100644 index 0000000000..7888d6542f --- /dev/null +++ b/site/_assets/stylesheets/style.scss @@ -0,0 +1,563 @@ +@import "reset.scss"; +@import "highlight.scss"; + +@mixin clearfix { + &:after { + content: ""; + display: table; + clear: both; + } +} + +html, +body { + font-family: "Open Sans", "Helvetica Neue", "Liberation Sans", Arial, sans-serif; +} + +a { + text-decoration: none; + + &:link, + &:visited { + color: #09e; + } + + &:hover { + color: #ff9512; + } + + &:active { + color: #000; + } +} + +code.highlighter-rouge { + background-color: #f6f4f2; + font-family: "Menlo", "DejaVu Mono", "Liberation Mono", "Courier New", monospace; + font-size: 14px; + margin: 0 2px; + outline: solid 1px #ebe6e2; + padding: 1px 2px; +} + +div.highlighter-rouge { + background-color: #f6f4f2; + border: solid 1px #ebe6e2; + font-family: "Menlo", "DejaVu Mono", "Liberation Mono", "Courier New"; + font-size: 16px; + line-height: 24px; + margin: 24px auto; + max-width: 720px; + padding: 24px; + + & > .highlight { + overflow-x: auto; + } +} + +em { + font-style: italic; +} + +h2 { + color: #000; + font-size: 24px; + line-height: 32px; + margin: 40px 0 24px; + + &:first-child { + margin-top: 0; + } +} + +h3 { + color: rgba(0, 0, 0, 0.87); + font-size: 20px; + line-height: 28px; + margin: 20px 0 12px; +} + +ol, +ul { + margin: 12px auto; + + & li { + color: rgba(0, 0, 0, 0.87); + display: list-item; + font-size: 16px; + line-height: 24px; + margin: 0 0 0 60px; + } +} + +ol li { + list-style-type: decimal; +} + +ul li { + list-style-type: disc; +} + +p { + color: rgba(0, 0, 0, 0.87); + font-size: 16px; + line-height: 24px; + margin: 0 0 12px; +} + +strong { + font-style: bold; +} + +.opa-nav-main { + &--list { + margin: 27px auto; + max-width: 720px; + text-align: right; + @include clearfix; + } + + &--home-item { + border-bottom: solid 2px transparent; + display: inline-block; + float: left; + font-size: 16px; + line-height: 24px; + + &--selected { + border-bottom: solid 2px #444; + display: inline-block; + float: left; + font-size: 16px; + line-height: 24px; + } + } + + &--item { + border-bottom: solid 2px transparent; + display: inline-block; + font-size: 16px; + line-height: 24px; + margin: 0 0 0 24px; + + &--selected { + border-bottom: solid 2px #444; + display: inline-block; + font-size: 16px; + line-height: 24px; + margin: 0 0 0 24px; + } + } + + &--link { + text-decoration: none; + + &:link, + &:visited { + color: rgba(0, 0, 0, 0.73); + } + + &:hover { + color: #09e; + } + + &:active { + color: #ff9512; + } + } +} + +.opa-header { + background-color: #ff9512; + position: relative; + @include clearfix; + + &--fork-me { + position: absolute; + right: 0; + top: 0; + z-index: 0; + } + + &--minor-title { + color: #fff; + font-size: 24px; + line-height: 32px; + margin: 0 0 24px; + text-align: center; + } + + &--title { + color: #fff; + font-size: 48px; + line-height: 60px; + margin: 0 0 24px; + text-align: center; + } + + &--subtitle { + color: rgba(255, 255, 255, 0.93); + font-size: 20px; + line-height: 28px; + margin: -10px 0 24px; + text-align: center; + } + + &--text { + color: rgba(255, 255, 255, 0.93); + text-align: center; + + &:last-child { + margin-bottom: 0; + } + } + + &--link { + border-bottom: dotted 1px; + text-decoration: none; + + &:link, + &:visited { + border-color: rgba(255, 255, 255, 0.93); + color: rgba(255, 255, 255, 0.93); + } + + &:hover { + border-color: #fff; + color: #fff; + } + + &:active { + border-color: #444; + color: #444; + } + } + + &--download-list { + margin: 48px auto 0; + max-width: 720px; + + & li { + border: solid 2px rgba(255, 255, 255, 0.87); + border-radius: 4px; + display: inline-block; + float: left; + height: 130px; + margin: 0 0 0 24px; + position: relative; + width: 224px; + + &:first-child { + margin: 0; + } + + &::before { + background-image: url(/assets/icon-download-white.svg); + background-repeat: no-repeat; + background-size: cover; + content: ""; + display: block; + height: 48px; + left: 50%; + opacity: 0.87; + position: absolute; + top: 50%; + transform: translateX(-50%); + width: 48px; + z-index: 1; + } + } + + &--link { + display: block; + font-size: 20px; + height: 100%; + line-height: 72px; + position: absolute; + text-align: center; + text-decoration: none; + width: 100%; + z-index: 2; + + &:link, + &:visited { + color: rgba(255, 255, 255, 0.93); + } + + &:hover { + color: #fff; + } + + &:active { + color: #444; + } + } + } +} + +.opa-header--abstract { + background-color: #ff9512; + margin: 0 auto; + max-width: 720px; + position: relative; + @include clearfix; + + &--nav { + bottom: 0; + left: -10px; + position: absolute; + top: 0; + width: 224px; + + &-list { + margin: 10px 0 0; + } + + &-item { + display: block; + font-size: 16px; + line-height: 18px; + padding: 0 0 0 10px; + margin: 3px 0 15px; + } + + &-item--selected { + border-left: solid 2px #fff; + color: #fff; + display: block; + font-size: 16px; + line-height: 18px; + padding: 0 0 0 8px; + margin: 3px 0 15px; + } + + &-link { + text-decoration: none; + + &:link, + &:visited { + color: rgba(255, 255, 255, 0.80); + } + + &:hover { + color: #fff; + } + + &:active { + color: #444; + } + } + } + + & > h1 { + color: #fff; + font-size: 24px; + line-height: 32px; + margin: -4px 0 24px 248px; + max-width: 472px; + } + + & > p { + color: rgba(255, 255, 255, 0.93); + font-size: 16px; + line-height: 24px; + margin: 0 0 12px 248px; + max-width: 472px; + + &:last-child { + margin-bottom: 0; + } + } +} + +.opa-content { + margin: 60px auto; + max-width: 720px; + @include clearfix; + + .opa-header > & { + margin: 0 auto 60px; + padding: 60px 0 0; + } + + & + .opa-footer { + margin: 80px 0 0; + } +} + +.opa-homepage--content { + margin: 0 auto; + max-width: 720px; +} + +.opa-homepage--section { + &--experience, + &--benefits, + &--features { + padding: 60px 0; + } + + &--experience { + background-color: #fff; + } + + &--benefits { + background-color: #9fdaed; + } + + &--features { + background-color: #dded9f; + } + + &--title { + color: #000; + font-size: 24px; + line-height: 32px; + margin: 0 auto 24px; + text-align: center; + } + + &--text { + text-align: center; + } + + &--infographic { + margin: 60px auto 24px; + max-width: 720px; + } +} + +.opa-homepage--section--feature-list { + max-width: 720px; + margin: 16px auto 0; + @include clearfix; + + .opa-homepage--section--feature { + float: left; + max-width: 348px; + + &:nth-child(2n+1) { + margin-left: 0; + margin-right: 12px; + } + + &:nth-child(2n) { + margin-left: 12px; + margin-right: 0; + } + + &--title { + color: #000; + font-size: 16px; + line-height: 20px; + margin: 10px auto 10px; + } + + &--text { + color: rgba(0, 0, 0, 0.87); + font-size: 14px; + line-height: 20px; + margin: 0 auto 20px; + } + } +} + +.opa-tip { + background-color: rgba(255, 204, 0, 0.07); + border: solid 1px rgba(255, 153, 0, 0.13); + color: rgba(0, 0, 0, 0.73); + font-size: 16px; + font-style: italic; + line-height: 24px; + margin: 24px auto; + max-width: 624px; + padding: 12px; + position: relative; +} + +.opa-community--contact-list { + margin: 48px auto 0; + max-width: 720px; + @include clearfix; + + & li { + display: inline-block; + float: left; + height: 116px; + margin: 0 0 0 24px; + position: relative; + width: 224px; + + &:first-child { + margin: 0; + } + } + + & + .opa-footer { + margin: 80px 0 0; + } +} + +.opa-footer { + background-color: #444; + padding: 60px 0; + + &--text { + color: rgba(255, 255, 255, 0.87); + font-size: 14px; + line-height: 20px; + margin: 0 auto 20px; + max-width: 720px; + } + + &--github { + &--ci { + float: right; + vertical-align: middle; + } + + &--icon { + fill: rgba(255, 255, 255, 0.54); + margin-right: 8px; + vertical-align: text-bottom; + } + + &--link { + text-decoration: none; + + &:link, + &:visited { + color: rgba(255, 255, 255, 0.87); + } + + &:hover { + color: #fff; + } + + &:active { + color: #ff9512; + } + } + } + + &--link { + text-decoration: none; + + &:link, + &:visited { + color: #3cf; + } + + &:hover { + color: #fff; + } + + &:active { + color: #ff9512; + } + } +} + +.opa-keep-it-together { + white-space: nowrap; +} diff --git a/docs/_config.yml b/site/_config.yml similarity index 68% rename from docs/_config.yml rename to site/_config.yml index ad5dfef94f..db0b067b50 100644 --- a/docs/_config.yml +++ b/site/_config.yml @@ -8,16 +8,23 @@ # Site settings title: Open Policy Agent email: -description: > - OPA: An open source project to policy enable any application. +description: "OPA: An open source project to policy enable any application." baseurl: "" # the subpath of your site, e.g. /blog url: "http://openpolicyagent.org" # the base hostname & protocol for your site github_username: open-policy-agent github_repo: opa # Build settings -markdown: redcarpet -redcarpet: - extensions: - - tables - - no_intra_emphasis \ No newline at end of file +gems: + - autoprefixer-rails + - jekyll-assets + - jekyll-contentblocks + - jekyll-minifier +assets: + compress: + css: true + assets: + - "*.png" + - "*.svg" +kramdown: + auto_ids: false diff --git a/docs/_includes/footer.html b/site/_includes/footer.html similarity index 100% rename from docs/_includes/footer.html rename to site/_includes/footer.html diff --git a/site/_includes/head.html b/site/_includes/head.html new file mode 100644 index 0000000000..232a01f403 --- /dev/null +++ b/site/_includes/head.html @@ -0,0 +1,9 @@ + + + + + {% if page.title %}{{ page.title | escape }} | OPA{% else %}{{ site.title | escape }}{% endif %} + + + {% stylesheet style.scss %} + diff --git a/site/_includes/nav-documentation.html b/site/_includes/nav-documentation.html new file mode 100644 index 0000000000..c03fc4e9a5 --- /dev/null +++ b/site/_includes/nav-documentation.html @@ -0,0 +1,28 @@ +{% assign doc_what = false %} +{% assign doc_work = false %} +{% assign doc_rego = false %} + +{% for page in site.pages %} + {% case page.doc_id %} + {% when 'WHAT_IS_POLICY_ENABLEMENT' %} + {% assign doc_what = page %} + {% when 'HOW_DOES_OPA_WORK' %} + {% assign doc_work = page %} + {% when 'HOW_DO_I_WRITE_POLICIES' %} + {% assign doc_rego = page %} + {% endcase %} +{% endfor %} + + diff --git a/site/_includes/nav-examples.html b/site/_includes/nav-examples.html new file mode 100644 index 0000000000..5354a408c4 --- /dev/null +++ b/site/_includes/nav-examples.html @@ -0,0 +1,22 @@ +{% assign xmp_repl = false %} +{% assign xmp_auth = false %} + +{% for page in site.pages %} + {% case page.xmp_id %} + {% when 'WORKING_WITH_THE_OPA_REPL' %} + {% assign xmp_repl = page %} + {% when 'DOCKER_AUTHORIZATION' %} + {% assign xmp_auth = page %} + {% endcase %} +{% endfor %} + + diff --git a/docs/_includes/header.html b/site/_includes/nav-main.html similarity index 100% rename from docs/_includes/header.html rename to site/_includes/nav-main.html diff --git a/site/_layouts/default.html b/site/_layouts/default.html new file mode 100644 index 0000000000..c3a25e544c --- /dev/null +++ b/site/_layouts/default.html @@ -0,0 +1,21 @@ + + + {% include head.html %} + + {% include nav-main.html %} + +
+

{% img '{{assets["github-corner-right.svg"].logical_path}}' alt:'Fork me on GitHub' %}

+ +
+ {% contentblock header %} +
+
+ +
+ {% contentblock body %} +
+ + {% include footer.html %} + + diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html new file mode 100644 index 0000000000..aa4ce1158f --- /dev/null +++ b/site/_layouts/documentation.html @@ -0,0 +1,25 @@ + + + {% include head.html %} + + {% include nav-main.html %} + +
+

{% img '{{assets["github-corner-right.svg"].logical_path}}' alt:'Fork me on GitHub' %}

+ +
+
+ {% include nav-documentation.html %} + + {% contentblock header %} +
+
+
+ +
+ {% contentblock body %} +
+ + {% include footer.html %} + + diff --git a/site/_layouts/examples.html b/site/_layouts/examples.html new file mode 100644 index 0000000000..684e458d6e --- /dev/null +++ b/site/_layouts/examples.html @@ -0,0 +1,25 @@ + + + {% include head.html %} + + {% include nav-main.html %} + +
+

{% img '{{assets["github-corner-right.svg"].logical_path}}' alt:'Fork me on GitHub' %}

+ +
+
+ {% include nav-examples.html %} + + {% contentblock header %} +
+
+
+ +
+ {% contentblock body %} +
+ + {% include footer.html %} + + diff --git a/site/_layouts/homepage.html b/site/_layouts/homepage.html new file mode 100644 index 0000000000..098c8cc1dd --- /dev/null +++ b/site/_layouts/homepage.html @@ -0,0 +1,35 @@ + + + {% include head.html %} + + {% include nav-main.html %} + +
+
+

{% img '{{assets["github-corner-right.svg"].logical_path}}' alt:'Fork me on GitHub' %}

+ + {% contentblock header %} +
+
+ +
+
+ {% contentblock experience %} +
+
+ +
+
+ {% contentblock benefits %} +
+
+ +
+
+ {% contentblock features %} +
+
+ + {% include footer.html %} + + diff --git a/site/community/index.md b/site/community/index.md new file mode 100644 index 0000000000..aca975da7e --- /dev/null +++ b/site/community/index.md @@ -0,0 +1,28 @@ +--- +nav_id: MAIN_COMMUNITY +layout: default + +title: Community +--- + +{% contentfor header %} + +# Open Policy Agent +{: .opa-header--title} + +Under active development. +{: .opa-header--subtitle} + +Open Policy Agent (OPA) is an open source policy engine. Contributions are always welcome. For information about contributing, see [CONTRIBUTING.md](https://github.com/open-policy-agent/opa/blob/master/CONTRIBUTING.md){: .opa-header--link}. +{: .opa-header--text} + +{% endcontentfor %} + +{% contentfor body %} + + * [{% img '{{assets["community-slack.svg"].logical_path}}' alt:'Slack: community chat' %}](https://openpolicyagent.slack.com/) + * [{% img '{{assets["community-google-groups.svg"].logical_path}}' alt:'Google Groups: mailing list' %}](https://groups.google.com/forum/?hl=en#!forum/open-policy-agent) + * [{% img '{{assets["community-github-issues.svg"].logical_path}}' alt:'GitHub Issues: bugs + features' %}](https://github.com/open-policy-agent/opa/issues) + {: .opa-community--contact-list} + +{% endcontentfor %} diff --git a/docs/docs/lang.md b/site/documentation/how-do-i-write-policies/index.md similarity index 66% rename from docs/docs/lang.md rename to site/documentation/how-do-i-write-policies/index.md index 02f40f6923..8f91a59d1c 100644 --- a/docs/docs/lang.md +++ b/site/documentation/how-do-i-write-policies/index.md @@ -1,13 +1,20 @@ --- -layout: docs -title: Rego -section: references -sort_order: 3 +nav_id: MAIN_DOCUMENTATION +doc_id: HOW_DO_I_WRITE_POLICIES +layout: documentation + +title: How Do I Write Policies? --- -# Rego +{% contentfor header %} -OPA includes a policy engine that is purpose built for reasoning about information represented in structured documents such as JSON. Data stored in in the policy engine can be queried using OPA's native query language: Rego. +# How Do I Write Policies? + +OPA is purpose built for reasoning about information represented in structured documents. The data that your service and its users publish can be inspected and transformed using OPA’s native query language Rego. + +{% endcontentfor %} + +{% contentfor body %} ## What is Rego? @@ -21,7 +28,7 @@ Use Rego for defining policy that is easy to read and write. Rego focuses on providing powerful support for referencing nested documents and ensuring that queries are correct and unambiguous. -Rego is declarative so policy authors can focus on what queries should return rather than how queries should be executed. These queries are simpler and more 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, e.g., indexing, concurrent evaluation, reordering, etc. +Rego is declarative so policy authors can focus on what queries should return rather than how queries should be executed. These queries are simpler and more 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 (for example, indexing, concurrent evaluation, reordering, and so on). ## The Basics @@ -29,26 +36,26 @@ This section introduces the main aspects of Rego. The simplest rule is a single expression and is defined in terms of a [Scalar Value](#scalar-values): -```rego +```ruby pi = 3.14159 ``` -Rules define the content of documents. We can query for the content of the "pi" document generated by the rule above: +Rules define the content of documents. We can query for the content of the `pi` document generated by the rule above: -``` +```ruby > pi 3.14159 ``` Rules can also be defined in terms of [Composite Values](#composite-values): -```rego +```ruby rect = {"width": 2, "height": 4} ``` The result: -``` +```ruby > rect { "height": 4, @@ -58,85 +65,85 @@ The result: Many expressions are defined in terms of [Equality](#equality). These expressions can be thought of as assertions. The simplest example of a rule containing an equality expression involves two scalar values: -```rego +```ruby v = true :- 42 = "the meaning of life" ``` -We can evaluate "v" to check if it is equal to true: +We can evaluate `v` to check if it is equal to true: -``` +```ruby > v = true false ``` The order of operands in an equality expression does not matter. The result is the same: -``` +```ruby > true = v false ``` -If we evaluate "v" on its own, the REPL prints "undefined" because the body of the rule never evaluates to true. As a result, the document generated by the rule is undefined. +If we evaluate `v` on its own, the REPL prints `undefined` because the body of the rule never evaluates to `true`. As a result, the document generated by the rule is not defined. -``` +```ruby > v undefined ``` We can define rules in terms of [Variables](#variables) as well: -```rego +```ruby t :- x = 42, y = 41, x > y ``` -Multiple expressions are separated by the comma (",") character. In order for the rule to be true, all of the expressions in the rule must true for some set of variable bindings. There may be multiple sets of variable bindings that make the rule true. The body of a rule can be understood intuitively as "\ AND \ AND ... AND \". The rule itself can be understood intuitively as "\ is true if \". +Multiple expressions are separated by the comma (`,`) character. In order for the rule to be true, all of the expressions in the rule must true for some set of variable bindings. There may be multiple sets of variable bindings that make the rule true. The body of a rule can be understood intuitively as ` AND AND ... AND `. The rule itself can be understood intuitively as `` is `true` if ``. -When we query for the contents of "t" we see the obvious result: +When we query for the contents of `t` we see the obvious result: -``` +```ruby > t true ``` -The order of expressions in a rule does not affect the document's content: +The order of expressions in a rule does not affect the document’s content: -```rego +```ruby s :- x > y, y = 41, x = 42 ``` The query result is the same: -``` +```ruby > s true ``` Rego [References](#references) help you refer to nested documents. For example: -```rego +```ruby sites = [{"name": "prod"}, {"name": "smoke1"}, {"name": "dev"}] r :- sites[i].name = "prod" ``` -The rule "r" above asserts that there exists (at least) one document within "sites" where the "name" attribute equals "prod". +The rule `r` above asserts that there exists (at least) one document within `sites` where the `name` attribute equals `"prod"`. The result: -``` +```ruby > r true ``` We can generalize the example above with a rule that defines a set document instead of a boolean document: -```rego +```ruby q[name] :- sites[i].name = name ``` -When we query for "q" we obtain a set of names: +When we query for `q` we obtain a set of names: -```repl +```ruby > q[x] +----------+ | x | @@ -147,40 +154,37 @@ When we query for "q" we obtain a set of names: +----------+ ``` -We can re-write the rule "r" from above to make use of "q". We will call the new rule "p": +We can re-write the rule `r` from above to make use of `q`. We will call the new rule `p`: -```rego +```ruby p :- q["prod"] ``` The result will be the same: -``` +```ruby > p true ``` Rules which have arguments can be queried with input values: -``` +```ruby > q["smoke2"] undefined > q["dev"] true ``` -If you made it this far, congratulations. This section introduced the main -aspects of Rego. The rest of this document describes the individual aspects of Rego in detail and is useful as a reference when reading and writing policy. Rego's syntax is defined at the end of this document in the [Rego Grammar](#grammar) section. +If you made it this far, congratulations. This section introduced the main aspects of Rego. The rest of this document describes the individual aspects of Rego in detail and is useful as a reference when reading and writing policy. Rego’s syntax is defined at the end of this document in the [Rego Grammar](#grammar) section. ## Scalar Values -Scalar values are the simplest type of term in Rego. Scalar values can be -strings, numbers, booleans, or null. +Scalar values are the simplest type of term in Rego. Scalar values can be strings, numbers, booleans, or null. -Documents can be defined solely in terms of scalar values. This is useful for -defining constants that are referenced in multiple places. For example: +Documents can be defined solely in terms of scalar values. This is useful for defining constants that are referenced in multiple places. For example: -```rego +```ruby greeting = "Hello" max_height = 42 pi = 3.14159 @@ -190,7 +194,7 @@ sentinel = null These documents can be queried like any other: -``` +```ruby > greeting "Hello" > max_height @@ -205,23 +209,22 @@ null ## Composite Values -Composite values define collections. In simple cases, composite values -can be treated as constants like [Scalar Values](#scalar-values): +Composite values define collections. In simple cases, composite values can be treated as constants like [Scalar Values](#scalar-values): -```rego +```ruby cube = {"width": 3, "height": 4, "depth": 5} ``` The result: -``` +```ruby > cube.width 3 ``` Composite values can also be defined in terms of [Variables](#variables) or [References](#references). For example: -``` +```ruby > a = 42, b = false, c = null, d = {"a": a, "x": [b, c]} +----+-------+------+---------------------------+ | A | B | C | D | @@ -230,27 +233,25 @@ Composite values can also be defined in terms of [Variables](#variables) or [Ref +----+-------+------+---------------------------+ ``` -By defining composite values in terms of variables and references, rules can -define abstractions over raw data and other rules. +By defining composite values in terms of variables and references, rules can define abstractions over raw data and other rules. ## Variables Variables are another kind of term in Rego. They appear in both the head and body of rules. -Variables appearing in the head of a rule can be thought of as input and -output of the rule. Unlike many programming languages, where a variable is either an input or an output, in Rego a variable is simultaneously an input and an output. If a query supplies a value for a variable, that variable is an input, and if the query does not supply a value for a variable, that variable is an output. +Variables appearing in the head of a rule can be thought of as input and output of the rule. Unlike many programming languages, where a variable is either an input or an output, in Rego a variable is simultaneously an input and an output. If a query supplies a value for a variable, that variable is an input, and if the query does not supply a value for a variable, that variable is an output. For example: -```rego +```ruby sites = [{"name": "prod"}, {"name": "smoke1"}, {"name": "dev"}] :- true q[name] :- sites[i].name = name ``` -In this case, we evaluate "q" with a variable "x" (which is not bound to a value). As as result, the query returns all of the site names. +In this case, we evaluate `q` with a variable `x` (which is not bound to a value). As as result, the query returns all of the site names. -``` +```ruby > q[x] +----------+ | x | @@ -261,56 +262,50 @@ In this case, we evaluate "q" with a variable "x" (which is not bound to a value +----------+ ``` -On the other hand, if we evaluate "q" with an input value for "name" we can determine whether "name" exists in the document defined by "q": +On the other hand, if we evaluate `q` with an input value for `name` we can determine whether `name` exists in the document defined by `q`: -``` +```ruby > q["smoke2"] undefined > q["dev"] true ``` -Variables appearing in the head of a rule must also appear in a non-negated -equality expression within the same rule. This property ensures that if the -rule is evaluated and all of the expressions evaluate to true for some set of -variable bindings, the variable in the head of the rule will be defined. +Variables appearing in the head of a rule must also appear in a non-negated equality expression within the same rule. This property ensures that if the rule is evaluated and all of the expressions evaluate to true for some set of variable bindings, the variable in the head of the rule will be defined. ## References Referenced are used to access nested documents. -The examples in this section use the data defined in the [Examples](#examples) -section. +The examples in this section use the data defined in the [Examples](#examples) section. -The simplest reference contains no variables. For example, the following -reference returns the hostname of the second server in the first site document -from our example data: +The simplest reference contains no variables. For example, the following reference returns the hostname of the second server in the first site document from our example data: -``` +```ruby > sites[0].servers[1].hostname "helium" ``` -References are typically written using the "dot-access" style. The canonical form does away with "." and closely resembles dictionary lookup in a language such as Python: +References are typically written using the “dot-access” style. The canonical form does away with `.` and closely resembles dictionary lookup in a language such as Python: -``` +```ruby > sites[0]["servers"][1]["hostname"] "helium" ``` -Both forms are valid, however, the "dot-access" style is typically more readable. Note, there are two cases where brackets need to be used: +Both forms are valid, however, the dot-access style is typically more readable. Note that there are two cases where brackets must be used: -1. String keys containing characters other than [a-z], [A-Z], [0-9], or "_" (underscore). -1. Non-string keys such as numbers, booleans, and null. -1. Variable keys which are described later. + 1. String keys containing characters other than `[a-z]`, `[A-Z]`, `[0-9]`, or `_` (underscore). + 1. Non-string keys such as numbers, booleans, and null. + 1. Variable keys which are described later. -References are always prefixed with a variable that identifes the root -document. In the example above this is "p". The root document may be: +References are always prefixed with a variable that identifies the root +document. In the example above this is `p`. The root document may be: -- a local variable inside a rule. -- a rule inside the same package. -- a document stored in OPA. -- a documented temporarily provided to OPA as part of a transaction. + * a local variable inside a rule. + * a rule inside the same package. + * a document stored in OPA. + * a documented temporarily provided to OPA as part of a transaction. ### Variable Keys @@ -319,7 +314,7 @@ References can include variables as keys. References written this way are used t The following reference will select the hostnames of all the servers in our example data: -``` +```ruby > sites[i].servers[j].hostname +---+---+------------------------------+ | i | j | sites[i].servers[j].hostname | @@ -327,7 +322,7 @@ example data: | 0 | 0 | "hydrogen" | | 0 | 1 | "helium" | | 0 | 2 | "lithium" | -| 1 | 0 | "berylium" | +| 1 | 0 | "beryllium" | | 1 | 1 | "boron" | | 1 | 2 | "carbon" | | 2 | 0 | "nitrogen" | @@ -335,7 +330,7 @@ example data: +---+---+------------------------------+ ``` -Conceptually, this is the same as the following imperative code (Python): +Conceptually, this is the same as the following imperative (Python) code: ```python def hostnames(sites): @@ -346,9 +341,9 @@ def hostnames(sites): return result ``` -In the reference above, we effectively used variables named "i" and "j" to iterate the collections. If the variables are unused outside the reference, we prefer to replace them with an underscore ("_") character. The reference above can be rewritten as: +In the reference above, we effectively used variables named `i` and `j` to iterate the collections. If the variables are unused outside the reference, we prefer to replace them with an underscore (`_`) character. The reference above can be rewritten as: -``` +```ruby > sites[_].servers[_].hostname +------------------------------+ | sites[_].servers[_].hostname | @@ -356,7 +351,7 @@ In the reference above, we effectively used variables named "i" and "j" to itera | "hydrogen" | | "helium" | | "lithium" | -| "berylium" | +| "beryllium" | | "boron" | | "carbon" | | "nitrogen" | @@ -366,13 +361,14 @@ In the reference above, we effectively used variables named "i" and "j" to itera The underscore is special because it cannot be referred to by other parts of the rule, e.g., the other side of the expression, another expression, etc. The underscore can be thought of as a special iterator. Each time an underscore is specified, a new iterator is instantiated. -> Under the hood, OPA translates the "_" character to a unique variable name that does not conflict with variables and rules that are in scope. +> Under the hood, OPA translates the `_` character to a unique variable name that does not conflict with variables and rules that are in scope. +{: .opa-tip} ### Multiple Expressions Rules are often written in terms of multiple expressions that contain references to documents. In the following example, the rule defines a set of arrays where each array contains an application name and a hostname of a server where the application is deployed. -```rego +```ruby apps_and_hostnames[pair] :- apps[i].name = name, apps[i].servers[_] = server, @@ -383,14 +379,14 @@ apps_and_hostnames[pair] :- The result: -``` +```ruby > apps_and_hostnames[x] +----------------------+ | x | +----------------------+ | ["web","hydrogen"] | | ["web","helium"] | -| ["web","berylium"] | +| ["web","beryllium"] | | ["web","boron"] | | ["web","nitrogen"] | | ["mysql","lithium"] | @@ -399,17 +395,16 @@ The result: +----------------------+ ``` -Don't worry about understanding everything in this example right now. There are just two important points: +Don’t worry about understanding everything in this example right now. There are just two important points: -1. Several variables appear more than once in the body. When a variable is used in multiple locations, OPA will only produce documents for the rule with the variable bound to the same value in all expressions. - -2. The rule is joining the "apps" and "sites" documents implicitly. In Rego (and other languages based on Datalog) joins are implicit. + 1. Several variables appear more than once in the body. When a variable is used in multiple locations, OPA will only produce documents for the rule with the variable bound to the same value in all expressions. + 2. The rule is joining the `apps` and `sites` documents implicitly. In Rego (and other languages based on Datalog), joins are implicit. ### Self-Joins -Using a different key on the same array or object provides the equivalent of self-join in SQL. For example, the following rule defines a document containing apps deployed on the same site as "mysql": +Using a different key on the same array or object provides the equivalent of self-join in SQL. For example, the following rule defines a document containing apps deployed on the same site as `"mysql"`: -```rego +```ruby same_site[name] :- apps[i].name = "mysql", apps[i].servers[_] = server, @@ -422,7 +417,7 @@ same_site[name] :- The result: -``` +```ruby > same_site[x] +-------+ | x | @@ -442,7 +437,7 @@ Like [Rules](#rules), comprehensions consist of a head and a body. The body of a The body of a comprehension is able to refer to variables defined in the outer body. For example: -``` +```ruby > region = "west", names = [name | sites[i].region = region, sites[i].name = name] +-----------------+--------+ | names | region | @@ -451,13 +446,14 @@ The body of a comprehension is able to refer to variables defined in the outer b +-----------------+--------+ ``` -In the above query, the second expression contains an [Array Comprehension](#array-comprehension) that refers to the "region" variable. The region variable will be bound in the outer body. +In the above query, the second expression contains an [Array Comprehension](#array-comprehension) that refers to the `region` variable. The region variable will be bound in the outer body. > When a comprehension refers to a variable in an outer body, OPA will reorder expressions in the outer body so that variables referred to in the comprehension are bound by the time the comprehension is evaluated. +{: .opa-tip} Comprehensions are similar to the same constructs found in other languages like Python. For example, we could write the above comprehension in Python as follows: -```python +```ruby # Python equivalent of Rego comprehension shown above. names = [site.name for site in sites if site.region = "west"] ``` @@ -468,13 +464,13 @@ Comprehensions are often used to group elements by some key. A common use case f Array Comprehensions build array values out of sub-queries. Array Comprehensions have the form: -``` +```ruby [ | ] ``` For example, the following rule defines an object where the keys are application names and the values are hostnames of servers where the application is deployed. The hostnames of servers are represented as an array. -```rego +```ruby app_to_hostnames[app_name] = hostnames :- apps[_] = app, app_name = app.name, @@ -486,58 +482,56 @@ app_to_hostnames[app_name] = hostnames :- The result: -``` +```ruby > app_to_hostnames[app] = hostnames -+-----------+-----------------------------------------------------+ -| app | hostnames | -+-----------+-----------------------------------------------------+ -| "web" | ["hydrogen","helium","berylium","boron","nitrogen"] | -| "mysql" | ["lithium","carbon"] | -| "mongodb" | ["oxygen"] | -+-----------+-----------------------------------------------------+ ++-----------+------------------------------------------------------+ +| app | hostnames | ++-----------+------------------------------------------------------+ +| "web" | ["hydrogen","helium","beryllium","boron","nitrogen"] | +| "mysql" | ["lithium","carbon"] | +| "mongodb" | ["oxygen"] | ++-----------+------------------------------------------------------+ ``` In the future, Rego will support Set and Object comprehensions. ## Rules -Rules define the content of [Virtual Documents](/docs/arch.html#data-model) in +Rules define the content of [virtual documents](/docs/arch.html#data-model) in OPA. When OPA evaluates a rule, we say OPA *generates* the content of the document that is defined by the rule. -The examples in this section make use of the data defined -in the [Examples](#examples) section. +The sample code in this section make use of the data defined in [Examples](#examples). ### Generating Sets The following rule documents a set containing the hostnames of all servers: -```rego +```ruby hostnames[name] :- sites[_].servers[_].hostname = name ``` -When we query for the content of "hostnames" we see the same data as we would if we queried using the `sites[_].servers[_].hostname` reference directly: +When we query for the content of `hostnames` we see the same data as we would if we queried using the `sites[_].servers[_].hostname` reference directly: -``` +```ruby > hostnames[name] -+------------+ -| name | -+------------+ -| "hydrogen" | -| "helium" | -| "lithium" | -| "berylium" | -| "boron" | -| "carbon" | -| "nitrogen" | -| "oxygen" | -+------------+ ++-------------+ +| name | ++-------------+ +| "hydrogen" | +| "helium" | +| "lithium" | +| "beryllium" | +| "boron" | +| "carbon" | +| "nitrogen" | +| "oxygen" | ++-------------+ ``` This example introduces a few important aspects of Rego. -First, the rule defines a set document where the contents are defined by the -variable "name". We know this rule defines a set document because the head only includes a key. All rules have the following form (where key, value, and body are all optional): +First, the rule defines a set document where the contents are defined by the variable `name`. We know this rule defines a set document because the head only includes a key. All rules have the following form (where key, value, and body are all optional): ``` ? ? ? @@ -546,16 +540,17 @@ variable "name". We know this rule defines a set document because the head only For a more formal definition of the rule syntax, see the [Rego Grammar](#grammar) section at the end of this document. > Set documents are collections of values without keys. OPA represents set documents as arrays when serializing to JSON or other formats which do not support a set data type. The important distinction between sets and arrays or objects is that sets are unkeyed while arrays and objects are keyed, i.e., you cannot refer to the index of an element within a set. +{: .opa-tip} -Second, the `sites[_].servers[_].hostname` fragment selects the "hostname" attribute from all of the objects in the "servers" collection. From reading the fragment in isolation we cannot tell whether the fragment refers to arrays or objects. We only know that it refers to a collections of values. +Second, the `sites[_].servers[_].hostname` fragment selects the `hostname` attribute from all of the objects in the `servers` collection. From reading the fragment in isolation we cannot tell whether the fragment refers to arrays or objects. We only know that it refers to a collections of values. -Third, the `sites[_].servers[_].hostname = name` expression binds the value of the "hostname" attribute to the variable "name", which is also declared in the head of the rule. +Third, the `sites[_].servers[_].hostname = name` expression binds the value of the `hostname` attribute to the variable `name`, which is also declared in the head of the rule. ### Generating Objects Rules that define objects are very similar to rules that define sets. -```rego +```ruby apps_by_hostname[hostname] = app :- sites[_].servers[_] = server, server.hostname = hostname, @@ -563,10 +558,7 @@ apps_by_hostname[hostname] = app :- apps[i].name = app ``` -The rule above defines an object that maps hostnames to app names. The main -difference between this rule and one which defines a set is the rule head: in -addition to declaring a value, the rule head also declares a key for the -document. +The rule above defines an object that maps hostnames to app names. The main difference between this rule and one which defines a set is the rule head: in addition to declaring a value, the rule head also declares a key for the document. The result: @@ -581,15 +573,12 @@ The result: ### Incremental Definitions -A rule may be defined multiple times with the same name. When a rule is -defined this way, we refer to the rule definition as *incremental* because -each definition is additive. The document content for an incrementally defined -rule is the union of the document content for each of the individual rules. +A rule may be defined multiple times with the same name. When a rule is defined this way, we refer to the rule definition as *incremental* because each definition is additive. The document content for an incrementally defined rule is the union of the document content for each of the individual rules. -For example, we can write a rule that abstracts over our "servers" and -"containers" data as "instances": +For example, we can write a rule that abstracts over our `servers` and +`containers` data as `instances`: -```rego +```ruby instances[instance] :- sites[_].servers[_] = server, instance = {"address": server.hostname, "name": server.name} @@ -599,12 +588,11 @@ instances[instance] :- instance = {"address": container.ipaddress, "name": container.name} ``` -An incrementally defined rule can be intuitively understood as "\ OR -\ OR ... OR \". +An incrementally defined rule can be intuitively understood as ` OR OR ... OR `. The result: -``` +```ruby > instances[x] +-----------------------------------------------+ | x | @@ -612,7 +600,7 @@ The result: | {"address":"hydrogen","name":"web-0"} | | {"address":"helium","name":"web-1"} | | {"address":"lithium","name":"db-0"} | -| {"address":"berylium","name":"web-1000"} | +| {"address":"beryllium","name":"web-1000"} | | {"address":"boron","name":"web-1001"} | | {"address":"carbon","name":"db-1000"} | | {"address":"nitrogen","name":"web-dev"} | @@ -631,28 +619,26 @@ This generates the correct result when the expressions represent assertions abou For safety, a variable appearing in a negated expression must also appear in another non-negated equality expression in the rule. > OPA will reorder expressions to ensure that negated expressions are evaluated after other non-negated expressions with the same variables. OPA will reject rules containing negated expressions that do not meet the safety criteria described above. +{: .opa-tip} The simplest use of negation involves only scalar values or variables and is equivalent to complementing the operator: -```rego +```ruby t :- 42 = x, not x = "the meaning of life" ``` The result: -``` +```ruby > t true ``` -Negation is required to check whether some value *does not* exist in a -collection. I.e., complementing the operator in an expression such as `p[_] = -"foo"` yields `p[_] != "foo"`, however, this is not equivalent to `not p["foo"]`. +Negation is required to check whether some value *does not* exist in a collection. That is, complementing the operator in an expression such as `p[_] = "foo"` yields `p[_] != "foo"`. However, this is not equivalent to `not p["foo"]`. -For example, we can write a rule that defines a document containing names of -apps not deployed on the "prod" site: +For example, we can write a rule that defines a document containing names of apps not deployed on the `"prod"` site: -```rego +```ruby prod_servers[name] :- sites[_] = site, site.name = "prod", @@ -671,7 +657,7 @@ apps_not_in_prod[name] :- The result: -``` +```ruby > apps_not_in_prod[name] +-----------+ | name | @@ -684,9 +670,9 @@ The result: In Rego, policies are defined inside *modules*. Modules consist of: -- Exactly one [Package](#packages) declaration. -- Zero or more [Import](#imports) statements. -- Zero or more [Rule](#rules) definitions. + * Exactly one [Package](#packages) declaration. + * Zero or more [Import](#imports) statements. + * Zero or more [Rule](#rules) definitions. Modules are typically represented in Unicode text and encoded in UTF-8. @@ -696,42 +682,33 @@ Comments begin with the `#` character and continue until the end of the line. ### Packages -Packages group the rules defined in one or more modules into a particular -namespace. Because rules are namespaced they can be safely shared across -projects. +Packages group the rules defined in one or more modules into a particular namespace. Because rules are namespaced they can be safely shared across projects. -Modules contributing to the same package do not have to be located in the same -directory. +Modules contributing to the same package do not have to be located in the same directory. -The rules defined in a module are automatically exported. I.e., they can be -queried under OPA's [Data API](/docs/arch.html#data-api) provided the appropriate -package is given, e.g., given the following module: +The rules defined in a module are automatically exported. That is, they can be queried under OPA’s [Data API](/docs/arch.html#data-api) provided the appropriate package is given. For example, given the following module: -```rego +```ruby package opa.examples pi = 3.14159 ``` -The "pi" document can be queried via the Data API: +The `pi` document can be queried via the Data API: -``` -GET /v1/data/opa/examples/pi +```http +GET https://example.com/v1/data/opa/examples/pi HTTP/1.1 ``` ### Imports -Import statements declare dependencies that modules have on documents -defined outside the package. By importing a document, the identifiers -exported by that document can be referenced within the current module. +Import statements declare dependencies that modules have on documents defined outside the package. By importing a document, the identifiers exported by that document can be referenced within the current module. -All modules contain an implicit statement which imports the "data" document. +All modules contain an implicit statement which imports the `data` document. -Modules use the same syntax to declare dependencies on [Base -Documents and Virtual -Documents](/docs/arch.html#data-model). +Modules use the same syntax to declare dependencies on [Base Documents and Virtual Documents](/docs/arch.html#data-model). -```rego +```ruby package opa.examples import data.servers @@ -741,10 +718,9 @@ http_servers[server] :- server.protocols[_] = "http" ``` -Imports can include an optional `alias` statement to handle namespacing -issues: +Imports can include an optional `alias` statement to handle namespacing issues: -```rego +```ruby package opa.examples import data.servers as my_servers @@ -758,39 +734,27 @@ http_servers[server] :- ### Equality -The equality operator (`=`) is used to define expressions that assert that -two values are the same. If the expression is defined in terms of one or more -variables then the expression will evaluate to true if one of the variables is -unbound. If the neither operand is an unbound variable, the expression is -evaluated by comparing the *values* referenced by the operands. +The equality operator (`=`) is used to define expressions that assert that two values are the same. If the expression is defined in terms of one or more variables then the expression will evaluate to true if one of the variables is unbound. If the neither operand is an unbound variable, the expression is evaluated by comparing the *values* referenced by the operands. -OPA attempts to *bind* variables to values when it encounters unbound variables -in equality expressions. Binding a variable affects subsequent evaluation of -expressions such that the variable will be treated as a constant (with the -bound value) instead of a variable. +OPA attempts to *bind* variables to values when it encounters unbound variables in equality expressions. Binding a variable affects subsequent evaluation of expressions such that the variable will be treated as a constant (with the bound value) instead of a variable. ### Inequality The following inequality operators are supported: -| Symbol | Example | Description | -| ------ | -------------- | ------- | -| `!=` | `"foo" != x.y` | LHS does not equal RHS. | -| `<` | `"foo" < x.y` | LHS is less than RHS. | -| `<=` | `"foo" <= x.y` | LHS is less than or equal to RHS. | -| `>` | `"foo" > x.y` | LHS is greater than RHS. | -| `>=` | `"foo" >= x.y` | LHS is greater than or equal to RHS. | +```ruby +a != b # `a` is not equal to `b`. +a < b # `a` is less than `b`. +a <= b # `a` is less than or equal to `b`. +a > b # `a` is greater than `b`. +a >= b # `a` is greater than or equal to `b`. +``` +Unlike the equality operator, these operators do not bind variables contained in the expression. As a result, if either operand is a variable, the variable must appear in another expression in the same rule that would cause the variable to be bound, i.e., an equality expression or the target position of a built-in function. -Unlike the equality operator, these operators do not bind variables contained -in the expression. As a result, if either operand is a variable, the variable -must appear in another expression in the same rule that would cause the variable -to be bound, i.e., an equality expression or the target position of a built-in -function. +## Built-in Functions -### Built-in Functions - -In some cases, rules must perform simple arithmetic, aggregation, etc. In these cases, Rego provides a number of Built-in Functions (or "built-ins") for performing these tasks. +In some cases, rules must perform simple arithmetic, aggregation, and so son. Rego provides a number of built-in functions (or “built-ins”) for performing these tasks. Built-ins can be easily recognized by their syntax. All built-ins have the following form: @@ -800,38 +764,148 @@ Built-ins can be easily recognized by their syntax. All built-ins have the follo Built-ins usually take one or more input values and produce at least one output value. Unless stated otherwise, all built-ins accept values or variables as output arguments. -#### Arithmetic +### Arithmetic -| Name | Example | Result | Description | -| ---- | ---- | ---- | ---- | -| `plus`| `plus(1, 2, x)` | `3` | Add two numbers. | -| `minus`| `minus(10, 5, x)` | `5` | Subtract two numbers. | -| `mul` | `mul(8, 3, x)` | `24` | Multiply two numbers. | -| `div` | `div(25, 5, x)` | `5` | Divide two numbers. Division by zero is treated as a runtime error and will cause the query to fail. | -| `round` | `round(3.5, x)` | `4` | Rounds the number to the nearest integer value. | -| `abs` | `abs(-1, x)` | `1` | Returns the number without its sign. | +```ruby +# plus(a, b, output) +# +# Adds two numbers. -#### Aggregation +> plus(1, 2, x) ++---+ +| x | ++---+ +| 3 | ++---+ +``` -| Name | Example | Result | Description | -| ---- | ---- | ---- | ---- | -| `count` | `count([1,2,3], x)` | `3` | Count the number of elements in the array or object or the number of characters in a string. | -| `sum` | `sum([1,2,3], x)` | `6` | Sum the numbers in an array. | -| `max` | `max([1,2,3], x)` | `3` | Calculate the maximum value in an array. | +```ruby +# minus(a, b, output) +# +# Subtracts two numbers. -#### Casting +> minus(13, 5, x) ++---+ +| x | ++---+ +| 8 | ++---+ +``` -| Name | Example | Result | Description | -| ---- | ---- | ---- | ---- | -| `to_number` | `to_number("3.14", x)` | `3.14` | Convert a scalar value to a number. | +```ruby +# mul(a, b, output) +# +# Multiplies two numbers. + +> mul(2, 4, x) ++---+ +| x | ++---+ +| 8 | ++---+ +``` + +```ruby +# div(a, b, output) +# +# Divides two numbers. + +> div(16, 4, x) ++---+ +| x | ++---+ +| 4 | ++---+ +``` + +```ruby +# round(number, output) +# +# Rounds the number to its nearest integer value. + +> round(3.5, x) ++---+ +| x | ++---+ +| 4 | ++---+ +``` + +```ruby +# abs(number, output) +# +# Calculates the absolute value of a number. + +> abs(-1, x) ++---+ +| x | ++---+ +| 1 | ++---+ +``` + +### Aggregation + +```ruby +# count(scalar, output) +# +# Counts the number of elements in the array or object or the number of +# characters in a string. + +> count([1,2,3], x) ++---+ +| x | ++---+ +| 3 | ++---+ +``` + +```ruby +# sum(array, output) +# +# Sums the numbers in an array. + +> sum([1,2,3], x) ++---+ +| x | ++---+ +| 6 | ++---+ +``` + +```ruby +# max(array, x) +# +# Calculates the maximum value in an array. + +> max([1,2,3], x) ++---+ +| x | ++---+ +| 3 | ++---+ +``` + +### Casting + +```ruby +# to_number(scalar, ouput) +# +# Converts a scalar value to a number. + +> to_number("3.14", x) ++------+ +| x | ++------+ +| 3.14 | ++------+ +``` ## Examples -The rules below define the content of documents describing a simplistic -deployment environment. These documents are referenced in other sections -above. +The rules below define the content of documents describing a simplistic deployment environment. These documents are referenced in other sections above. -```rego +```ruby sites = [ { "region": "east", @@ -857,7 +931,7 @@ sites = [ "servers": [ { "name": "web-1000", - "hostname": "berylium" + "hostname": "beryllium" }, { "name": "web-1001", @@ -916,7 +990,7 @@ containers = [ ## Rego Grammar -Rego's syntax is defined by the following grammar: +Rego’s syntax is defined by the following grammar: ``` module = package { import } policy @@ -959,3 +1033,5 @@ NULL JSON null ALPHA ASCII characters A-Z and a-z DIGIT ASCII characters 0-9 ``` + +{% endcontentfor %} diff --git a/site/documentation/how-does-opa-work/index.md b/site/documentation/how-does-opa-work/index.md new file mode 100644 index 0000000000..00d614217b --- /dev/null +++ b/site/documentation/how-does-opa-work/index.md @@ -0,0 +1,512 @@ +--- +nav_id: MAIN_DOCUMENTATION +doc_id: HOW_DOES_OPA_WORK +layout: documentation + +title: How Does OPA Work? +--- + +{% contentfor header %} + +# How Does OPA Work? + +OPA is a full-featured policy engine that runs as a host-local daemon alongside your service. You can think of it as a concierge for your service who can answer detailed questions on behalf of your users to meet their specific needs. + +{% endcontentfor %} + +{% contentfor body %} + +## Overview + +OPA’s RESTful APIs use JSON over HTTP so you and your users can integrate OPA with any programming language. At a high level, integrating OPA into your service involves: + + * Deploying OPA alongside your service + * Pushing relevant data about your service’s state into OPA’s document store + * Offloading some or all decision-making to OPA by querying it + +When your service is integrated with OPA, your users will be able author and deploy custom policies that control the behavior of your service’s policy-enabled features. Furthermore, users can publish data to OPA that is not available to your service about their own deployment context. + +In the future, both your service and its users will be able to register for, and react to, notifications triggered when OPA detects a policy-relevant change. + +## Deployment + +Unless you embed OPA as a Go library, you will deploy it alongside your service – either directly as an operating system daemon or inside a container. In this way, transactions will have low latency and availability will be determined through shared fate with your service. + +When OPA starts for the first time, it will not contain any policies or data. Policies and data can be added, removed, and modified at any time. For example: by deployment automation software or your service as it is deployed, by your service during an upgrade, or by administrators as needed. + +## Data and Policies + +The primary unit of data in OPA is a document, which is similar to a JSON value. Documents typically correspond to single, self-contained objects and are capable of representing both primitive types (strings, numbers, booleans, and null) as well as structured types (objects, and arrays). Documents are created, read, updated, and deleted via OPA’s RESTful HTTP APIs. + +{% img '{{assets["data-model-dependencies.svg"].logical_path}}' width:'720' %} + +### Base Documents + +So-called base documents contain static, structured data stored in memory and optionally saved to disk for resiliency. Your service will publish and update base documents in order to describe its current state, and your users can do the same to include relevant data about the state of their own deployment context. + +Base documents are published and updated using OPA’s Data API. For example, the following request publishes a list of servers to OPA: + +```http +PATCH /v1/data/servers HTTP/1.1 +Content-Type: application/json-patch+json +``` + +```json +[ + { + "op": "add", + "path": "-", + "value": { + "id": "s1", + "name": "app", + "protocols": [ + "http", + "https", + "ssh" + ], + "ports": [ + "p1", + "p2", + "p3" + ] + } + }, + { + "op": "add", + "path": "-", + "value": { + "id": "s2", + "name": "db", + "protocols": [ + "mysql" + ], + "ports": [ + "p3" + ] + } + }, + { + "op": "add", + "path": "-", + "value": { + "id": "s3", + "name": "cache", + "protocols": [ + "memcache" + ], + "ports": [ + "p3" + ] + } + }, + { + "op": "add", + "path": "-", + "value": { + "id": "s4", + "name": "dev", + "protocols": [ + "http", + "https", + "ssh" + ], + "ports": [ + "p1", + "p2" + ] + } + } +] +``` + +### Policies + +Policies are written using OPA’s purpose-built, declarative language Rego. Rego includes rich support for traversing nested documents and transforming data using syntax inspired by dictionary and array access in languages like Python and JSONPath. For detailed information about using Rego, see [How Do I Write Policies?](/documentation/how-do-i-write-policies). + +Each Rego file defines a policy module using a collection of rules that describe the expected state of your service. Both your service and its users can publish and update policy modules using OPA’s Policy API. For example, the following request creates a policy with two rules (violations and public_servers) named “exempli-gratia”: + +```http +PUT https://example.com/v1/policies/exempli-gratia HTTP/1.1 +Content-Type: text/plain +``` + +```ruby +package opa.examples + +import data.servers +import data.networks +import data.ports + +violations[server] :- + server = servers[_], + server.protocols[_] = "http", + public_servers[server] = true + +public_servers[server] :- + server = servers[_], + server.ports[_] = ports[i].id, + ports[i].networks[_] = networks[j].id, + networks[j].public = true +``` + +A policy file must contain a single package declaration, which defines the path to the policy module and its rules (for example, data.opa.examples.violations – see The data Document for more information about accessing nested documents). The policy name itself (in this case, “exempli-gratia”) is only used to identify policies for file management purposes; it is not used otherwise. + +### Rules and Virtual Documents + +In contrast to base documents, virtual documents embody the results of evaluating the rules included in policy modules. Virtual documents are computed when users publish new policy modules, update existing modules, run queries, and when any relevant base document is published or updated. Rules allow policy authors to write questions with yes-no answers (that is, predicates) and to generate structured values from raw data found in base documents as well as from intermediate data found in other virtual documents. + +### The data Document + +OPA nests all documents within a built-in root document named data. All documents, whether pushed by your service or computed by OPA as needed, are contained within the data document. + +{% img '{{assets["data-model-logical.svg"].logical_path}}' width:'720' %} + +```json +{ + "data": { + "servers": [...], + "ports": [...], + "networks": [...], + "opa": { + "examples": { + "violations": [...], + "public_servers": [...] + } + } + } +} +``` + +As a result, any document, base or virtual, can be accessed hierarchically starting from the root data node – either as an identifier: + +```ruby +import data.servers # Base document +import data.opa.examples.violations # Virtual document +``` + +or as a URI component in an HTTP request: + +```http +GET https://example.com/v1/data/servers HTTP/1.1 +``` + +```http +GET https://example.com/v1/data/opa/examples/violations HTTP/1.1 +``` + +### Putting It All Together + +Let’s take a look at some documents representing the state of a hypothetical service and a policy module that uses this data. The following documents describe a set of servers, the protocols they use, the ports they open, and the networks those ports are connected to. + +```json +{ + "data": { + "servers": [ + { + "id": "s1", + "name": "app", + "protocols": [ + "https", + "ssh" + ], + "ports": [ + "p1", + "p2", + "p3" + ] + }, + { + "id": "s2", + "name": "db", + "protocols": [ + "mysql" + ], + "ports": [ + "p3" + ] + }, + { + "id": "s3", + "name": "cache", + "protocols": [ + "memcache", + "http" + ], + "ports": [ + "p3" + ] + }, + { + "id": "s4", + "name": "dev", + "protocols": [ + "http" + ], + "ports": [ + "p1", + "p2" + ] + } + ], + "networks": [ + { + "id": "n1", + "public": false + }, + { + "id": "n2", + "public": false + }, + { + "id": "n3", + "public": true + } + ], + "ports": [ + { + "id": "p1", + "networks": [ + "n1" + ] + }, + { + "id": "p2", + "networks": [ + "n3" + ] + }, + { + "id": "p3", + "networks": [ + "n2" + ] + } + ] + } +} +``` + +When the data is published, we can use OPA’s API to inspect base documents like servers: + +```http +GET https://example.com/v1/data/servers HTTP/1.1 +``` + +The response is an array of all servers: + +```json +[ + { + "id": "s1", + "name": "app", + "protocols": [ + "https", + "ssh" + ], + "ports": [ + "p1", + "p2", + "p3" + ] + }, + { + "id": "s2", + "name": "db", + "protocols": [ + "mysql" + ], + "ports": [ + "p3" + ] + }, + { + "id": "s3", + "name": "cache", + "protocols": [ + "memcache", + "http" + ], + "ports": [ + "p3" + ] + }, + { + "id": "s4", + "name": "dev", + "protocols": [ + "http" + ], + "ports": [ + "p1", + "p2" + ] + } +] +``` + +Now let’s write a policy that enumerates servers that are connected to public networks and that are using HTTP. These servers are violating a business rule that states that all public servers must use HTTPS. + +```ruby +# This policy module belongs the opa.example package. +package opa.examples + +# Refer to data.servers as `servers`. +import data.servers +# Refer to the data.networks as `networks`. +import data.networks +# Refer to the data.ports as `ports`. +import data.ports + +# A server exists in the violations set if... +violations[server] :- + # ...the server exists + server = servers[_], + # ...and any of the server’s protocols is HTTP + server.protocols[_] = "http", + # ...and the server is public. + public_servers[server] = true + +# A server exists in the public_servers set if... +public_servers[server] :- + # ...the server exists + server = servers[_], + # ...and the server is connected to a port + server.ports[_] = ports[i].id, + # ...and the port is connected to a network + ports[i].networks[_] = networks[j].id, + # ...and the network is public. + networks[j].public = true +``` + +Note that: + + * Rules consist of assertions about data stored in OPA. In this case, the assertions test for equality with, and membership of, values in the servers, networks, and ports documents. + * Expressions can reference elements in a collection using the `[_]` and `[]` syntax. OPA knows to evaluate such queries by iterating over each element in the corresponding collection. + * Assertions about elements in a collection are `true` if any of the elements match the expression, and are only `false` when none of the elements match. For example, `ports[i].networks[_] = networks[j].id` will be `true` whenever any element in `ports[i].networks` matches the id of any element in `networks`. + * Expressions can reference nested documents. For `example,ports[i].networks[_]` refers to each network ID listed in each port document. + * Expressions can reference virtual documents. For example, `public_servers[server] = true` matches only if `server` is in the list produced by the `public_servers` rule. + +After publishing this policy module, data will include additional documents corresponding to the module’s package declaration (opa.examples) and the virtual documents its rules generate. + +```json +{ + "data": { + "servers": [...], + "networks": [...], + "ports": [...], + "opa": { + "examples": { + "violations": [ + { + "id": "s4", + "name": "dev", + "protocols": [ + "http" + ], + "ports": [ + "p1", + "p2" + ] + } + ], + "public_servers": [ + { + "id": "s1", + "name": "app", + "protocols": [ + "https", + "ssh" + ], + "ports": [ + "p1", + "p2", + "p3" + ] + }, + { + "id": "s4", + "name": "dev", + "protocols": [ + "http" + ], + "ports": [ + "p1", + "p2" + ] + } + ] + } + } + } +} +``` + +If we use OPA’s API to inspect the violations virtual document… + +```http +GET https://example.com/v1/data/opa/examples/violations HTTP/1.1 +``` + +…the response is the subset of the servers base document that use HTTP and are connected to a public network: + +```http +HTTP/1.1 200 OK +Content-Type: application/json +``` + +```json +[ + { + "id": "s4", + "name": "dev", + "protocols": [ + "http" + ], + "ports": [ + "p1", + "p2" + ] + } +] +``` + +## Future Features + +OPA is under active development. The following features are planned but not yet implemented. + +### Triggers + +Your service and its users can register to be notified when the system exits the expected state so that violations can be remediated automatically. + +Any rule can be used as the trigger for a notification. For example, let’s assume that you want to migrate containers to a new host if their current host shuts down. You need a rule to detect when there are containers assigned to hosts that are no longer running. + +```ruby +# All production containers are running if... +containers_to_migrate[id] :- + # ...the container exists + container = containers[id], + # ...and it is in production + container.site.name = "prod", + # ...and its host is running. + container.host.state != "terminated" +``` + +This rule produces a list of containers that should be migrated. You can register to observe this rule, and when the underlying data changes, OPA will re-evaluate it and trigger a notification. You can handle the event by re-deploying the containers in the resulting list to a running host. + +### Transactions + +OPA APIs support transactional operations. Either all of the operations within a transaction succeed or the whole transaction fails. For example, to deploy a new virtual machine, you might: + + * Open a new transaction. + * Query OPA for a list of hosts where the VM can be deployed. + * Deploy the VM to host from the list. + * Push data about the new deployment into OPA’s document store. + * Close the transaction. + +If any of steps 2–4 fail, so will the transaction. + +### Debugging + +To understand why queries return specific results, policy authors can obtain detailed explanations from OPA about its query processing. + +{% endcontentfor %} diff --git a/site/documentation/what-is-policy-enablement/index.md b/site/documentation/what-is-policy-enablement/index.md new file mode 100644 index 0000000000..6b4f4a185d --- /dev/null +++ b/site/documentation/what-is-policy-enablement/index.md @@ -0,0 +1,51 @@ +--- +nav_id: MAIN_DOCUMENTATION +doc_id: WHAT_IS_POLICY_ENABLEMENT +layout: documentation + +title: What is Policy Enablement? +--- + +{% contentfor header %} + +# What Is Policy Enablement? + +A policy is a set of rules that governs the behavior of a service. + +Policy-enablement empowers users to read, write, and manage these rules without needing specialized development or operational expertise. + +When your users can implement policies without recompiling your source code, then your service is policy enabled. + +{% endcontentfor %} + +{% contentfor body %} + +## Policies + +All organizations have policies. Policies are essential to the long-term success of organizations because they encode important knowledge about how to comply with legal requirements, work within technical constraints, avoid repeating mistakes, and so on. + +In their simplest form, policies can be applied manually based on rules that are written down or conventions that are unspoken but permeate an organization’s culture. Policies may also be enforced with application logic or statically configured at deploy time. + +## Policy-Enabled Services + +Policy-enabled services allow policies to be specified declaratively, updated at any time without recompiling or redeploying, and enforced automatically (which is especially valuable when decisions need to be made faster than humanly possible). They make deployments more adaptable to changing business requirements, improve the ability to discover violations and conflicts, increase the consistency of policy compliance, and mitigate the risk of human error. + +A policy-enabled service is able to answer questions by comparing relevant input from its environment to policy statements written by administrators. For example, a cloud computing service could answer questions such as: + + * Can I add compute capacity? + * In what regions can I add compute capacity? + * Which instances are currently running in the wrong region? + +## Open Policy Agent + +OPA is a lightweight, self-contained and extensible agent co-located with the your service. OPA simplifies the task of policy enabling your service by implementing a full-featured policy engine for you. It provides: + + * Declarative policy authoring + * Secure policy management + * Interactive queries + * Transactional data consistency + * Asynchronous events + +With OPA, you do not have to design a policy language, build a compiler or interpreter, or implement other language analysis tools to policy enable your service. + +{% endcontentfor body %} diff --git a/site/examples/docker-authorization/index.md b/site/examples/docker-authorization/index.md new file mode 100644 index 0000000000..5631a45914 --- /dev/null +++ b/site/examples/docker-authorization/index.md @@ -0,0 +1,347 @@ +--- +sort_order: 1001 +nav_id: MAIN_EXAMPLES +xmp_id: DOCKER_AUTHORIZATION +layout: examples + +title: Docker Authorization +--- + +{% contentfor header %} +# Docker Authorization + +Docker’s out-of-the-box authorization model is all or nothing. But many users require finer-grained access control and Docker’s plugin infrastructure allows us to do so. + +This is an excellent opportunity to see how to policy enable an existing service. + +{% endcontentfor %} + +{% contentfor body %} + +## Goals + +This example helps you get started with OPA and introduces you to core concepts in OPA, including Rego the language used to define policies. + +> Policy enabling an application decouples the policy implementation from the business logic so that administrators can define policy without changing the application while still keeping up with the size, complexity, and dynamic nature of modern applications. +{: .opa-tip} + +Although there are a multitude of desirable access control policies, for demonstration purposes, we want to prevent the following: + + * Containers with insecure configurations. + * Users modifying the system without sufficient read+write access. + +This example illustrates two key concepts: + + 1. OPA policy definition is decoupled from the implementation of the service (in this case Docker). The administrator is empowered to define and manage policies without requiring changes to any of the apps. + 2. Both the data relevant to policy and the policy definitions themselves can change rapidly. + +Once you finish this example, you will be familiar with: + + * Running OPA as a server/daemon. + * Loading policy definitions and data via the REST APIs. + * Querying data via the REST APIs. + * The basics of [Rego](/documentation/how-do-i-write-policies/), OPA’s purpose-built policy language. + +## Prerequisites + +This example requires: + + * Docker Engine 1.11 or newer + * `root` or `sudo` access + +The example has been tested on the following platforms: + + * Ubuntu 16.04 (64-bit) + +If you are using a different distro, OS, or architecture, the steps will be the same. However, there may be slight differences in the commands you need to run. + +## Steps + +### 1. Create a directory for OPA policy defintions. + +```shell +$ mkdir -p policies +``` + +### 2. Download the latest version of OPA. + +```shell +$ curl -L https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_linux_amd64 > opa +$ chmod u+x opa +``` + + +### 3. Run OPA in server mode with logging enabled. + +```shell +$ opa run -s --alsologtostderr 1 --v 2 --policy-dir policies +``` + +OPA will run until it receives a signal to stop. Open another terminal to continue with the rest of the example. + +### 4. Download the [open-policy-agent/docker-authz-plugin](https://github.com/open-policy-agent/docker-authz-plugin) executable. + +```shell +$ curl -L https://github.com/open-policy-agent/docker-authz-plugin/releases/download/v0.1.0-rc1/docker-authz-plugin_linux_amd64 > docker-authz-plugin +$ chmod u+x docker-authz-plugin +``` + +The open-policy-agent/docker-authz-plugin repository hosts a small [Docker Authorization Plugin](https://docs.docker.com/engine/extend/plugins_authorization/). Docker's authorization plugin system allows an external process to receive all requests sent to the Docker daemon. The authorization plugin replies, instructing the Docker daemon to allow or reject the request. + +### 5. Create an empty policy definition that will allow all requests. + +```shell +$ cat >example.rego < This step requires sudo access because the Docker plugin framework will attempt to update the Docker daemon configuration. If you run without sudo you may encounter a permission error. +{: .opa-tip} + +### 7. Reconfigure Docker. + +Docker must include the following command-line argument: + +```shell +--authorization-plugin=docker-authz-plugin +``` + +On Ubuntu 16.04 with systemd, this can be done as follows (requires root): + +```shell +$ sudo mkdir -p /etc/systemd/system/docker.service.d +$ sudo tee -a /etc/systemd/system/docker.service.d/override.conf > /dev/null <example.rego <example.rego < 12. Identify the user in Docker requests. + +> Back up your existing Docker configuration, just in case. You can replace your original configuration after you are done with the example. +{: .opa-tip} + +```shell +$ mkdir -p ~/.docker +$ cp ~/.docker/config.json ~/.docker/config.json~ +``` + +To identify the user, include an HTTP header in all of the requests sent to the Docker daemon: + +```shell +$ cat >~/.docker/config.json <users.json <example.rego < ~/.docker/config.json < true +true +> 3.14 +3.14 +> ["hello", "world"] +[ + "hello", + "world" +] +``` + +You can also test simple boolean expressions: + +```ruby +> true = false +false +> 3.14 > 3 +true +> "hello" != "goodbye" +true +``` + +Most REPLs let you define variables that you can reference later on. OPA allows you to do something similar. For example, we can define a `pi` constant as follows: + +```ruby +> pi = 3.14 +``` + +Once "pi" is defined, you query for the value and write expressions in terms of it: + +```ruby +> pi +3.14 +> pi > 3 +true +``` + +One thing to watch out for in the REPL is that `=` is used both for assigning variables values and for testing the value of variables. For example `p = q` sometimes assigns `p` the value of `q` and sometimes checks if the values of `p` and `q` are the same. The REPL decides between assignment and test based on whether `p` already has a value or not. If `p` has a value, `p = q` is a test (returning `true` or `false`), and if `p` has no value `p = q` is an assignment. To unset a value for a variable, use the `unset` command. (This ambiguity is only really an issue in the REPL. When writing policy, the duality of `=` is actually beneficial.) + +```ruby +> pi = 3 +false +> unset pi +> pi = 3 +> pi +3 +``` + +In addition to running queries, the REPL also lets you define rules: + +```ruby +> p[x] :- a = [1,2,3,4], a[x] +> p[x], x > 1 ++---+ +| x | ++---+ +| 2 | +| 3 | ++---+ +``` + +The rule above defines a set of values that are the indices of elements in the array `a`. + +When you enter expressions into the OPA REPL, you are effectively running *queries*. The REPL output shows the values of variables in the expression that make the query `true`. If there is no set of variables that would make the query `true`, the REPL prints `false`. If there are no variables in the query and the query evaluates successfully, then the REPL just prints `true`. + +Quit out of the REPL by pressing Control-C or typing `exit`: + +```ruby +> exit +Exiting +``` + +### 2. Create a data file and a policy module. + +Let's define a bit of JSON data that will be used in the example: + +```shell +$ cat >data.json <example.rego < data.servers[_].id ++--------------------+ +| data.servers[_].id | ++--------------------+ +| "s1" | +| "s2" | +| "s3" | +| "s4" | ++--------------------+ +> data.opa.example.public_servers[x] ++-------------------------------------------------------------------------------+ +| x | ++-------------------------------------------------------------------------------+ +| {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} | +| {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | ++-------------------------------------------------------------------------------+ +``` + +One powerful thing about Rego and the REPL is that you can run queries using the same syntax that you would use to lookup values. + +For example if `i` has value `0` then `data.servers[i]` returns the first value in the `data.servers` array: + +```ruby +> i = 0 +> data.servers[i] +{ + "id": "s1", + "name": "app", + "ports": [ + "p1", + "p2", + "p3" + ], + "protocols": [ + "https", + "ssh" + ] +} +``` + +That same expression `data.servers[i]` when `i` has no value defines a query that returns all the values of `i` and `data.servers[i]`: + +```ruby +> unset i +> data.servers[i] ++---+-------------------------------------------------------------------------------+ +| i | data.servers[i] | ++---+-------------------------------------------------------------------------------+ +| 0 | {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} | +| 1 | {"id":"s2","name":"db","ports":["p3"],"protocols":["mysql"]} | +| 2 | {"id":"s3","name":"cache","ports":["p3"],"protocols":["memcache"]} | +| 3 | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | ++---+-------------------------------------------------------------------------------+ +``` + +### 4. Import and export documents. + +The REPL also understands the [Import and Package](/documentation/how-do-i-write-policies/#modules) directives. + +```ruby +> import data.servers +> servers[i].ports[_] = "p2", servers[i].id = id ++---+------+ +| i | id | ++---+------+ +| 0 | "s1" | +| 3 | "s4" | ++---+------+ +``` + +```ruby +> package opa.example +> public_servers[x], x.protocols[_] = "http" ++-------------------------------------------------------------------+ +| x | ++-------------------------------------------------------------------+ +| {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | ++-------------------------------------------------------------------+ +``` + +### 5. Define a rule to identify servers in violation of our security policy. + +```ruby +> import data.servers +> violations[s] :- + s = servers[_], + s.protocols[_] = "http", + public_servers[s] +> violations[server] ++-------------------------------------------------------------------+ +| server | ++-------------------------------------------------------------------+ +| {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} | ++-------------------------------------------------------------------+ +``` + +> The REPL accepts multi-line input and will change appearance when it detects multi-line input. +{: .opa-tip} + +{% endcontentfor %} diff --git a/site/get-opa/index.md b/site/get-opa/index.md new file mode 100644 index 0000000000..6effaa24c0 --- /dev/null +++ b/site/get-opa/index.md @@ -0,0 +1,51 @@ +--- +nav_id: MAIN_GET_OPA +layout: default + +title: Get Open Policy Agent +--- + +{% contentfor header %} + +# Get Open Policy Agent +{: .opa-header--minor-title} + +OPA is available as binary releases for 64-bit Linux and Mac OS X or as Golang source code. +{: .opa-header--text} + + * [64-bit Linux](https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_linux_amd64){: .opa-header--download-list--link} + * [64-bit Mac OS X](https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_darwin_amd64){: .opa-header--download-list--link} + * [Go Source](https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa0.1rc3.src.tar.gz){: .opa-header--download-list--link} + {: .opa-header--download-list} + +{% endcontentfor %} + +{% contentfor body %} + +## 64-bit Linux + +```shell +$ curl -L https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_linux_amd64 > opa +$ chmod u+x opa +$ ./opa version +``` + +## 64-bit Mac OS X + +```shell +$ curl -L https://github.com/open-policy-agent/opa/releases/download/v0.1.0-rc3/opa_darwin_amd64 > opa +$ chmod u+x opa +$ ./opa version +``` + +## Go Source + +```shell +$ git clone https://github.com/open-policy-agent/opa.git $GOPATH/src/github.com/open-policy-agent/opa +$ cd $GOPATH/src/github.com/open-policy-agent/opa +$ make deps +$ make +$ ./opa version +``` + +{% endcontentfor %} diff --git a/site/index.md b/site/index.md new file mode 100644 index 0000000000..e407bd3d17 --- /dev/null +++ b/site/index.md @@ -0,0 +1,117 @@ +--- +nav_id: MAIN_HOME +layout: homepage + +title: Open Policy Agent +--- + +{% contentfor header %} + +# Open Policy Agent +{: .opa-header--title} + +Decouple governance logic from application logic. +{: .opa-header--subtitle} + +Open Policy Agent (OPA) simplifies the task of policy enabling your service. OPA provides an extensible framework for declarative policy authoring, secure policy management, interactive queries, transactional data consistency, asynchronous events, and more. +{: .opa-header--text} + +So you can focus on other things. +{: .opa-header--text} + +{% endcontentfor %} + +{% contentfor experience %} + +## Deliver the experience you want your users to have. +{: .opa-homepage--section--title} + +Your users need deployments to comply with legal requirements, technical constraints, and their own team conventions. OPA policies are decoupled from your code so users can create and manage policies without modifying your service. +{: .opa-homepage--section--text} + +{% img '{{assets["experience.svg"].logical_path}}' alt:'With OPA, admins define how your service should behave using a declarative language. Attempts to use your service are posed as questions that OPA answers.' %} +{: .opa-homepage--section--infographic} + +{% endcontentfor %} + +{% contentfor benefits %} + +## Don’t roll your own policy engine. +{: .opa-homepage--section--title} + +Do you really have time and resources to devote to designing, implementing, testing, and maintaining a policy engine? +{: .opa-homepage--section--text} + +{% img '{{assets["benefits.svg"].logical_path}}' alt:'Without OPA, you need to implement policy management for your service from scratch. Required components must be carefully designed, implemented, and tested to ensure correct behavior and a positive user experience. That’s a lot of work. But OPA already includes everything you need in order to policy enable any service.' %} +{: .opa-homepage--section--infographic} + +{% endcontentfor %} + +{% contentfor features %} + +## Is OPA right for you? +{: .opa-homepage--section--title} + +OPA is purpose-built for modern deployment environments. OPA is… +{: .opa-homepage--section--text} + +
+
+ +### Decoupled +{: .opa-homepage--section--feature--title} + +Users don’t change your source code. Instead, they write policies in an easy-to-use, declarative language developed especially for OPA. +{: .opa-homepage--section--feature--text} + +
+ +
+ +### Easy to Deploy +{: .opa-homepage--section--feature--title} + +OPA has zero deployment dependencies. It runs as a daemon side-by-side with your service and shares its fate for the purposes of high availabilty. +{: .opa-homepage--section--feature--text} + +
+ +
+ +### Compatible +{: .opa-homepage--section--feature--title} + +OPA’s RESTful APIs use JSON over HTTP so you can integrate OPA with your service no matter which programming language you use. +{: .opa-homepage--section--feature--text} + +
+ +
+ +### Responsive +{: .opa-homepage--section--feature--title} + +OPA is designed from scratch with latency-sensitive applications in mind, enforcing policies with minimal performance impact. +{: .opa-homepage--section--feature--text} + +
+ +
+ +### Interactive +{: .opa-homepage--section--feature--title} + +Anyone can use OPA’s interactive shell to quickly experiment with queries and data sets. +{: .opa-homepage--section--feature--text} + +
+ +
+ +### Embeddable +{: .opa-homepage--section--feature--title} + +Anyone can use OPA’s interactive shell to quickly experiment with queries and data sets. +{: .opa-homepage--section--feature--text} + +{% endcontentfor %} From 1fdce147552ea87af437c024db9fd15b0cb03580 Mon Sep 17 00:00:00 2001 From: Mikol Graves Date: Wed, 13 Jul 2016 17:39:21 -0700 Subject: [PATCH 2/3] Midsummer site refresh --- docs/_layouts/default.html | 20 ------------ site/_includes/footer.html | 33 +++++++------------ site/_includes/nav-main.html | 63 ++++++++++++++++++++++-------------- 3 files changed, 49 insertions(+), 67 deletions(-) delete mode 100644 docs/_layouts/default.html diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html deleted file mode 100644 index e4ab96fb0b..0000000000 --- a/docs/_layouts/default.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - {% include head.html %} - - - - {% include header.html %} - -
-
- {{ content }} -
-
- - {% include footer.html %} - - - - diff --git a/site/_includes/footer.html b/site/_includes/footer.html index 735b95d7bd..4a48cdcb47 100644 --- a/site/_includes/footer.html +++ b/site/_includes/footer.html @@ -1,25 +1,14 @@ -