Summary
There is no way to check a gateway.yaml / endpoints/ / topology.properties set without
starting the runtime. The configuration surface is large and fail-closed, so an invalid document is
found by a container that refuses to boot rather than by a pipeline step.
What an adopter ends up doing
Standing up a new deployment, I wanted the configuration checked before it reached a host. The best
available approach was to run the shipped JSON schemas myself:
Draft202012Validator(json.load(open("gateway.schema.json"))).iter_errors(doc)after resolving the ${VAR} placeholders by hand, because the schemas see resolved values while the
files carry placeholders.
That catches structural mistakes — unknown keys, wrong types, missing required fields. It does not
catch the rules that are actually easy to get wrong, because they are cross-document and live in
ConfigValidator:
- anchor
path_prefix pairwise disjointness (and its segment-wise, not string-prefix, semantics)
- route-to-anchor namespace membership
- the access→auth matrix
- topology alias resolvability
- same-prefix route disjointness
Those are the ones an adopter gets wrong. In my case the design turned out correct, but I only knew
that after pulling an image and reading a boot log.
Why it matters here more than for most projects
The boot is deliberately fail-closed and aggregates every violation in one pass — which is excellent
behaviour, and exactly what makes it valuable outside the runtime too. All the machinery already
exists; what is missing is a way to invoke it without a running gateway.
Suggestion
A validate-and-exit mode would be enough — for example --validate-config on the runner, exiting
non-zero and printing the same aggregated violation list. That makes a configuration change gateable
in CI, and it lets an operator check a change before restarting a live gateway.
A small standalone validator artifact would serve the same purpose if a flag on the native runner is
awkward.
Summary
There is no way to check a
gateway.yaml/endpoints//topology.propertiesset withoutstarting the runtime. The configuration surface is large and fail-closed, so an invalid document is
found by a container that refuses to boot rather than by a pipeline step.
What an adopter ends up doing
Standing up a new deployment, I wanted the configuration checked before it reached a host. The best
available approach was to run the shipped JSON schemas myself:
after resolving the
${VAR}placeholders by hand, because the schemas see resolved values while thefiles carry placeholders.
That catches structural mistakes — unknown keys, wrong types, missing required fields. It does not
catch the rules that are actually easy to get wrong, because they are cross-document and live in
ConfigValidator:path_prefixpairwise disjointness (and its segment-wise, not string-prefix, semantics)Those are the ones an adopter gets wrong. In my case the design turned out correct, but I only knew
that after pulling an image and reading a boot log.
Why it matters here more than for most projects
The boot is deliberately fail-closed and aggregates every violation in one pass — which is excellent
behaviour, and exactly what makes it valuable outside the runtime too. All the machinery already
exists; what is missing is a way to invoke it without a running gateway.
Suggestion
A validate-and-exit mode would be enough — for example
--validate-configon the runner, exitingnon-zero and printing the same aggregated violation list. That makes a configuration change gateable
in CI, and it lets an operator check a change before restarting a live gateway.
A small standalone validator artifact would serve the same purpose if a flag on the native runner is
awkward.