Help › Guide
Reconciliation checks
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
Two systems often hold the same records: an inventory and an IPAM both know each device's address. A reconciliation check reads both through operations you already have, matches their records by an exact key, and says where they disagree. It writes to neither. A correction is a separate step that you, or on a server a second person, approve.
A check
A check is a small file:
reqlyn: 1
check:
name: inventory against ipam
left:
operation: Inventory devices
step: devices
items: items
key: address
label: inventory
right:
operation: IPAM addresses
step: addresses
items: items
key: address
label: ipam
fields:
- name: device
left: hostname
right: device
owner: left
fix:
operation: Correct IPAM device
key: address
value: device
fresh:
side: right
at: updated_at
most_days: 90
leftandright: each side's operation, the step whose response holds the records, where the list is in that response (items; empty when the response is the list), the field each record is known by (key) and what the side is called in findings (label). A check reads the records a step received, not the operation's output.fields: each field both sides hold, its name on each side, and which side owns it, whose value is right.fix, when there is one, names the operation that writes the owner's value to the other side, and which of its inputs take the record's key and that value.fresh: how old one side's records may be, by a field holding when each was last changed (RFC 3339).
Running it
reqlyn check save inventory-ipam.yaml
reqlyn check list
reqlyn check run "inventory against ipam"
run runs both operations on this computer and prints, each with its record and where it came from:
- matched: the same key on both sides, owned fields agreeing;
- missing: a key held by one side only;
- duplicate: a key held twice on one side (its fields are then not compared);
- conflict: an owned field that disagrees, with both values and the side that owns it;
- stale: a record older than
freshallows.
Only exact keys match. Nothing is matched by being similar.
On the desktop
Checks, the shield on the rail, lists the checks kept on this computer. Choosing one runs it and shows a summary ("4 inventory and 5 ipam. 6 to review, 0 dismissed. Nothing was written to either.") and each finding as its kind, its key and a sentence.
- Keep or Dismiss each finding; dismissed ones are behind "Show dismissed", and Undo takes either back.
- Pairing: "Not the same record" unpairs a match; "Pair them" pairs two records whose keys differ, and "Unpair" undoes it. Reqlyn suggests near-misses (keys equal once case and separators are set aside, or records holding the same owned value), but a suggestion changes nothing until you pair it.
- Plan fixes, for a check whose fields name fixes: runs the check again and lists, under PLAN, each write as a sentence, "through <operation>", and what it would send; each finding not planned says why (a missing record is for a person to add or remove; which of a duplicate is right is a person's call; an old record is confirmed by its owner). "Write it" (or "Write all N") sends the writes one after another, then runs the check again: each written finding reads "Resolved", "Unresolved, written and found again" or "Unresolved, not written" with why.
Overrides and reviews stay on this computer.
On a server
A check can be published over two published versions that only read, in one environment:
reqlyn remote check publish inventory-ipam.yaml --environment lab --versions 3 2
reqlyn remote checks
reqlyn remote check show "inventory against ipam"
The check asks for no run itself. Each time either side's version succeeds in that environment (schedule both to keep it fresh), the server keeps that side's records, sealed, and reconciles them against the other side's last records, keeping the last twenty results with when each side was read. Reading findings is an editor's, as they hold what both systems' responses held.
Plans and approval
reqlyn remote check plan "inventory against ipam"
reqlyn remote plan show <id>
reqlyn remote plan approve <id>
reqlyn remote plan outcome <id>
check plan turns the last conflicts into a plan of writes, each through the fix its field names (a published version activated in the check's environment), with a preview of what it sends; nothing is sent. A plan is approved or refused once, by a publisher signed in as a person who neither proposed it nor issued the token that did; a service token never approves. Approved, each write's run is asked for once. plan outcome says, finding by finding, whether each was resolved (the next reconciliation read after the write no longer finds it), unresolved, skipped or uncertain, with why.
Help for Reqlyn 0.5.1. All help topics