Skip to main content

Validate Gateway Configuration

Use three different checks before a gateway rollout:

  1. kt config validate checks the declarative document structure.
  2. kt gateway check resolves runtime configuration and provider credentials.
  3. kt policy test executes the config's policy test cases.

These checks answer different questions. Passing one does not imply that the others will pass.

Structural validation​

Validate the default file:

kt config validate

Validate another file:

kt config validate --file configs/production.yaml

The command parses the document and runs declarative-config validation. In text mode, validation errors produce a user error and nonzero exit status; successful output reports the config version and Result: valid.

For CI, use JSON and assert that the returned valid field is true:

kt config validate \
  --file configs/production.yaml \
  --json

The JSON object contains:

  • file
  • valid
  • config_version
  • schema_version
  • errors

Current JSON mode prints a valid JSON result and exits successfully even when valid is false. Do not treat its process exit status as the validation gate; inspect valid and fail the job when it is not true. If an automation environment can rely only on exit status, use text mode instead.

Runtime readiness​

After structural validation, resolve the config as the gateway would:

kt gateway check --config configs/production.yaml

Add --verbose when diagnosing provider activation:

kt gateway check \
  --config configs/production.yaml \
  --verbose

gateway check reports the resolved config version and digest, active and inactive providers, routing strategy, policy chain, and a final Ready or Not Ready result. Required providers whose credentials cannot be resolved make the check not ready.

Current gateway check output is human-readable and a Not Ready result does not by itself make the process exit nonzero. Do not use its exit status alone as a readiness gate; assert the reported result or run a wrapper that does so.

Run it with the same environment and secret-store access as the intended gateway service. A shell check can pass while an installed service fails if the service does not receive the same environment.

gateway check does not:

  • start a gateway;
  • contact a model provider with a sample inference;
  • deploy a configuration to the control plane; or
  • prove that application traffic reaches the gateway.

Policy behavior tests​

Run pack and inline tests after the config is structurally valid:

kt policy test --pack-dir .

Use --json in automation. A failed test returns a nonzero exit status even when the YAML itself is valid.

Use this order locally and in deployment automation:

kt config validate --file policy-config.yaml --json
kt policy lint --mode runtime --file policy-config.yaml
kt policy test --pack-dir . --json
kt gateway check --config policy-config.yaml

In this sequence, explicitly assert valid == true for the first JSON result and assert that gateway check reports Ready.

Then start a bound gateway and send a representative request through it:

kt gateway run \
  --agent docs-validation \
  --policy-config policy-config.yaml \
  --listen 127.0.0.1:41002

Checking /healthz confirms only that the gateway process is healthy. Verify an actual supported request family to prove provider routing and policy behavior.

Choosing the right validator​

QuestionCommand
Is this declarative document structurally valid?kt config validate
Is this file a valid runtime or IAM policy document?kt policy lint --mode auto
Can provider credentials be resolved in this environment?kt gateway check
Do the declared policy cases produce expected outcomes?kt policy test
Is a running process alive?GET /healthz
Does a real governed model request work?Send a representative request through the gateway.

Next steps​