Configurations

A configuration is the YAML that tells a gateway which models to call and which rules to apply. In Configurations in the Console, you edit that YAML, save versions of it, and deploy a version to the gateways of an agent.

Saving a version does not change a gateway. Only a deployment does.

Before you start

• Permission to edit configurations and to deploy to the target agent.
• An agent with a connected gateway.
• The provider keys that the configuration refers to, available to that gateway.

To write the YAML in your own repository first, see Manage configuration in a file.

Create or edit a configuration

1. Open Configurations.
2. For a new configuration, select Create Configuration. To change a saved configuration, open it. Then select Edit.
3. Paste your YAML into the editor, or select Import Configuration to load a local file.
4. Correct the validation errors that show next to the editor.
5. Select Next to review the changes.

On the review step, you can save the version without a deployment. For a new configuration, select Save as Draft. For a saved configuration, select Save changes. To deploy the version, use the steps below.

Refer to provider keys by name. Do not paste a key into the YAML. See Secret references.

Deploy a version

Before you deploy, increase pack.version in the YAML. The gateway logs this value as config_version when it applies the configuration.

1. On the review step, under Deploy to agent, select the Agent. The summary shows the number of gateways of that agent.
2. Examine the changes. Then select Deploy.
3. In Deployment approval, make sure that the number of target gateways is correct. Select Deploy to n gateways.
4. Wait for Deployment complete.

The version goes to each gateway of the agent. Each gateway pulls its configuration every 30 seconds. It can take up to 30 seconds to load the new version. A gateway that is offline loads it when it connects again.

Verify the deployment

For deployment from a local file, use CLI 0.1.14 or later. It can select one gateway or all gateways of an agent. Use the checks below after either CLI or Console deployment.

1. Open Gateways in the Console.
2. Examine Sync for each gateway that received the deployment.
3. Wait for In sync.
4. Send one request that the new rules allow.
5. Send one request that the new rules block.

Use gateway 0.1.14 or later for configuration reports after a reload. The gateway checks for changes about every 30 seconds. Its next heartbeat reports the applied configuration.

Status	Meaning	Action
In sync	The recent gateway reports match the assigned configuration that the API serves.	Send the test requests. This status does not prove provider access or correct policy results.
Pending	A new assignment or configuration is within the 60-second reporting period.	Wait for the next configuration check and heartbeat.
Out of sync	The gateway has not reported the assigned configuration within that period.	Examine the gateway log and its connection to the API.
Unknown	The API has no usable configuration report, or the report is more than 90 seconds old.	Check the gateway version and connection.

The configuration detail page also shows the combined status of its target gateways. If gateways have different states, it shows Out of sync, then Pending, then Unknown, before In sync.

For an older gateway, check the log after a configuration change. Find connected read model refresh applied updated config with the new config_version. Record the config_sha256. Then send the test requests.

Find the two requests and their decisions in History when capture is on. You can also read the delivered events with your signed-in CLI profile:

verdictan events tail --since 10m --json

Trail records the deployment.

Compare or restore versions

Open a configuration and select the Versions tab. It lists each saved version with its source, SHA-256 digest, and save time. Under Compare versions, select a base version and the version to compare.

The History tab shows the rollout timeline: each saved version and each deployment, in time order.

To go back to an earlier version, deploy its content again:

1. In Versions, find the version that worked and copy its YAML.
2. Select Edit. Replace the YAML with the copy.
3. Select Next, then Deploy.
4. Do the checks in Verify the deployment.

Keep the earlier version until the tests of the new version pass.

Secret references

A configuration never contains a provider key. Each provider target refers to the key with secret_key_ref, which takes exactly one source:

Inside a provider target

secret_key_ref:
  env: VERDICTAN_OPENAI_API_KEY      # an environment variable on the gateway host

Inside a provider target

secret_key_ref:
  store: OPENAI_API_KEY              # a secret saved in Secrets

If the gateway cannot resolve the reference, it stops with an error such as secret_key_ref could not be resolved. Check these items:

• The reference has one of env or store, not both and not neither.
• For env, the variable is set and not empty in the process or container that runs the gateway.
• For store, the secret exists in Secrets and the agent has access to it.

Connect your model provider describes each source.

Provider routing

The gateway sends a request to a provider target whose model matches the model in the request. A target matches when:

• its model is the same as the request model, or the request uses the form <provider>/<model>,
• its model is *, which accepts any model, or
• an enabled entry in its models list has that model_id or alias.

If no target matches, the request fails with No provider matched model '...'. The message lists the patterns and targets that the gateway tried. Change the request model or add a matching target. Provider Configuration describes the target fields.

Troubleshooting

Problem	Action
Deploy is not available.	Correct the validation errors, select an agent, and examine your deployment permissions.
The gateway does not log the new config_version within 30 seconds.	Open Gateways. Examine the last connection time. Connect each offline gateway again. Make sure that the gateway belongs to the agent that you deployed to.
The gateway logs the new version, but requests behave as before.	Make sure that the requests go to that gateway, and that pack.version changed with the rules. See Managing Policy Changes.
A provider credential fails.	Examine the secret reference. On the gateway host, run verdictan gateway check --config policy-config.yaml.

Delete configurations

Select the configurations in the list and select Delete selected configurations. First make sure that no agent uses them. Do not delete a configuration to go back to an earlier version. Deploy the earlier version instead.

Next steps

• Roll Out a New Template: start from a template.
• Declarative Config Reference: find the meaning of each field.