Skip to content

Validate config with a program

This page is for an image author whose kind has constraints that a schema or a CEL rule cannot express, or can express only at great cost. At the end a validator, a program of the image, checks the node's documents before a delivery changes anything, and the operator sees which document and field it refuses. The example reads the Hardware and Rack kinds of the extensions example, and refuses a Hardware document on a node that has no Rack.

A validator reads the documents of the kinds it names and prints the refusals it finds. chalkd runs every validator after the change rules and before the outputs render. A refusal, or a validator that fails, refuses the whole delivery, and the node keeps the config it runs.

See it in a full extension: Refuse an interface the node does not configure of the BGP guide checks bird's interfaces against the node's Network documents.

Before you begin

You need a kind of your own, as Declare a config kind declares one. Prefer a rule where one does the job: Guard changes with rules and facts shows rules, which chalkctl checks too, before it sends anything. A validator suits a check that needs a program: a parser, a tool, data of the image's own, or a computation over many documents.

Declare the validator

chalkos.validators.<name> declares a validator:

chalkos.validators.hardware-rack = {
  inputs = [ "Hardware" "Rack" ];
  program = chalkosLib.validate.jq ./hardware-rack.jq;
};

The declaration sets two things:

  • inputs names the kinds whose documents the validator reads, here Hardware and Rack.
  • program is the validator: here a jq program.

The name is lower-case letters, digits and dashes, as an output's.

Read the validator's input

chalkd appends validate hardware-rack to the command, and writes one JSON object to the program's standard input: the input a renderer reads, as Program input describes. On a node named example that holds a Hardware and a Rack, the object reads, indented here:

{
  "documents": {
    "Hardware": [
      {"apiVersion": "hardware.example.org/v1alpha1", "kind": "Hardware", "metadata": {"name": "hardware"},
       "spec": {"assetTag": null, "model": "SYS-E300-9D", "vendor": "Supermicro"}}
    ],
    "Rack": [
      {"apiVersion": "rack.example.org/v1alpha1", "kind": "Rack", "metadata": {"name": "rack"},
       "spec": {"location": "rack-a/u12"}}
    ]
  },
  "node": {"name": "example"}
}

A validator refuses a config by printing one JSON object on standard output, the report of refusals that a renderer prints too:

{"refusals": [{"kind": "Hardware", "name": "hardware", "path": "metadata.name", "message": "a node with a Hardware document needs a Rack document, which says where the server is mounted"}]}

Each refusal names the document by kind and name, the field by its path, and says in message what is wrong and how to fix it. Any refusal refuses the delivery. Refusal report gives the rules of each field and of the report, which a validator and a renderer share.

Validate with a jq program

chalkosLib.validate.jq turns a jq program into a validator: jq reads the input, and what the program outputs is the report. hardware-rack.jq refuses the Hardware document of a node whose input holds no Rack:

hardware-rack.jq
# Refuses Hardware documents on a node without a Rack document.
{
  refusals: [
    if (.documents.Hardware | length) > 0 and (.documents.Rack | length) == 0 then
      {
        kind: "Hardware",
        name: .documents.Hardware[0].metadata.name,
        path: "metadata.name",
        message: "a node with a Hardware document needs a Rack document, which says where the server is mounted"
      }
    else empty end
  ]
}

A template can refuse the same config, as Refuse a config from the renderer shows, but the validators run before the renderers, so the operator sees the validator's refusal.

Validate with any program of the store

program also takes a package or a command line of the store, to which chalkd appends validate and the validator's name. A script made by pkgs.writeShellScript reads the input from standard input and prints the report with echo or jq:

chalkos.validators.hardware-rack.program = pkgs.writeShellScript "hardware-rack" ''
  exec ${lib.getExe pkgs.jq} -c -f ${./hardware-rack.jq}
'';

A Go program, or one in any other language, works the same way: read the input, print the report, exit 0. A program that serves as a renderer too reads the same input in both roles.

Test the validator

A test of chalkos.tests runs every validator on a config file, as chalkd does for a delivery, and compares the refusals with those the test expects. A test that expects none expects the config accepted. nix flake check runs the tests, so a jq program with a syntax error, or one that refuses a config it should accept, fails there before any node gets the image. Cover each branch of the program: a config it accepts, and one per refusal. For hardware-rack, that is a node with both kinds, one with a Hardware alone and one with neither.

Check that it worked

Run the tests:

nix flake check

This test gives the node a Hardware without a Rack, and expects the refusal of the report above:

chalkos.tests.hardware-without-rack = {
  config = ./tests/hardware-without-rack.yaml;
  refusals = [
    {
      kind = "Hardware";
      name = "hardware";
      path = "metadata.name";
      message = "a node with a Hardware document needs a Rack document, which says where the server is mounted";
    }
  ];
};

A validator that fails, or whose refusals differ from those the test expects, fails the test with a FAIL line of the refusals it expected and those it got, as Test an extension shows.

On a node, chalkctl config apply checks the config as far as chalkctl can and prints what changed. Then the node runs the validator and refuses the delivery, and chalkctl prints the node's refusal after the config is refused:. The node changed nothing. chalkctl config apply --dry-run prints the same refusal without a delivery.

chalkctl validate accepts such a config: chalkctl runs only the validators it links, the router layer's router on router images, and an image's own validator runs on the node alone.

If it fails

A validator that fails names itself and its exit status. Each run is a transient unit, chalkos-render-<n>.service, whose journal holds what the program wrote to standard error, and the journal of chalkd.service names the unit beside the failure:

chalkctl logs server1 --unit=chalkd.service
chalkctl logs server1 --unit=chalkos-render-<n>.service

chalkctl config apply while an image is staged, with or without --staged, and chalkctl upgrade run the validators of the image the config is for, from that image's store, in chalkos-check.service. So does chalkctl install on a machine that runs the installer, once the image's store is on the target disk.

A validator runs in the renderers' sandbox, within its limits of time and space.

Built into chalkos

A router image declares the validator router. It checks what the router kinds' documents and the Network documents mean together: which links networkd puts in which VRF, and those links against the firewall's zones, the NAT rules, the management interfaces, the policy routes' in, the BGP peers, the NAT64s, the resolvers and the DHCP subnets and relays. chalkctl links the same code, so chalkctl validate and chalkctl config apply run it before they send anything, and the node runs it again as chalkos-render validate router. It refuses the VRFs' links first. The checks that read the links run once those pass, and report every fault they find at once.

The router guide lists its messages and their fixes, beside those of the renderers, which run on the node alone:

What next