progfiguration.inventory.roles#

Applying and working with roles

Note that we have to ignore type checking on string references to Inventory here. The inventory module imports this module, so we cannot import it, or we will get a circular import.

Module Contents#

Classes#

RoleArgumentReference

A special kind of role argument that is dereferenced at runtime.

RoleCalculationReference

A reference to a calculation from a role

ProgfigurationRole

A role that can be applied to a node

Functions#

collect_role_arguments(hoststore, secretstore, ...)

Collect all the arguments for a role

class progfiguration.inventory.roles.RoleArgumentReference#

Bases: Protocol

A special kind of role argument that is dereferenced at runtime.

This is used to allow roles to reference arguments from other roles

Role arguments are often used as-is, but some kinds of arguments are references. Some examples of references from progfiguration core:

  • progfiguration.age.AgeSecretReference: Decrypt the secret using the age key

  • progfiguration.inventory.roles.RoleCalculationReference: Get the calculation from the referenced role

Sites can define their own argument references.

abstract dereference(nodename: str, hoststore: HostStore, secretstore: SecretStore) Any#

Get the final value of a role argument for a node.

Arguments to this method:

  • nodename: The name of the node that the argument is being applied to

  • hoststore: The inventory object

This function must retrieve or calculate the final value from its internal data and these arguments.

class progfiguration.inventory.roles.RoleCalculationReference#

Bases: RoleArgumentReference

A reference to a calculation from a role

This is used to allow roles to reference calculations from other roles

role: str#
calcname: str#
dereference(nodename: str, hoststore: HostStore, secretstore: SecretStore) Any#

Get the final value of a role argument for a node.

Arguments to this method:

  • nodename: The name of the node that the argument is being applied to

  • hoststore: The inventory object

This function must retrieve or calculate the final value from its internal data and these arguments.

class progfiguration.inventory.roles.ProgfigurationRole#

Bases: abc.ABC

A role that can be applied to a node

Required attributes:

  • name: The name of the role

  • localhost: A localhost object

  • hoststore: An inventory object

  • rolepkg: The package that the role is defined in,

    used to determine the path to the role’s templates.

Required methods:

  • apply(): Apply the role to the node

Optional methods:

  • calculations(): Return a dict of data the role can calculate from its arguments and internal state before it is applied. This data can be referenced by other roles. For instance, a role that creates a user might calculate the user’s homedir path like ‘/home/username’, and return a calculation like {‘homedir’: ‘/home/username’}. The user may or may not have been created when it returns this data, and the path may or may not exist until the role actually runs.

name: str#
localhost: progfiguration.localhost.LocalhostLinux#
hoststore: HostStore#
rolepkg: str#
_rolefiles: Any | None#
abstract apply(**kwargs)#
calculations()#
role_file(filename: str) importlib.abc.Traversable#

Get the path to a file in the role’s package

This works whether we’re installed from pip, checked out from git, or running from a pyz file.

progfiguration.inventory.roles.collect_role_arguments(hoststore: HostStore, secretstore: SecretStore, nodename: str, node: progfiguration.inventory.nodes.InventoryNode, nodegroups: dict[str, types.ModuleType], rolename: str)#

Collect all the arguments for a role

Find the arguments in the following order:

  • Default role arguments from the ProgfigurationRole subclass

  • Arguments from the universal group

  • Arguments from other groups (in an undefined order)

  • Arguments from the node itself

Dereference any arg refs.