Update docs and server binding addr per OPA v1.0 specs (#7140)

This changes updates the docs and all the policy examples in them to be OPA v1.0-compliant. It also binds the OPA server to `localhost` interface by default per OPA v1.0 specs. Signed-off-by: Ashutosh Narkar <[email protected]> Co-authored-by: Charlie Egan <[email protected]>
open-policy-agent · Dec 19, 2024 · 9a7d920 · 9a7d920
1 parent c5757a5
commit 9a7d920
Show file tree

Hide file tree

Showing 41 changed files with 824 additions and 750 deletions.
diff --git a/cmd/deps.go b/cmd/deps.go
@@ -74,8 +74,6 @@ Given a policy like this:
 
 	package policy
 
-	import rego.v1
-
 	allow if is_admin
 
 	is_admin if "admin" in input.user.roles

diff --git a/cmd/flags.go b/cmd/flags.go
@@ -162,7 +162,7 @@ func addRegoV0V1FlagWithDescription(fs *pflag.FlagSet, regoV1 *bool, value bool,
 }
 
 func addV0CompatibleFlag(fs *pflag.FlagSet, v1Compatible *bool, value bool) {
-	fs.BoolVar(v1Compatible, "v0-compatible", value, "opt-in to OPA features and behaviors prior to the OPA v1.0 release. Takes precedence over --v1-compatible")
+	fs.BoolVar(v1Compatible, "v0-compatible", value, "opt-in to OPA features and behaviors prior to the OPA v1.0 release")
 }
 
 func addV1CompatibleFlag(fs *pflag.FlagSet, v1Compatible *bool, value bool) {

diff --git a/cmd/run.go b/cmd/run.go
@@ -215,7 +215,7 @@ See https://godoc.org/crypto/tls#pkg-constants for more information.
 	runCommand.Flags().BoolVarP(&cmdParams.serverMode, "server", "s", false, "start the runtime in server mode")
 	runCommand.Flags().IntVar(&cmdParams.rt.ReadyTimeout, "ready-timeout", 0, "wait (in seconds) for configured plugins before starting server (value <= 0 disables ready check)")
 	runCommand.Flags().StringVarP(&cmdParams.rt.HistoryPath, "history", "H", historyPath(), "set path of history file")
-	cmdParams.rt.Addrs = runCommand.Flags().StringSliceP("addr", "a", []string{defaultAddr}, "set listening address of the server (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket)")
+	cmdParams.rt.Addrs = runCommand.Flags().StringSliceP("addr", "a", []string{defaultLocalAddr}, "set listening address of the server (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket)")
 	cmdParams.rt.DiagnosticAddrs = runCommand.Flags().StringSlice("diagnostic-addr", []string{}, "set read-only diagnostic listening address of the server for /health and /metric APIs (e.g., [ip]:<port> for TCP, unix://<path> for UNIX domain socket)")
 	cmdParams.rt.UnixSocketPerm = runCommand.Flags().String("unix-socket-perm", "755", "specify the permissions for the Unix domain socket if used to listen for incoming connections")
 	runCommand.Flags().BoolVar(&cmdParams.rt.H2CEnabled, "h2c", false, "enable H2C for HTTP listeners")
@@ -381,9 +381,8 @@ func initRuntime(ctx context.Context, params runCmdParams, args []string, addrSe
 	rt.SetDistributedTracingLogging()
 	rt.Params.AddrSetByUser = addrSetByUser
 
-	// v0 negates v1
-	if !addrSetByUser && !rt.Params.V0Compatible && rt.Params.V1Compatible {
-		rt.Params.Addrs = &[]string{defaultLocalAddr}
+	if !addrSetByUser && rt.Params.V0Compatible {
+		rt.Params.Addrs = &[]string{defaultAddr}
 	}
 
 	return rt, nil

diff --git a/cmd/run_test.go b/cmd/run_test.go
@@ -59,7 +59,7 @@ func TestRunServerBaseListenOnLocalhost(t *testing.T) {
 
 	ctx, cancel := context.WithCancel(context.Background())
 
-	rt, err := initRuntime(ctx, params, nil, false)
+	rt, err := initRuntime(ctx, params, nil, true)
 	if err != nil {
 		t.Fatalf("Unexpected error: %v", err)
 	}
@@ -436,7 +436,7 @@ func TestInitRuntimeAddrSetByUser(t *testing.T) {
 func newTestRunParams() runCmdParams {
 	params := newRunParams()
 	params.rt.GracefulShutdownPeriod = 1
-	params.rt.Addrs = &[]string{"localhost:0"}
+	params.rt.Addrs = &[]string{"localhost:8181"}
 	params.rt.DiagnosticAddrs = &[]string{}
 	params.serverMode = true
 	return params

diff --git a/cmd/test.go b/cmd/test.go
@@ -467,8 +467,6 @@ Example policy (example/authz.rego):
 
 	package authz
 
-	import rego.v1
-
 	allow if {
 		input.path == ["users"]
 		input.method == "POST"
@@ -483,8 +481,6 @@ Example test (example/authz_test.rego):
 
 	package authz_test
 
-	import rego.v1
-
 	import data.authz.allow
 
 	test_post_allowed if {

diff --git a/docs/README.md b/docs/README.md
@@ -173,8 +173,6 @@ In this module:
 ```live:rule_body:module
 package example
 
-import rego.v1
-
 u if {
 	"foo" == "foo"
 }
@@ -202,8 +200,6 @@ Here's what a more complex set of blocks could look like:
 ``````markdown
 ```live:eg:module:hidden
 package example
-
-import rego.v1
 ```
 
 We can define a scalar rule:
@@ -253,8 +249,6 @@ Whereas the `eg/string/rule` output is evaluated with the module:
 ```
 package example
 
-import rego.v1
-
 string := "hello"
 
 r if input.value == string

diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -127,7 +127,6 @@ at some point in time, but have been introduced gradually.
 
 ```live:example/refs:module:hidden
 package example
-import rego.v1
 ```
 
 When OPA evaluates policies it binds data provided in the query to a global
@@ -164,7 +163,6 @@ input.deadbeef
 
 ```live:example/exprs:module:hidden
 package example
-import rego.v1
 ```
 
 To produce policy decisions in Rego you write expressions against input and
@@ -223,7 +221,6 @@ input.servers[0].protocols[0] == "telnet"
 
 ```live:example/vars:module:hidden
 package example
-import rego.v1
 ```
 
 You can store values in intermediate variables using the `:=` (assignment)
@@ -275,7 +272,6 @@ x != y  # y has not been assigned a value
 
 ```live:example/iter:module:hidden
 package example
-import rego.v1
 ```
 
 Like other declarative languages (e.g., SQL), iteration in Rego happens
@@ -375,19 +371,6 @@ some i; input.servers[i].protocols[i] == "ssh"  # there is no assignment of i th
 While plain iteration serves as a powerful building block, Rego also features ways
 to express _FOR SOME_ and _FOR ALL_ more explicitly.
 
-{{< info >}}
-To ensure backwards-compatibility, the keywords discussed below introduced slowly.
-In the first stage, users can opt-in to using the new keywords via a special import:
-`import rego.v1` or, alternatively, `import future.keywords.every` introduces the `every` keyword described here.
-(Importing `every` means also importing `in` without an extra `import` statement.)
-
-At some point in the future, the keyword will become _standard_, and the import will
-become a no-op that can safely be removed. This should give all users ample time to
-update their policies, so that the new keyword will not cause clashes with existing
-variable names.
-[See the docs on _future keywords_](./policy-language/#future-keywords) for more information.
-{{< /info >}}
-
 ##### FOR SOME (`some`)
 
 `some ... in ...` is used to iterate over the collection (its last argument),
@@ -482,7 +465,6 @@ logic statements. Rules can either be "complete" or "partial".
 
 ```live:example/complete:module:hidden
 package example.rules
-import rego.v1
 ```
 
 #### Complete Rules
@@ -573,7 +555,6 @@ any_public_networks
 
 ```live:example/partial_set:module:hidden
 package example
-import rego.v1
 ```
 
 Partial rules are if-then statements that generate a set of values and
@@ -649,8 +630,6 @@ protocols:
 ```live:example/logical_or/complete:module:openable,merge_down
 package example.logical_or
 
-import rego.v1
-
 default shell_accessible := false
 
 shell_accessible if {
@@ -692,8 +671,6 @@ could be modified to generate a set of servers that expose `"telnet"` or
 ```live:example/logical_or/partial_set:module:openable,merge_down
 package example.logical_or
 
-import rego.v1
-
 shell_accessible contains server.id if {
 	server := input.servers[_]
 	server.protocols[_] == "telnet"
@@ -753,8 +730,6 @@ For example:
 ```live:example/final:module:openable,merge_down
 package example
 
-import rego.v1
-
 allow if {                                          # allow is true if...
     count(violation) == 0                           # there are zero violations.
 }
@@ -892,8 +867,6 @@ For example:
 ```live:example/using_opa:module:openable,read_only
 package example
 
-import rego.v1
-
 default allow := false                              # unless otherwise defined, allow is false
 
 allow if {                                          # allow is true if...
@@ -1034,10 +1007,9 @@ You can start OPA as a server with `-s` or `--server`:
 ./opa run --server ./example.rego
 ```
 
-By default OPA listens for HTTP connections on `0.0.0.0:8181`. See `opa run
+By default OPA listens for HTTP connections on `localhost:8181`. See `opa run
 --help` for a list of options to change the listening address, enable TLS, and
-more. For example, if the `--v1-compatible` flag is set, OPA will listen
-for HTTP connections on `localhost:8181` by default.
+more.
 
 Inside of another terminal use `curl` (or a similar tool) to access OPA's HTTP
 API. When you query the `/v1/data` HTTP API you must wrap input data inside of a

diff --git a/docs/content/aws-cloudformation-hooks.md b/docs/content/aws-cloudformation-hooks.md
@@ -174,8 +174,6 @@ simple policy to block an S3 Bucket unless it has an `AccessControl` attribute s
 ```live:example/system:module
 package system
 
-import rego.v1
-
 main := {
 	"allow": count(deny) == 0,
 	"violations": deny,
@@ -361,8 +359,6 @@ take a look at what such a main policy might look like:
 #
 package system
 
-import rego.v1
-
 main := {
 	"allow": count(violations) == 0,
 	"violations": violations,
@@ -437,8 +433,6 @@ We can now modify our original policy to verify S3 bucket resources only:
 ```live:example/bucket:module
 package aws.s3.bucket
 
-import rego.v1
-
 deny contains sprintf("S3 Bucket %s 'AccessControl' attribute value must be 'Private'", [input.resource.id]) if {
 	not bucket_is_private
 }
@@ -467,8 +461,6 @@ A simple authz policy for checking the bearer token might look something like th
 ```live:example/authz:module
 package system.authz
 
-import rego.v1
-
 default allow := false
 
 allow if {