Skip to main content

Validate Gateway Configuration

Before a gateway rollout, use three different checks:

  1. verdictan config validate checks the declarative document structure.
  2. verdictan gateway check resolves runtime configuration and provider credentials.
  3. verdictan policy test runs 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:

verdictan config validate

Validate a different file:

verdictan config validate --file configs/production.yaml

The command parses the document and validates the declarative config. In text mode, validation errors cause a user error and a nonzero exit status. When validation succeeds, the output reports the config version and Result: valid.

For CI, use JSON. Assert that the returned valid field is true:

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

The JSON object contains:

  • file
  • valid
  • config_version
  • schema_version
  • errors

Active JSON mode prints correct JSON. It exits with code zero when valid is false. Do not use the process exit status as the validation gate. Examine valid. If the value is not true, fail the job. If your automation can use only the exit status, use text mode.

Runtime readiness​

After structural validation, resolve the config for the gateway runtime:

verdictan gateway check --config configs/production.yaml

When you investigate provider activation, add --verbose:

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

gateway check reports the resolved config version and digest. It also reports providers, routing strategy, policy chain, and a last Ready or Not Ready result. Unresolved credentials for a necessary provider cause a Not Ready result.

Active gateway check output is human-readable. A Not Ready result returns a nonzero exit status. Automation can use that status as its readiness gate. Keep the command output so that you can identify each unresolved provider or credential.

Run it with the same environment and secret-store access as the specified 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 do these operations:

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

Policy behavior tests​

After the config is structurally correct, run pack and inline tests:

verdictan policy test --pack-dir .

Use --json in automation. A failed test returns a nonzero exit status. Correct YAML does not change this result.

Use this sequence locally and in deployment automation:

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

In this sequence, explicitly assert valid == true for the first JSON result. The last command returns success only when it reports Ready.

Then start a bound gateway. Send a representative request through it:

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

GET /healthz shows only that the gateway process is healthy. Send a request from a supported request family. Use the result to verify provider routing and policy behavior.

Select the correct validator​

QuestionCommand
Is this declarative document structurally correct?verdictan config validate
Is this file a correct runtime or IAM policy document?verdictan policy lint --mode auto
Can this environment resolve provider credentials?verdictan gateway check
Do the declared policy cases give the specified results?verdictan policy test
Is a running process alive?GET /healthz
Does a representative governed model request work?Send a representative request through the gateway.

Next steps​