Get started

The Open Policy Agent (OPA) is an open source, general-purpose policy engine that enables unified, context-aware policy enforcement across the entire stack.

OPA provides a high-level declarative language for authoring policies and simple APIs to answer policy queries. Using OPA, you can offload policy decisions from your service such as:

  • Should this API call be allowed? E.g., true or false.
  • How much quota remains for this user? E.g., 1048.
  • Which hosts can this container be deployed on? E.g., ["host1", "host40", ..., "host329"].
  • What updates must be applied to this resource? E.g., {"labels": {"team": "products}}.

This tutorial shows how to get started with OPA using an interactive shell or REPL (read-eval-print loop).

Goals

REPLs are great for learning new languages and running quick experiments. You can use OPA’s REPL to experiment with policies and prototype new ones.

To introduce the REPL, you will use dummy data and an example policy. In English, the policy can be stated as follows:

  • Servers that open an unencrypted HTTP port must not be connected to a public network.

Inside the REPL, you will define rules that codify the policy stated above.

Once you finish this tutorial, you will be familiar with:

  • Running OPA as an interactive shell/REPL.
  • Writing ad-hoc queries in Rego.

Prerequisites

If this is your first time using OPA, download the latest executable for your system.

On macOS (64-bit):

  1. curl -L -o opa https://github.com/open-policy-agent/opa/releases/download/v0.11.0/opa_darwin_amd64

On Linux (64-bit):

  1. curl -L -o opa https://github.com/open-policy-agent/opa/releases/download/v0.11.0/opa_linux_amd64

Windows users can obtain the OPA executable from GitHub Releases. The steps below are the same for Windows users except the executable name will be different.

Set permissions on the OPA executable:

  1. chmod 755 ./opa

Steps

1. Make sure you can run the REPL on your machine.

  1. ./opa run

Without any data, you can experiment with simple expressions to get the hang of it:

  1. > true
  2. true
  3. > 3.14
  4. 3.14
  5. > ["hello", "world"]
  6. [
  7.   "hello",
  8.   "world"
  9. ]

You can also test simple boolean expressions:

  1. > true == false
  2. false
  3. > 3.14 > 3
  4. true
  5. > "hello" != "goodbye"
  6. true

Most REPLs let you define variables that you can reference later on. OPA allows you to do something similar. For example, you can define a pi constant as follows:

  1. > pi := 3.14

Once “pi” is defined, you query for the value and write expressions in terms of it:

  1. > pi
  2. 3.14
  3. > pi > 3
  4. true

In addition to running queries, the REPL also lets you define rules:

  1. > items := ["pizza", "apples", "bread", "coffee"]
  2. > users := {"bob": {"likes": [0, 2]}, "alice": {"likes": [1, 2, 3]}}
  3. > likes[[name, item]] { index := users[name].likes[_]; item := items[index] }

The likes rule above defines a set of tuples specifying what each user likes.

  1. > likes[["alice", item]] # what does alice like?
  2. +----------+------------------------+
  3. |   item   | likes[["alice", item]] |
  4. +----------+------------------------+
  5. | "apples" | ["alice","apples"]     |
  6. | "bread"  | ["alice","bread"]      |
  7. | "coffee" | ["alice","coffee"]     |
  8. +----------+------------------------+
  9. > likes[[name, "bread"]] # who likes bread?
  10. +---------+------------------------+
  11. |  name   | likes[[name, "bread"]] |
  12. +---------+------------------------+
  13. | "bob"   | ["bob","bread"]        |
  14. | "alice" | ["alice","bread"]      |
  15. +---------+------------------------+

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 undefined. 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-D or typing exit:

  1. > exit
  2. Exiting

2. Create a data file and a policy module.

Let’s define a bit of JSON data that will be used in the tutorial:

  1. cat >data.json <<EOF
  2. {
  3.     "servers": [
  4.         {"id": "s1", "name": "app", "protocols": ["https", "ssh"], "ports": ["p1", "p2", "p3"]},
  5.         {"id": "s2", "name": "db", "protocols": ["mysql"], "ports": ["p3"]},
  6.         {"id": "s3", "name": "cache", "protocols": ["memcache"], "ports": ["p3"]},
  7.         {"id": "s4", "name": "dev", "protocols": ["http"], "ports": ["p1", "p2"]}
  8.     ],
  9.     "networks": [
  10.         {"id": "n1", "public": false},
  11.         {"id": "n2", "public": false},
  12.         {"id": "n3", "public": true}
  13.     ],
  14.     "ports": [
  15.         {"id": "p1", "networks": ["n1"]},
  16.         {"id": "p2", "networks": ["n3"]},
  17.         {"id": "p3", "networks": ["n2"]}
  18.     ]
  19. }
  20. EOF

Also, let’s include a rule that defines a set of servers that are attached to public networks:

  1. cat >example.rego <<EOF
  2. package opa.example
  4. import data.servers
  5. import data.networks
  6. import data.ports
  8. public_servers[s] {
  9.     some i, j
  10.     s := servers[_]
  11.     s.ports[_] == ports[i].id
  12.     ports[i].networks[_] == networks[j].id
  13.     networks[j].public == true
  14. }
  15. EOF

3. Run the REPL with the data file and policy module as input.

  1. ./opa run data.json example.rego

You can now run queries against the various documents:

  1. > data.servers[_].id
  2. +--------------------+
  3. | data.servers[_].id |
  4. +--------------------+
  5. | "s1"               |
  6. | "s2"               |
  7. | "s3"               |
  8. | "s4"               |
  9. +--------------------+
  10. > data.opa.example.public_servers[x]
  11. +-------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
  12. |                                       x                                       |                      data.opa.example.public_servers[x]                       |
  13. +-------------------------------------------------------------------------------+-------------------------------------------------------------------------------+
  14. | {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} | {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} |
  15. | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]}             | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]}             |
  16. +-------------------------------------------------------------------------------+-------------------------------------------------------------------------------+

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:

  1. > i := 0
  2. > data.servers[i]
  3. {
  4.   "id": "s1",
  5.   "name": "app",
  6.   "ports": [
  7.       "p1",
  8.       "p2",
  9.       "p3"
  10.   ],
  11.   "protocols": [
  12.       "https",
  13.       "ssh"
  14.   ]
  15. }

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]:

  1. > unset i
  2. > data.servers[i]
  3. +---+-------------------------------------------------------------------------------+
  4. | i |                                data.servers[i]                                |
  5. +---+-------------------------------------------------------------------------------+
  6. | 0 | {"id":"s1","name":"app","ports":["p1","p2","p3"],"protocols":["https","ssh"]} |
  7. | 1 | {"id":"s2","name":"db","ports":["p3"],"protocols":["mysql"]}                  |
  8. | 2 | {"id":"s3","name":"cache","ports":["p3"],"protocols":["memcache"]}            |
  9. | 3 | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]}             |
  10. +---+-------------------------------------------------------------------------------+

4. Import and export documents.

The REPL also understands the Import and Package directives.

  1. > import data.servers
  2. > servers[i].ports[_] == "p2"; id := servers[i].id
  3. +---+------+
  4. | i |  id  |
  5. +---+------+
  6. | 0 | "s1" |
  7. | 3 | "s4" |
  8. +---+------+
  1. > package opa.example
  2. > public_servers[x].protocols[_] == "http"
  3. +-------------------------------------------------------------------+
  4. |                                 x                                 |
  5. +-------------------------------------------------------------------+
  6. | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} |
  7. +-------------------------------------------------------------------+

5. Define a rule to identify servers in violation of our security policy.

  1. > import data.servers
  2. > violations[s] {
  3.   s := servers[_]
  4.   s.protocols[_] == "http"
  5.   public_servers[s]
  6. }
  8. > violations[server] = _
  9. +-------------------------------------------------------------------+
  10. |                              server                               |
  11. +-------------------------------------------------------------------+
  12. | {"id":"s4","name":"dev","ports":["p1","p2"],"protocols":["http"]} |
  13. +-------------------------------------------------------------------+

The REPL accepts multi-line input and will change appearance when it detects multi-line input. You can end multi-line input by inserting a blank line.