From eb54b8896f6fd93bd67d6b6c0875cfff426698d7 Mon Sep 17 00:00:00 2001 From: Hank Donnay Date: Mon, 3 Jul 2023 11:33:26 -0500 Subject: [PATCH] docs: add dropins to prose documentation This change explains how to use the dropins and updates the local-dev config to do so. Closes: #1783 Signed-off-by: Hank Donnay --- Documentation/reference/config.md | 40 +++++++++++++++++++----- docker-compose.yaml | 4 +-- local-dev/clair/config.yaml.d/.gitignore | 2 ++ local-dev/clair/quay.yaml.d/.gitignore | 2 ++ 4 files changed, 39 insertions(+), 9 deletions(-) create mode 100644 local-dev/clair/config.yaml.d/.gitignore create mode 100644 local-dev/clair/quay.yaml.d/.gitignore diff --git a/Documentation/reference/config.md b/Documentation/reference/config.md index d7439efe3d..5f4743b024 100644 --- a/Documentation/reference/config.md +++ b/Documentation/reference/config.md @@ -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 @@ -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: @@ -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 @@ -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`. diff --git a/docker-compose.yaml b/docker-compose.yaml index 7ccb4a9ba6..8e15472be3 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -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. @@ -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 diff --git a/local-dev/clair/config.yaml.d/.gitignore b/local-dev/clair/config.yaml.d/.gitignore new file mode 100644 index 0000000000..d6b7ef32c8 --- /dev/null +++ b/local-dev/clair/config.yaml.d/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore diff --git a/local-dev/clair/quay.yaml.d/.gitignore b/local-dev/clair/quay.yaml.d/.gitignore new file mode 100644 index 0000000000..d6b7ef32c8 --- /dev/null +++ b/local-dev/clair/quay.yaml.d/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore