mesh-catalog/modules/mesh-provisioner-client

mesh-provisioner-client

Holds the node-provisioner seat on every node: the provisioner's client (novox/hq ADR 0349 clauses 3 to 5, design 57 P5). Go, one binary (cmd/mesh-provisioner-client), run as a service of its own under the account mesh-provisioner-client, outside the tool runner, on a bus account of its own, provisioner.<node>, delivered as its own secret provisioner-broker (mesh-controller internal/broker/provisioner.go). The bus grants that account its own machine's keys and, to read alone, the seat mesh-provisioner's whole plans, where a provider's consumers on any machine are bound to it (ADR 0373); nothing else.

What it does

For each module placed on its node — a plan in the seat mesh-provisioner's plans (mesh-provisioner_plans, <node>.<module>, novox/hq ADR 0570 clause 2), composed there from bus state: the templates archive by reference and digest, the files it fills (path, template, owner-at-runtime, how its program takes a change) and the placement values its templates name — the client:

• fetches the templates archive and uses it only when it hashes to the plan's digest, keeping it by digest;
• watches each owner's keys for its node: placement in the plan, config in mesh-config_resolved (<node>.<module>.<key>), both named by mesh-provisioner_registry;
• leaves every ${secret:<name>} its plan names (a module's own secret, provisioning.secrets, or the credential of what it requires, a provisioning.provisions entry with a name) as the placeholder, for the node-engine to fill when it writes the file (novox/hq ADR 0570 clause 6): the client never asks the vault for it and never holds the value. A secret with a path is handed as that file alone, holding the placeholder. A secret the plan does not name fails the module;
• fills each item the module contributes to a collection (provisioning.items: the collection and its template) from the same owners as a file, and records it in mesh-provisioner_collect, <node>.<collection>.<contributor> (a character a key's token cannot hold written =<hex>: shell:zsh:normal is shell=3Azsh=3Anormal). An item naming a secret fails: an item is kept in a bucket, and no secret is;
• fills a collector's ${collected:<collection>} from every item of that collection recorded for its node, in the contributors' order, each introduced by a line naming its contributor in the collection's comment (provisioning.collections: the collections the module collects, each with its comment). The three old namespaces read as collections of the same name: ${shell:zsh:normal} is the collection shell:zsh:normal, ${environment:posix} is environment:posix, ${contribution:node-hotkeys:trigger} is contribution:node-hotkeys:trigger. A collector naming a collection its plan does not fails. A collection with no item is filled empty, and filled again whenever an item of it is recorded or goes;
• fills a file only once every value of it is there, file by file (issue 1553): a file with a value that waits stays as it is, the others are filled, and it reports waiting with every value it waits for and the files it filled; applied only when every file is filled (a collection's items are recorded only when nothing of the module waits);
• has the node-engine write each changed file through its local write socket (/run/nox-mesh-host/fill.sock, mesh-host internal/filling), which writes it as the declaration says (an owned file whole, a seed only when absent, a managed file's own keys or block) and restarts or reloads its program as the declaration says;
• fills every module again when the node-engine makes its write socket (a new engine, issue 1165) or touches it, which it does after an apply whose declaration may let through a write it refused or failed (a path now named as filled, the provisioner's account now named, a write that failed; mesh-host internal/filling Knock): a file refused because the declaration did not name it yet is written once the declaration does, and the journal says each such retry;
• writes again on every change it watches and when its node comes back, never on a timer (novox/hq ADR 0349 clause 4): every file of the module goes through the node-engine again, so an owned file changed on disk is put back;
• reports prov.applied.<node>.<module> and keeps the same report in mesh-provisioner_applied (<node>.<module>): applied with each file's action and digest, waiting, failed with the reason, or removed;
• when a module is taken off the node, removes its items and its report (the node-engine removes the files its declaration no longer names); and when the bus comes back, or the client starts, fills from the current values;
• fills a provider's ${consumers:<provision>} (novox/hq ADR 0373, issue 679) with one entry per consumer bound to it for that provision, in the order of the plans' keys and, within a plan, of its provisions entries: a JSON list, each entry {consumer, module, local, credential, value}, the credential its own, pair/<provider>/<provision>/<node>/<module>[/<local>], asked of the vault in the client's own name as a secret is. Who binds a provider is read from every machine's plans, so the client watches the whole of plans (it carries no secret's value) and reads only its own machine's plans as its own. A consumer whose credential the vault does not hold yet, or will not hand, is left out and said in the log, so the others are served; the provider's helper waits for it (mesh-sdk go/provider ConsumersFile). It is filled again when a consumer binds or unbinds and when the vault says one of the credentials changed. The catalogue holds the file to mode 0600 and owned, and refuses the placeholder in a module not providing that provision (mesh-controller internal/catalogue consumers.go); an item naming it fails;
• fills a consumer's ${bound:<provision>:<key>} from its provider's entry (mesh-sdk go/provider, issue 678): the bucket <provider module>_bound of the provider its plan names, key <node>.<module>.<provision>[.<local>], as the registry says, watched for its own machine's keys once a plan names it; as, user or one of the served values. An entry not written yet, or a bucket not there yet, is waited for; one the provider refused fails the module with the provider's reason.

It fills config, secret (design 57 V4, issue 647), the collections (collected, and shell, environment and contribution read as collections: design 57 L1, issue 684), consumers and bound (issue 679) and the placement kinds (dir, access, port, seat, machine). Any other kind fails with the reason.

A module's code asks at runtime

A module whose code runs in its machine's tool runner reads its config values through the SDK (ADR 0349 clause 14 as ADR 0370 changes it, issue 685). The tool runner asks this client on prov.ask.<node>, which only the same machine's tool runner may publish, with {module, kind, key}; the module is the one whose bundle asks, named by the tool runner and never by the module's code. The client answers {value}, the value as mesh-config_resolved holds it, only for a module assigned to its machine and a key mesh-config resolved for it (what its manifest declares), or {error} with the reason. It never answers a secret: the vault hands a secret only to a caller the bus proves, so a module in the tool runner reads its secrets from its files. A binding's non-secret values (bound) are filled into files (issue 679) and not yet answered on an ask. It says on prov.changed.<node>.<module> which value moved ({kind, key}, every key of the kind when key is absent, never the value), when the client starts and on every change, so the tool runner asks again for the watches it holds.

Files it does not know

Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).

• ${dir:state}: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).