Important concepts¶

progfiguration core: The core pacakge containing generic code not specific to any site.

Progfiguration sites (progfigsites): A package containing all the code specific to a single site.

Controller: This is the machine that contains a master Age key and can connect to all the nodes in the inventory. It can decrypt all secrets and can connect to all nodes via SSH when running the progfigsite deploy command.

Inventory: A host store plus a secret store.

Host store

Where nodes, groups, and functions are defined. See progfiguration.inventory.invstores.HostStore.

Progfiguration ships with progfiguration.sitehelpers.memhosts.MemoryHostStore which implements that protocol, and progfiguration.sitehelpers.invconf.hosts_conf() which can instantiate one from a simple configuration file.

Sites are free to instantiate a MemoryHostStore directly or implement their own HostStore (in their sitelib module) and use it instead.

Secret store

How secrets are stored. See progfiguration.inventory.invstores.SecretStore.

Progfiguration ships with progfiguration.sitehelpers.agesecrets.AgeSecretStore which implements that protocol, and progfiguration.sitehelpers.invconf.secrets_conf() which can instantiate one from a simple configuration file.

Sites are free to instantiate an AgeSecretStore directly or implement their own SecretStore (in their sitelib module) and use it instead.

Node: A machine to be configured. Must be defined in the inventory config file and have a Python module at progfigsite.nodes.NODENAME. If the node has any secrets, they are stored as JSON files under progfigsite/nodes/NODENAME.secrets.json. See progfigsite.nodes Module.

Group: Collections of nodes. Must be defined in the inventory config file and have a Python module at progfigsite.groups.GROUPNAME. If the group has any secrets, they are stored as JSON files under progfigsite/groups/GROUPNAME.secrets.json. See progfigsite.groups Module.

Role: Configuration code that can be applied to a node. A role might do something like install packages, set the contents of a configuration file, etc. These are Python modules at progfigsite.roles.ROLENAME. Roles commonly contain data files to install on the node as well. See progfigsite.roles Module.

Role reference: Most role arguments are simple Python objects, like strings, ints, or pathlib.Path objects. Role references are special arguments that are used to dynamically find argument values at runtime. Currently, progfiguration understands two kinds of references: progfiguration.inventory.roles.RoleCalculationReference, which refers to the results of role calculations (see progfigsite.roles Module for more on calculations), and progfiguration.inventory.invstores.SecretReference, which is a protocol that SecretStore backends must implement that refers to secret values. Role references are dereferenced at runtime.

Function

A function is a mapping of a node to a set of roles. Functions are defined inside the host store only – unlike groups and nodes, they don’t have an object associated with them.

A node can only have one function, but the function can map to multiple roles. When a node is provisioned, the roles associated with the function are applied to the node.