Skip to content

Commit

Permalink
docs: add dropins to prose documentation
Browse files Browse the repository at this point in the history
This change explains how to use the dropins and updates the local-dev
config to do so.

Closes: #1783
Signed-off-by: Hank Donnay <hdonnay@redhat.com>
  • Loading branch information
hdonnay committed Sep 19, 2023
1 parent 6969e00 commit eb54b88
Show file tree
Hide file tree
Showing 4 changed files with 39 additions and 9 deletions.
40 changes: 33 additions & 7 deletions Documentation/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,8 @@

## CLI Flags And Environment Variables

Clair is configured by a structured yaml file.
Each Clair node needs to specify what mode it will run in and a path to a
configuration file via CLI flags or environment variables.
Clair is configured by a structured yaml or JSON[^1] file and an optional directory of "merge" and "patch" documents[^1].
Each Clair node needs to specify what mode it will run in and a path to a configuration file via CLI flags or environment variables.

For example:
```shell
Expand All @@ -28,8 +27,7 @@ $ clair -conf ./path/to/config.yaml -mode matcher
```

The above example starts two Clair nodes using the same configuration.
One will only run the indexing facilities while the other will only run the
matching facilities.
One will only run the indexing facilities while the other will only run the matching facilities.

Environment variables respected by the Go standard library can be specified
if needed. Some notable examples:
Expand All @@ -41,10 +39,34 @@ if needed. Some notable examples:
If running in "combo" mode you **must** supply the `indexer`, `matcher`,
and `notifier` configuration blocks in the configuration.

## Configuration dropins

Starting in Clair version `4.7.0`, dropin configuration files are supported.

Given a root configurtaion file of `/etc/clair/config.json`, all files matching the globs `/etc/clair/config.json.d/*.json` and `/etc/clair/config.json.d/*.json-patch` would be loaded in lexical order after the root configuration file.
Similarly, given `/etc/clair/config.yaml`, all files matching the globs `/etc/clair/config.yaml.d/*.yaml` and `/etc/clair/config.yaml.d/*.yaml-patch` would be loaded.
Only the extensions `yaml` and `json` are supported, and indicate yaml and JSON formatting, respectively.

The dropin files must have the same extension and format as the root file.
Dropins with the bare suffix are treated as [merge documents](rfc7386).
Dropins with the `-patch` suffix are treated as [patch documents](rfc6902) and must contain a valid [RFC 6902](rfc6902) structure.
Yaml documents must be resolvable to the JSON subset.

Take care with the [merge](rfc7386) behavior around lists; a patch operation may be more suitable.
The `clairctl check-config` command can be used to ensure a merged configuration is what is intended.
In addition, placing `test` operations in a patch file that's evaluated last (such as `zz-validate.json-patch`) can be used to have Clair refuse to start if some configuration values are not what is intended.

The application defaults are applied *after* the configuration is loaded and as such, not reflected in the `clairctl check-config` command.
The output of that command is also not currently suitable to be used to "compile" a config to a single file.

[rfc7386]: https://datatracker.ietf.org/doc/html/rfc7386
[rfc6902]: https://datatracker.ietf.org/doc/html/rfc6902

## Configuration Reference

Please see the [go module documentation][godoc_config] for additional
documentation on defaults and use.
Please see the [go module documentation][godoc_config] for additional documentation on defaults and use.
Starting in version `4.7.0`, unknown keys are disallowed.
Configurations that looked valid previously and loaded fine may now cause Clair to refuse to start.

[godoc_config]: https://pkg.go.dev/github.com/quay/clair/config

Expand Down Expand Up @@ -633,3 +655,7 @@ Configuration for a prometheus metrics exporter.
a string value

Defines the path where metrics will be served.

* * *

[^1]: Support added in version `4.7.0`.
4 changes: 2 additions & 2 deletions docker-compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ x-anchors:
clair-database:
condition: service_healthy
volumes:
- "./local-dev/clair/${CLAIR_CONFIG:-config.yaml}:/etc/clair.yaml:ro"
- "./local-dev/clair:/etc/clair:ro"
- ".:/src"
# Can't specify the config via environment because maps are not recursively
# merged.
Expand All @@ -30,7 +30,7 @@ x-anchors:
- run
- .
- -conf
- /etc/clair.yaml
- /etc/clair/${CLAIR_CONFIG:-config.yaml}
restart: unless-stopped
working_dir: /src/cmd/clair

Expand Down
2 changes: 2 additions & 0 deletions local-dev/clair/config.yaml.d/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
*
!.gitignore
2 changes: 2 additions & 0 deletions local-dev/clair/quay.yaml.d/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
*
!.gitignore

0 comments on commit eb54b88

Please sign in to comment.