enhancement!: Use .cerbos.yaml as conventional name for config file (…

…#1755)

Signed-off-by: Andrew Haines <haines@cerbos.dev>

cmd/cerbos/healthcheck/healthcheck.go

@@ -41,11 +41,11 @@ Examples:
 
 # Check gRPC endpoint
 
-cerbos healthcheck --config=/path/to/config.yaml
+cerbos healthcheck --config=/path/to/.cerbos.yaml
 
 # Check HTTP endpoint and ignore server certificate verification
 
-cerbos healthcheck --config=/path/to/config.yaml --kind=http --insecure
+cerbos healthcheck --config=/path/to/.cerbos.yaml --kind=http --insecure
 
 # Check the HTTP endpoint of a specific host with no TLS.
 

cmd/cerbos/run/run.go

@@ -33,7 +33,7 @@ const (
 	help = `
 Launches a command within the context of a Cerbos PDP. The policies are loaded by default from a directory named "policies" in the current working directory. The launched application can access Cerbos endpoints using the values from CERBOS_HTTP or CERBOS_GRPC environment variables.
 
-If a file named "cerbos.yaml" exists in the current working directory, it will be used as the configuration file for the PDP. You can override the config file and/or other configuration options using the flags described below. 
+If a file named ".cerbos.yaml" exists in the current working directory, it will be used as the configuration file for the PDP. You can override the config file and/or other configuration options using the flags described below.
 
 Examples:
 
@@ -67,7 +67,7 @@ storage:
 
 type Cmd struct {
 	LogLevel string         `help:"Log level (${enum})" default:"info" enum:"debug,info,warn,error"`
-	Config   string         `help:"Path to config file" type:"existingfile" placeholder:"./cerbos.yaml"`
+	Config   string         `help:"Path to config file" type:"existingfile" placeholder:".cerbos.yaml"`
 	Set      []string       `help:"Config overrides" placeholder:"server.adminAPI.enabled=true"`
 	Command  []string       `help:"Command to run" arg:"" passthrough:"" required:""`
 	Timeout  time.Duration  `help:"Cerbos startup timeout" default:"30s"`
@@ -157,9 +157,9 @@ func (c *Cmd) loadConfig() error {
 		if err := config.Load(c.Config, confOverrides); err != nil {
 			return fmt.Errorf("failed to load configuration from %s: %w", c.Config, err)
 		}
-	} else if fd, err := os.Stat("cerbos.yaml"); err == nil && !fd.IsDir() {
-		if err := config.Load("cerbos.yaml", confOverrides); err != nil {
-			return fmt.Errorf("failed to load configuration from cerbos.yaml: %w", err)
+	} else if fd, err := os.Stat(".cerbos.yaml"); err == nil && !fd.IsDir() {
+		if err := config.Load(".cerbos.yaml", confOverrides); err != nil {
+			return fmt.Errorf("failed to load configuration from .cerbos.yaml: %w", err)
 		}
 	} else {
 		wd, err := os.Getwd()

cmd/cerbos/server/server.go

@@ -49,7 +49,7 @@ func (ll *LogLevelFlag) Decode(ctx *kong.DecodeContext) error {
 type Cmd struct {
 	DebugListenAddr string       `help:"Address to start the gops listener" placeholder:":6666"`
 	LogLevel        LogLevelFlag `help:"Log level (${enum})" default:"info" enum:"debug,info,warn,error"`
-	Config          string       `help:"Path to config file" optional:"" placeholder:"./config.yaml" env:"CERBOS_CONFIG"`
+	Config          string       `help:"Path to config file" optional:"" placeholder:".cerbos.yaml" env:"CERBOS_CONFIG"`
 	CloudBundle     string       `help:"Use Cerbos Cloud to pull the policy bundle with the given label. Overrides the store defined in the configuration." optional:"" env:"CERBOS_CLOUD_BUNDLE"`
 	Set             []string     `help:"Config overrides" placeholder:"server.adminAPI.enabled=true"`
 	ZPagesEnabled   bool         `help:"Enable zpages" hidden:""`

deploy/charts/cerbos/templates/configmap.yaml

@@ -5,5 +5,5 @@ metadata:
   labels:
     {{- include "cerbos.labels" . | nindent 4 }}
 data:
-    "config.yaml": |-
+    ".cerbos.yaml": |-
     {{- include "cerbos.config" . | nindent 8 }}

deploy/charts/cerbos/templates/deployment.yaml

@@ -49,7 +49,7 @@ spec:
           imagePullPolicy: {{ .Values.image.pullPolicy }}
           args:
             - "server"
-            - "--config=/config/config.yaml"
+            - "--config=/config/.cerbos.yaml"
             - "--log-level={{ .Values.cerbos.logLevel }}"
           ports:
             - name: http

docs/modules/ROOT/examples/tutorial/03-resource-definition/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/examples/tutorial/04-calling-cerbos/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/examples/tutorial/05-testing-policies/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/examples/tutorial/06-adding-conditions/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/examples/tutorial/07-derived-roles/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/examples/tutorial/08-principal-policies/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/examples/tutorial/09-attribute-schema/cerbos/start.sh

@@ -1 +1 @@
-docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+docker run --rm -t --name cerbos -v $(pwd):/tutorial -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml

docs/modules/ROOT/pages/installation/container.adoc

@@ -4,10 +4,10 @@ include::partial$attributes.adoc[]
 
 [source,sh,subs="attributes"]
 ----
-docker run --rm --name cerbos -p 3592:3592 {app-docker-img} 
+docker run --rm --name cerbos -p 3592:3592 {app-docker-img}
 ----
 
-By default, the container is configured to listen on ports 3592 (HTTP) and 3593 (gRPC) and watch for policy files on the volume mounted at `/policies`. You can override these by creating a new xref:configuration:index.adoc[configuration file]. 
+By default, the container is configured to listen on ports 3592 (HTTP) and 3593 (gRPC) and watch for policy files on the volume mounted at `/policies`. You can override these by creating a new xref:configuration:index.adoc[configuration file].
 
 .Create a directory to hold the config file and policies.
 [source,sh,subs="attributes"]
@@ -18,7 +18,7 @@ mkdir -p cerbos-quickstart/policies
 .Create a config file.
 [source,sh,subs="attributes,+macros"]
 ----
-cat $$>$$ cerbos-quickstart/conf.yaml $$<<$$EOF
+cat $$>$$ cerbos-quickstart/.cerbos.yaml $$<<$$EOF
 server:
   httpListenAddr: ":3592"
 
@@ -33,6 +33,5 @@ EOF
 .Launch the container with the new config file.
 [source,sh,subs="attributes"]
 ----
-docker run --rm --name cerbos -d -v $(pwd)/cerbos-quickstart:/quickstart -p 3592:3592 {app-docker-img} server --config=/quickstart/conf.yaml
+docker run --rm --name cerbos -d -v $(pwd)/cerbos-quickstart:/quickstart -p 3592:3592 {app-docker-img} server --config=/quickstart/.cerbos.yaml
 ----
-

docs/modules/ROOT/pages/tutorial/01_running-locally.adoc

@@ -37,13 +37,13 @@ storage:
 
 NOTE: You can find the full configuration schema in the xref:configuration:index.adoc[Cerbos docs].
 
-Save this file to a directory `config/conf.yaml`. You'll also need to create an empty policy folder `policies/`.
+Save this configuration to a file named `.cerbos.yaml`. You'll also need to create an empty policy folder `policies/`.
 
 Now, extract the binary and run:
 
 [source,sh]
 ----
-./cerbos server --config=config/conf.yaml
+./cerbos server --config=.cerbos.yaml
 ----
 
 Once started you can open `http://localhost:3592` to see the API documentation.

docs/modules/ROOT/pages/tutorial/02_resource-definition.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Policy authoring
 
-NOTE: The policies for this section can be found link:{tutorial-base}/03-resource-definition/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/03-resource-definition/cerbos[on GitHub].
 
 == Authentication roles
 

docs/modules/ROOT/pages/tutorial/03_calling-cerbos.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Calling Cerbos
 
-NOTE: The policies for this section can be found link:{tutorial-base}/04-calling-cerbos/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/04-calling-cerbos/cerbos[on GitHub].
 
 Now that you know the policies are valid, it is time to make your first call to Cerbos to make an authorization check.
 
@@ -14,10 +14,10 @@ To start you need to launch the server:
 # Using Container
 docker run --rm --name cerbos -t \
   -v /tutorial:/tutorial \
-  -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/config/conf.yaml
+  -p 3592:3592 ghcr.io/cerbos/cerbos:latest server --config=/tutorial/.cerbos.yaml
 
 # Using Binary
-./cerbos server --config=/tutorial/config/conf.yaml
+./cerbos server --config=/tutorial/.cerbos.yaml
 ----
 
 Once Cerbos has started up you should see an output confirming that there are 3 policies loaded and ready to start processing authorization checks:

docs/modules/ROOT/pages/tutorial/04_testing-policies.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Testing policies
 
-NOTE: The policies for this section can be found link:{tutorial-base}/05-testing-policies/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/05-testing-policies/cerbos[on GitHub].
 
 Cerbos allows you to write xref:policies:compile.adoc[tests for policies] and run them as part of the compilation stage to make sure that the policies do exactly what you expect. This saves the manual effort of running example requests over and over to ensure the policy logic is as you expect.
 

docs/modules/ROOT/pages/tutorial/05_adding-conditions.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Adding conditions
 
-NOTE: The policies for this section can be found link:{tutorial-base}/06-adding-conditions/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/06-adding-conditions/cerbos[on GitHub].
 
 In the previous section, an RBAC policy was created that allowed anyone with a `user` role to update a user resource - this isn't what is intended as it would allow users to update other users' profiles.
 

docs/modules/ROOT/pages/tutorial/06_derived-roles.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Derived roles
 
-NOTE: The policies for this section can be found link:{tutorial-base}/07-derived-roles/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/07-derived-roles/cerbos[on GitHub].
 
 The business requirements for Cerbforce state that only an owner of Contacts and Companies are allowed to delete them from the system. With Cerbos, the aim is to keep policies as simple as possible and not repeat logic across different resources, so in this situation, a xref:policies:derived_roles.adoc[Derived Role] can enable help.
 

docs/modules/ROOT/pages/tutorial/07_principal-policies.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Principal policies
 
-NOTE: The policies for this section can be found link:{tutorial-base}/08-principal-policies/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/08-principal-policies/cerbos[on GitHub].
 
 The final type of policy that Cerbos supports is a xref:policies:principal_policies.adoc[principal policy] which is a special type that allows user-specific overrides to be defined.
 

docs/modules/ROOT/pages/tutorial/08_attribute-schema.adoc

@@ -2,7 +2,7 @@ include::partial$attributes.adoc[]
 
 = Attribute schema
 
-NOTE: The policies for this section can be found link:{tutorial-base}/09-attribute-schema/cerbos[on Github].
+NOTE: The policies for this section can be found link:{tutorial-base}/09-attribute-schema/cerbos[on GitHub].
 
 An additional check bit of business logic has been introduced for the `contact` resource which requires the `active` attribute of a contact to be set to `True` to be able to `update` or `delete` it. This is so that old contacts are kept for reporting purposes and can't be accidentally deleted or updated.
 
@@ -32,11 +32,12 @@ The same can be done with attributes of a principal - you can find out more in x
 
 == Enforcing schema
 
-Validating the request against the schema is done at request time by the server - to enable this a xref:configuration:schema.adoc[new schema configuration block] needs adding to the `config.yaml`.
+Validating the request against the schema is done at request time by the server - to enable this a xref:configuration:schema.adoc[new schema configuration block] needs adding to the `.cerbos.yaml`.
 
 [source,yaml]
 ----
-include::example$tutorial/09-attribute-schema/cerbos/config/conf.yaml[]
+schema:
+  enforcement: reject
 ----
 
 With this now in place, any request that is made to check authorization of a `contact` resource is rejected if the attributes are not provided or of the wrong type:

docs/modules/cli/pages/cerbos.adoc

@@ -92,7 +92,7 @@ You can share the configuration between Cerbos PDP and the healthcheck by using
 ----
 docker run -i -t -p 3592:3592 -p 3593:3593 \
     -v /path/to/conf/dir:/config \
-    -e CERBOS_CONFIG=/config/conf.yaml \
+    -e CERBOS_CONFIG=/config/.cerbos.yaml \
     {app-docker-img}
 ----
 
@@ -110,11 +110,11 @@ Examples:
 
 # Check gRPC endpoint
 
-cerbos healthcheck --config=/path/to/config.yaml
+cerbos healthcheck --config=/path/to/.cerbos.yaml
 
 # Check HTTP endpoint and ignore server certificate verification
 
-cerbos healthcheck --config=/path/to/config.yaml --kind=http --insecure
+cerbos healthcheck --config=/path/to/.cerbos.yaml --kind=http --insecure
 
 # Check the HTTP endpoint of a specific host with no TLS.
 
@@ -259,7 +259,7 @@ cerbos run -- python -m unittest
 
 By default, the policies are loaded from the `policies` directory in the current working directory and HTTP and gRPC endpoints will be exposed on `127.0.0.1:3592` and `127.0.0.1:3593` respectively. Your application can obtain the actual endpoint addresses by inspecting the `CERBOS_HTTP` or `CERBOS_GRPC` environment variables.
 
-If a file named `cerbos.yaml` exists in the current working directory, that file will be used as the Cerbos xref:configuration:index.adoc[configuration file]. You can use a different config file or override specific config values using the same flags as the `server` command above.
+If a file named `.cerbos.yaml` exists in the current working directory, that file will be used as the Cerbos xref:configuration:index.adoc[configuration file]. You can use a different config file or override specific config values using the same flags as the `server` command above.
 
 
 [source]
@@ -271,7 +271,7 @@ Run a command in the context of a Cerbos PDP
 Launches a command within the context of a Cerbos PDP. The policies are loaded by default from a directory named "policies" in the current working directory. The launched application can access Cerbos endpoints using the
 values from CERBOS_HTTP or CERBOS_GRPC environment variables.
 
-If a file named "cerbos.yaml" exists in the current working directory, it will be used as the configuration file for the PDP. You can override the config file and/or other configuration options using the flags described
+If a file named ".cerbos.yaml" exists in the current working directory, it will be used as the configuration file for the PDP. You can override the config file and/or other configuration options using the flags described
 below.
 
 Examples:
@@ -296,7 +296,7 @@ Flags:
       --version
 
       --log-level="info"                        Log level (debug,info,warn,error)
-      --config=./cerbos.yaml                    Path to config file
+      --config=.cerbos.yaml                     Path to config file
       --set=server.adminAPI.enabled=true,...    Config overrides
       --timeout=30s                             Cerbos startup timeout
 ----
@@ -309,26 +309,26 @@ Starts the Cerbos PDP.
 
 [source]
 ----
-Usage: cerbos server --config=./config.yaml
+Usage: cerbos server --config=.cerbos.yaml
 
 Start Cerbos server (PDP)
 
 Examples:
 
 # Start the server
 
-cerbos server --config=/path/to/config.yaml
+cerbos server --config=/path/to/.cerbos.yaml
 
 # Start the server with the Admin API enabled and the 'sqlite' storage driver
 
-cerbos server --config=/path/to/config.yaml --set=server.adminAPI.enabled=true --set=storage.driver=sqlite3 --set=storage.sqlite3.dsn=':memory:'
+cerbos server --config=/path/to/.cerbos.yaml --set=server.adminAPI.enabled=true --set=storage.driver=sqlite3 --set=storage.sqlite3.dsn=':memory:'
 
 Flags:
   -h, --help                                    Show context-sensitive help.
       --version
 
       --debug-listen-addr=:6666                 Address to start the gops listener
       --log-level="info"                        Log level (debug,info,warn,error)
-      --config=./config.yaml                    Path to config file
+      --config=.cerbos.yaml                     Path to config file
       --set=server.adminAPI.enabled=true,...    Config overrides
 ----

docs/modules/configuration/pages/index.adoc

@@ -3,11 +3,11 @@ include::ROOT:partial$attributes.adoc[]
 [[configuration]]
 = Configuration
 
-The Cerbos server is configured with a YAML file. Start the server by passing the configuration file using the `--config` flag. The values defined in the file can be overridden from the command-line by using the `--set` flag. The `--set` flag can be used multiple times. For example, to override `server.httpListenAddr` and `engine.defaultPolicyVersion`, the `--set` flag can be used as follows:
+The Cerbos server is configured with a YAML file, conventionally named `.cerbos.yaml`. Start the server by passing the configuration file using the `--config` flag. The values defined in the file can be overridden from the command-line by using the `--set` flag. The `--set` flag can be used multiple times. For example, to override `server.httpListenAddr` and `engine.defaultPolicyVersion`, the `--set` flag can be used as follows:
 
 [source,sh,subs="attributes"]
 ----
-./{app-name} server --config=/path/to/config.yaml --set=server.httpListenAddr=:3592 --set=engine.defaultPolicyVersion=staging
+./{app-name} server --config=/path/to/.cerbos.yaml --set=server.httpListenAddr=:3592 --set=engine.defaultPolicyVersion=staging
 ----
 
 NOTE: Config values can reference environment variables by enclosing them between `${}`, for example `$$${HOME}$$`. Defaults can be set using `$$${VAR:default}$$`.