Docs: suggest using opa-config.yaml as name for config file (#6966)

And update some references throughout the docs.

Fixes #6959

Signed-off-by: Anders Eknert <[email protected]>

Author: anderseknert

ast/policy.go

@@ -570,7 +570,7 @@ func (pkg *Package) MarshalJSON() ([]byte, error) {
 }
 
 // IsValidImportPath returns an error indicating if the import path is invalid.
-// If the import path is invalid, err is nil.
+// If the import path is valid, err is nil.
 func IsValidImportPath(v Value) (err error) {
 	switch v := v.(type) {
 	case Var:

docs/content/configuration.md

@@ -9,11 +9,19 @@ required must be specified if the parent is defined. For example, when the
 configuration contains a `status` key, the `status.service` field must be
 defined.
 
+{{< info >}}
+OPA accepts any name for the configuration file. Some tooling may however benefit from knowing what name to associate
+with OPA's configuration file (for auto-completion of attributes, linting, etc.). The following names could be
+considered idiomatic for that purpose:
+- `opa-config.yaml` (or `.json`)
+- `opa-conf.yaml` (or `.json`)
+{{< /info >}}
+
 The configuration file path is specified with the `-c` or `--config-file`
 command line argument:
 
 ```bash
-opa run -s -c config.yaml
+opa run -s -c opa-config.yaml
 ```
 
 The file can be either JSON or YAML format. The following is an example
@@ -1019,7 +1027,7 @@ It will read the contents of the file and set the config value with the token.
 If using arrays/lists in the configuration the `--set` and `--set-file` overrides will not be able to
 patch sub-objects of the list. They will overwrite the entire index with the new object.
 
-For example, a `config.yaml` file with contents:
+For example, a `opa-config.yaml` file with contents:
 
 ```yaml
 services:
@@ -1034,7 +1042,7 @@ Used with overrides:
 
 ```shell
 opa run \
-  --config-file config.yaml
+  --config-file opa-config.yaml
   --set-file "services[0].credentials.bearer.token=/var/run/secrets/bearer_token.txt"
 ```
 

docs/content/docker-authorization.md

@@ -97,21 +97,21 @@ decision_logs:
   console: true
 ```
 
-Save the above file as `config.yaml`. We'll need to place this somewhere where the plugin can find it.
+Save the above file as `opa-config.yaml`. We'll need to place this somewhere where the plugin can find it.
 The `/etc/docker` directory will be mounted as `/opa` in the container running the plugin, so let's create a
 sub-directory for our configuration file there.
 
 ```shell
 sudo mkdir -p /etc/docker/config
-sudo mv config.yaml /etc/docker/config/
+sudo mv opa-config.yaml /etc/docker/config/
 ```
 
 ### 3. Install the opa-docker-authz plugin.
 
 Install the `opa-docker-authz` plugin and point it to the config file just created.
 
 ```shell
-docker plugin install openpolicyagent/opa-docker-authz-v2:0.9 opa-args="-config-file /opa/config/config.yaml"
+docker plugin install openpolicyagent/opa-docker-authz-v2:0.9 opa-args="-config-file /opa/config/opa-config.yaml"
 ```
 
 You need to configure the Docker daemon to use the plugin for authorization.

docs/content/extensions.md

@@ -332,7 +332,7 @@ go build -o opa++
 
 Define an OPA configuration file that will use your plugin:
 
-**config.yaml**:
+**opa-config.yaml**:
 
 ```yaml
 decision_logs:
@@ -345,7 +345,7 @@ plugins:
 Start OPA with the configuration file:
 
 ```bash
-./opa++ run --server --config-file config.yaml
+./opa++ run --server --config-file opa-config.yaml
 ```
 
 Exercise the plugin via the OPA API:

docs/content/management-discovery.md

@@ -201,7 +201,7 @@ with `region: "US"`, then the `bundle_name` will be `example/test1/p`.
 
 Start an OPA with a boot configuration as shown below:
 
-**config.yaml**
+**opa-config.yaml**
 
 ```yaml
 services:
@@ -220,7 +220,7 @@ labels:
 Run OPA:
 
 ```bash
-opa run -s -c config.yaml
+opa run -s -c opa-config.yaml
 ```
 
 You should see a log like below, which shows the bundle being downloaded. In
@@ -233,7 +233,7 @@ INFO Bundle downloaded and activated successfully. name=example/test1/p plugin=b
 Now start another OPA with a boot configuration as shown below. Notice the
 `region` is `UK`:
 
-**config.yaml**
+**opa-config.yaml**
 
 ```yaml
 services:
@@ -252,7 +252,7 @@ labels:
 Run OPA:
 
 ```bash
-opa run -s -c config.yaml
+opa run -s -c opa-config.yaml
 ```
 
 In this case, the bundle being downloaded is `example/test2/p` as `region` is