Feature request: add json schema to validate the daemon settings

[jdrouet]

Description

In docker cli, we already embed a json schema for docker compose, maybe we should have one also for the daemon settings.

Describe the results you expected:

Have a JSON Schema file with the settings definition

[thaJeztah]

This change would be in the moby repository (which is where the daemon CLI lives), but yes, I definitely agree we need something for this. From https://github.com/moby/moby/pull/34093#issuecomment-316698133

However (without having deep-dived into the code) I have a feeling we're reinventing the wheel; I think we're looking at properly validating the daemon.json; the format is currently "badly" documented (just the example JSON in https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file), which could use some improvement overall.

Would it be an idea to define a JSON schema for the configuration file, and use that for validating? Possibly we can use the schema itself to generate documentation as well (which would be a win-win)

Some related issues;

• https://github.com/moby/moby/pull/34093 ("warn for unknown options")
• https://github.com/moby/moby/issues/21559 ("How to check docker daemon options when using daemon.json")
• https://github.com/moby/moby/issues/34673 Feature request: Make json files diffable
  • https://github.com/moby/moby/pull/34838 / https://github.com/moby/moby/pull/35640 Add support to TOML format in configuration file
• https://github.com/moby/moby/issues/20151 Use daemon-config.json in standard installs
• https://github.com/moby/moby/issues/25471 ("Conflict between default -H fd:// systemd config and daemon.json hosts config")
• https://github.com/moby/moby/issues/25508 ("Allow querying of daemon's log-driver and log-opt via remote API ")
• https://github.com/moby/moby/issues/36911 Dockerd needs a 'validate config' option
  • https://github.com/moby/moby/pull/38138 Add configuration validation option
• https://github.com/moby/moby/issues/32530 ("daemon.json parsing ignores unknown fields")
  • https://github.com/moby/moby/pull/34093 Warn about unknown options in the config file
  • discusses JSON-schema as a possible approach; https://github.com/moby/moby/pull/34093#issuecomment-316698133
• https://github.com/moby/moby/pull/29692#issuecomment-348608853 (Docker for Mac being out of sync with actual supported options)
• https://github.com/docker/cli/issues/1058 Generate compose file reference from JSON-schema
  • s/compose file/daemon config/

[thaJeztah]

One thing to take into account is daemon upgrades/downgrades may invalidate existing configuration files; we should either "error", or "warn" on those

[jacobseth]

Hey there, could I have a go at this?

[thaJeztah]

@jcsirot did you already have a json-schema created? ^^

[jcsirot]

Well, I don't know. Maybe you wanted to ask @jdrouet :-D

[peter-curiousit]

For anyone like me looking for something to help write the daemon.json file, I found this: https://json.schemastore.org/dockerd.json

I'm not sure how accurate it is so YMMV

[jrandall]

For anyone like me looking for something to help write the daemon.json file, I found this: https://json.schemastore.org/dockerd.json

I'm not sure how accurate it is so YMMV

I've found this helpful, thanks! However, to maximise usefulness in a validation setting, it should be made more strict by adding "additionalProperties": false at the top-level.

e.g.

# curl -sLf "https://json.schemastore.org/dockerd.json" | jq '. += {"additionalProperties": false}' > /tmp/dockerd.jsonschema
# pipx run check-jsonschema --schemafile /tmp/dockerd.jsonschema /tmp/daemon.json
Schema validation errors were encountered.
  /tmp/daemon.json::$: Additional properties are not allowed ('default-address-pool' was unexpected)

Without "additionalProperties": false, a daemon.json with the default-address-pool: [...] issue validates as ok (while that list of values is silently ignored as mentioned in https://github.com/moby/moby/issues/43128).

[akerouanton]

@jrandall Did you try dockerd --validate? (see this docs page)