About
Concepts
This section explains relevant concepts in Pullconf and how they are interconnected.
Server
The Pullconf server (pullconfd) is a simple server application that parses resources defined in TOML configuration files and exposes them via an HTTP API. Clients (pullconf) use this API to request their resource catalog via HTTP. All resources remain in memory until the server is restarted or reloaded. The server also validates configuration extensively and fails if some part of the configuration is erroneous or ambiguous.
When a client requests its resource catalog it does so using its hostname and an API key. Unless the server finds the client's resource catalog and the provided API key can be tied to the client, it will be rejected. How a client's hostname and their API key are tied to each other will be further explained in the sections below.
Also note that when it comes to the server configuration itself pullconfd only accepts encrypted communication channels, so a TLS certificate and private key are mandatory to secure the HTTP server.
Clients
Pullconf clients (Linux server that runs the pullconf binary) request their respective resource catalog from pullconfd and apply it. Authentication is implemented via API keys and hostnames. When a client's hostname (output from $ hostname --fqdn) is my.example.domain it fetches its resource catalog from /api/clients/my.example.domain. A client API key is authorized for this single endpoint and is otherwise declined.
The resource catalog is applied in the following way: Every resource contains dependency data. If a resource does not depend on other resources or its dependencies have already been applied, it will be applied in this instant. Otherwise it will be appended to a queue. The client iterates over its resource catalog until every resource has been applied.
Resources
Resources are the main building blocks for configuring a target system. There are generic types such as file, directory or symlink. On the other hand there are also very specific resource types as such as host that serve a single purpose, in this case maintaining a line in /etc/hosts.
Pullconf tries to infer dependencies between configured resources. For example every host resource depends on the target file /etc/hosts. If this file does not exist, the resource cannot be applied. If an administrator chose to also manage this file explicitly via the file resource type, the former will depend on the latter and both resources will be applied in order. Similarly a directory resource may depend on other directory resources if those happen to be ancestors to this directory, e.g. /my/absolute/path depends on /my/absolute if both happen to be managed resources.
Groups
As previously explained a client's resource catalog is defined in a TOML file on the server. The TOML structure contains an optional key that can be used to assign groups to a client. Groups are also TOML files stored on the server that (just as client configuration files) include resources. Groups are the place where common resources are defined that apply to multiple clients. For example the sshd configuration of a client fleet could be defined in a group since this is usually the same on every system.
When the server is (re)started it reads resources from every group that a client is a member of and evaluates them in the context of this client. Resources that are already defined in the client take precedence over those defined in a group when they are the same. For example when a file resource managing a file at /my/elaborate/path is defined in both the client and the group TOML configuration file, the former takes precedence and the latter will be ignored.
While a client's resources take precedence over those defined in groups, there is no hierarchy on the group level. As such there are a total two configuration levels, the client level on top and all the group level below it. This structure invites you to compose your client's configuration from a set of groups and leave the client configuration file for the specific stuff.