Field Validation

The services on the gechologcontainer support a --validate option for configuration files. This enables users to validate the changes to the configuration file before uploading/applying them. Supported services:

Validate configuration file for nats2file using the nats2log validation command.

Validation in web interface

For configuration files that can be managed via the web interface (see web interface supported files), the validation information is display next to each field and automatically updated as changes are made to the configuration file.

Overall validation information

The web interface displays the current overall validation status of the edited validation file, and also for each main area of the configuration file. Areas that have rejected fields are also outlined.

Validation information helps guide the user to what fields are invalid, and in this example why a router is rejected.

NOTE: For the license file field, valid means that the file exists. For verification of the license expiration see License.

Run validation via command line

In these examples we are using nats2log.

Validate a config file on the container

If the new configuration files is accessible from the container, such as via a mounted volume, run this command:

docker exec gecholog ./nats2log -o app/conf/new_nats2log_config.json --validate

az container exec --resource-group <RESOURCE_GROUP> --name gecholog --container-name gecholog --exec-command "./nats2log -o app/conf/new_nats2log_config.json --validate"

Validate a local config file

We can also pipe stdout to stdin for config validation which enables us to test a local config file without copying it to the container.

type new_nats2log_config.json|docker exec -i gecholog ./nats2log --validate

cat new_nats2log_config.json|docker exec -i gecholog ./nats2log --validate

Successful validation

The INFO response indicates that the configuration file is valid. All the accepted configurations are listed in the message.

{
  "time": "2024-02-19T16:22:34.381111324Z",
  "level": "INFO",
  "source": {
    "function": "main.setupConfig",
    "file": "/app/standardlibrary/nats2log/nats2log.go",
    "line": 1218
  },
  "msg": "configuration file valid",
  "service": "nats2log",
  "configuration": "mode:file_writer log_level:INFO retries:3 service_bus:hostname:localhost:4222 topic:coburn.gl.nats2file topic_logger_exact:coburn.gl token:[*****MASKED*****] tls:insecure:false system_cert_pool:true cert_files:[] filename:/app/log/gecholog.jsonl write_mode:append"
}

NOTE: A configuration file CAN be valid but still have invalid fields that are not accepted. The invalid fields are listed in a separate rejected fields message. So its important to review both the accepted and rejected parts of the configuration.

A successful configuration file validation returns a zero exit code:

echo $?                                                                                                     
0

Rejected fields

Rejected fields are indicated with a WARN type. Rejected fields are listed with a short explanation why the field is rejected. A rejected field in a nested object can invalidate the entire object, so make sure you inspect the accepted configuration list to confirm that you changes have been approved.

{
  "time": "2024-02-19T16:22:34.381177875Z",
  "level": "WARN",
  "source": {
    "function": "main.setupConfig",
    "file": "/app/standardlibrary/nats2log/nats2log.go",
    "line": 1224
  },
  "msg": "configuration has rejected fields",
  "service": "nats2log",
  "rejected_fields": {
    "nats2log_config.AzureLogAnalyticsWriter.azureLogAnalyticsWriter.SharedKey": "required:",
    "nats2log_config.AzureLogAnalyticsWriter.azureLogAnalyticsWriter.WorkspaceID": "required:",
    "nats2log_config.ElasticWriter.elasticWriter.Password": "required:"
  }
}

Failed validation

If the validation command produces ERROR, the configuration file is not valid and forcing a restart with an invalid configuration have the effect that the service, in this example nats2log, will not start and will be deactivated.

This is an example of ERROR message where nats2log cannot accept the validation file since there are issues with azure_log_analytics_writer which is not acceptable since the mode=azure_log_analytics_writer.

{
  "time": "2024-02-19T16:28:12.766971153Z",
  "level": "ERROR",
  "source": {
    "function": "main.setupConfig",
    "file": "/app/standardlibrary/nats2log/nats2log.go",
    "line": 1209
  },
  "msg": "configuration file validation failed",
  "service": "nats2log",
  "validation_errors": {
    "nats2log_config_v0921.AzureLogAnalyticsWriter": "required_if:Mode azure_log_analytics_writer"
  }
}

A failed configuration file validation returns a non-zero exit code:

echo $?                                                                                                     
1

Environment variable context when validating config file

The command

type new_nats2log_config.json|docker exec -i gecholog ./nats2log --validate

cat new_nats2log_config.json|docker exec -i gecholog ./nats2log --validate

executes nats2log config file validation inside the docker container, where the environment variables set for the container apply. Assume that our new local configuration file uses a new environment variable MY_VAR that currently isn't set within the container. To avoid config validation errors due to missing env variables you can adjust your validation command like this:

type new_nats2log_config.json|docker exec -i -e MY_VAR=your_value gecholog ./nats2log --validate

cat new_nats2log_config.json|docker exec -i -e MY_VAR=your_value gecholog ./nats2log --validate

Invalid field descriptions

Most configuration requirement errors are self-explanatory like required or min=0. Some require a little bit more explanation:

Nats config validation

Also nats-server allows you to validate your nats configuration:

docker exec gecholog ./nats-server -c /app/conf/new_nats-server.conf -t

az container exec --resource-group <RESOURCE_GROUP> --name gecholog --container-name gecholog --exec-command "./nats-server -c /app/conf/new_nats-server.conf -t"

Which prints

nats-server: configuration file /app/conf/new_nats-server.conf is valid

For more information about nats, visit nats.io.