Skip to main content

Policies

Managing Policy Changes

A change to a rule can block traffic that your application needs, or allow traffic that it must not. This page takes a change from a draft file to a canary, a small first rollout, and then to more gateways. At each step you keep the last version that worked, so that you can go back.

Use this page for a gateway that already runs a configuration. For your first file, see Manage configuration in a file.

Before you start​

  • Know the gateways, agent, environment, provider targets, and request families that the change affects.
  • Keep the last good YAML, its configuration version, and its digest.
  • Agree who deploys the change and who can roll it back.
  • Write at least one request that the rules must allow and one that they must block or redact. Add routing and escalation cases if those behaviors change.
  • Use the same provider environment and secret access that the target gateway service has.
  • Have two tokens: a gateway runtime token for VERDICTAN_API_TOKEN, and a client API token for VERDICTAN_CLIENT_TOKEN. Do not use a provider key as either token.

1. Define success and rollback gates​

Write these down before you edit the file:

  • The requests that the gateway must allow, block, redact, or escalate.
  • The provider and model for each routed request.
  • How much the block rate, error rate, latency, and review volume can change.
  • How long the canary runs.
  • What makes you roll back, and what makes you stop to investigate.

Record a baseline from the current version: request IDs and event JSON from verdictan events tail --since <window> --json or GET /v1/events?since=<window>. Events and request IDs are the evidence of runtime decisions. Use History only when capture is on and you need the session content.

2. Validate the draft​

Run these checks in the pack directory. Each one must pass:

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 --verbose
CheckProvesDoes not prove
config validateThe document parses and has a valid structure.Credentials or policy results
policy lintThe file is a valid runtime policy document.That allow and block results are correct
policy testThe JSON tests in tests/ and the inline testing.suites cases give their expected results.Live routing or application connectivity
gateway checkThe file resolves with the current environment, provider credentials, routing, and policy chain. It prints the version and SHA-256 digest.A provider call, a deployment, or a live request

Run gateway check with the environment of the target service. A check can pass in your shell and fail in the service if the service has different variables or secret access.

3. Send representative traffic​

Use an agent and gateway that are only for tests. A deployment goes to every gateway of the agent that you select.

  1. Restart the test gateway with its usual command and the provider variables of the target service. The gateway reads provider credentials from its own environment.
  2. Increase pack.version in the draft, so that you can identify it in the gateway log.
  3. Deploy the draft to the test agent in Configurations. Try the change on a test gateway has the steps.
  4. In the gateway log, wait for connected read model refresh applied updated config with your new config_version. The gateway pulls its configuration every 30 seconds.

To deploy from your terminal, use Deploy from the CLI with CLI 0.1.14 or later. Select the test gateway with --gateway-id. Do not use gateway run --policy-config, which calls unsupported API routes.

In another terminal, send a request with a client API token for that agent and a model from the draft. Change the URL if your gateway listens on a different address:

export VERDICTAN_CLIENT_TOKEN="<client-api-token>"
export VERDICTAN_TEST_MODEL="<configured-model-id>"
export VERDICTAN_TEST_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4().hex)')"

curl -i http://127.0.0.1:41002/v1/chat/completions \
  -H "Authorization: Bearer ${VERDICTAN_CLIENT_TOKEN}" \
  -H "X-Request-Id: ${VERDICTAN_TEST_REQUEST_ID}" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"${VERDICTAN_TEST_MODEL}\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Reply with the word Hello.\"}
    ]
  }"

Keep the status, the body, and the X-Request-Id header. Then, in a CLI terminal signed in with an account that has events:read, find the event with that request ID:

verdictan events tail --since 10m --json

Repeat for each allow, block, redact, and escalation case, with a new request ID each time. For each case, examine the verdict, the reason code, the configuration version, and the gateway or agent. If the gateway called a provider, also examine the provider and the model.

Also send one request with an invalid client token. The gateway must reject it before it calls a provider.

If no matching event arrives, stop. Examine the region, the control-plane connection of the gateway, and whether the request family records evidence. An empty History view does not prove that no request occurred.

4. Review the rollout gate​

Deploy only when all of these are true:

  • The change is inside the approved scope.
  • The allow, block, and redact cases pass, and the routing and escalation cases pass where they apply.
  • The provider metadata for retention or routing matches what you need.
  • A reviewer approved the version, target agent and its gateways, observation window, and rollback criteria.
  • The last good configuration is available, and the rollback owner is available.
  • The team can watch Gateways, events, the Inbox queues, and application health during the window.

Deploy to one representative canary first. A deployment goes to every gateway of the selected agent, so the canary needs its own agent. A saved version in Configurations is not a deployment, and Deployment complete does not prove that the gateway applied the reviewed content.

5. Verify the deployed runtime​

With gateway 0.1.14 or later, check Sync in Gateways before you send test traffic. Wait for In sync. See configuration sync status if another state remains. This status proves configuration agreement. It does not replace the request tests or the observation period.

Use the version that gateway check printed for the reviewed file. The canary must log connected read model refresh applied updated config with that config_version. You can also ask the gateway directly:

export EXPECTED_CONFIG_VERSION="reviewed-version"

verdictan gateway config \
  --gateway-url http://127.0.0.1:41002 \
  --expect-version "${EXPECTED_CONFIG_VERSION}"

The Console can reformat the YAML when it saves a version. This can change the digest from the value that gateway check printed for your file. Compare the version. Record the digest that the gateway reports.

If the gateway protects its admin endpoint, set VERDICTAN_API_TOKEN first. Then send the representative requests again and match their events. Compare verdicts, routing, errors, latency, and review volume with the baseline for the whole window before you add more gateways.

WhereWhat it tells you
GatewaysRuntime health, connection state, and configuration sync status
The gateway logThe config_version of each configuration pull
verdictan events or GET /v1/eventsDecisions and routing for each request ID
InboxHuman review volume and outcomes
TrailThe order of rollout and follow-up actions
HistorySession content, when capture is on

6. Pause or roll back​

Stop adding gateways if the version check fails, evidence is missing, or a metric goes past its limit. Investigate before you decide that the new rule is the cause.

Roll back when one of your agreed triggers occurs, for example:

  • The rules allow a request that is not safe, or block a necessary business flow.
  • Routing selects the wrong provider, model, or retention setting.
  • The canary has errors or latency above the approved limit for a long time.
  • Review volume is more than the team can handle.
  • The deployed version is not the approved one.

To roll back:

  1. Stop adding gateways. Keep the request IDs, event JSON, active version, and digest.

  2. Deploy the last good YAML through the same reviewed workflow. In Configurations, save it as a new version with a higher pack.version. Deploy it to the agent of the affected gateways.

  3. If you changed a named local gateway with verdictan gateway reload, you can use its stored rollback target:

    verdictan gateway revert \
  --name verdictan-proxy \
  --gateway-url http://127.0.0.1:41002

  4. Run verdictan gateway config again with the pack.version that you deployed in step 2. Send the representative requests again. Match their events.

  5. Record the trigger, the decision, the restored version, the request IDs, and the evidence in the change record.

Verdictan does not roll back policy changes for you. verdictan gateway reload restores the previous configuration only when activation fails immediately and a rollback target exists. After a completed reload, a Console deployment, or a deployment to many gateways, use the steps above.

Next steps​