cli.administration.inventory.mesh package

Submodules

cli.administration.inventory.mesh.inventory module

cli.administration.inventory.mesh.inventory.assert_no_subnet_overlap(specs: list[MeshSpec], pool: str | None) → None
cli.administration.inventory.mesh.inventory.declared_specs(groups: dict[str, list[str]], host_vars_dir: Path, inventory_files: list[Path]) → list[MeshSpec]

The meshes the deployment declares, in declaration order.

Parameters:

  • groups – group to hosts over every inventory of the deploy.

  • host_vars_dir – directory holding one <host>.yml per host.

  • inventory_files – the inventories of the deploy.

cli.administration.inventory.mesh.inventory.groups_of(inventory_files: list[Path]) → dict[str, list[str]]
cli.administration.inventory.mesh.inventory.host_applications(host_vars_dir: Path, host: str) → Any
cli.administration.inventory.mesh.inventory.hub_of(groups: dict[str, list[str]]) → str | None
cli.administration.inventory.mesh.inventory.pool_of(inventory_files: list[Path]) → str
cli.administration.inventory.mesh.inventory.specs_of(applications: Any, inventory_files: list[Path]) → list[MeshSpec]

The meshes declared in applications, in declaration order.

Parameters:

  • applications – the declaring host’s applications block.

  • inventory_files – the inventories of the deploy.

cli.administration.inventory.mesh.inventory.topology_of(groups: dict[str, list[str]], host_vars_dir: Path, specs: list[MeshSpec]) → Topology

cli.administration.inventory.mesh.keys module

cli.administration.inventory.mesh.keys.generate_private_key() → str
cli.administration.inventory.mesh.keys.is_valid_public_key(value: str) → bool
cli.administration.inventory.mesh.keys.public_key_of(private_key: str) → str

cli.administration.inventory.mesh.model module

class cli.administration.inventory.mesh.model.Mesh(spec: MeshSpec, members: tuple[~cli.administration.inventory.mesh.model.MeshMember, ...]=<factory>)

Bases: object

A spec resolved against an inventory.

Parameters:

  • spec – the declaration this mesh was resolved from.

  • members – every host in the mesh, hub first.

property hub: MeshMember
property is_full: bool
member(host: str) → MeshMember | None
members: tuple[MeshMember, ...]
peers_of(host: str) → tuple[MeshMember, ...]
spec: MeshSpec
property spokes: tuple[MeshMember, ...]
class cli.administration.inventory.mesh.model.MeshMember(host: str, address: str, private_key: str | None, public_key: str, is_hub: bool, endpoint: str = '')

Bases: object

One host’s place in a resolved mesh.

Parameters:

  • host – inventory hostname.

  • address – the member’s address inside the mesh subnet.

  • endpoint – the underlay address its peers dial.

  • private_key – the member’s own secret half, or None when the member already holds one.

  • public_key – the half its peers receive.

  • is_hub – whether this member routes for the others.

address: str
endpoint: str = ''
host: str
is_hub: bool
private_key: str | None
public_key: str
class cli.administration.inventory.mesh.model.MeshSpec(name: str, subnet: str, listen_port: int, routed_range: str = '')

Bases: object

One declared mesh.

Parameters:

  • name – identifier of the mesh, used as the interface name.

  • subnet – the mesh address range, as a.b.c.0/24.

  • listen_port – UDP port the hub, or every member of a full mesh, listens on.

  • routed_range – the range a spoke routes through the hub.

listen_port: int
name: str
routed_range: str = ''
subnet: str
class cli.administration.inventory.mesh.model.Topology(hub: str | None, spokes: dict[str, tuple[str, ...]]=<factory>)

Bases: object

Who an inventory puts into each mesh.

Parameters:

  • hub – the host that routes for every mesh, or None for full meshes.

  • spokes – mesh name to the hosts that joined it, never the hub.

hub: str | None
spokes: dict[str, tuple[str, ...]]

cli.administration.inventory.mesh.plan module

cli.administration.inventory.mesh.plan.members_of(spec: MeshSpec, topology: Topology, controller: str | None = None) → tuple[str | None, list[str]]
cli.administration.inventory.mesh.plan.plan_mesh(spec: MeshSpec, topology: Topology, existing_public_keys: dict[str, str] | None = None, *, rotate: bool = False, controller: str | None = None, endpoints: dict[str, str] | None = None, addresses: dict[str, str] | None = None) → Mesh

Resolve spec into a mesh whose members are addressed and keyed.

Parameters:

  • spec – the mesh to resolve.

  • topology – who the inventory puts into each mesh.

  • existing_public_keys – hostname to already-issued public key.

  • rotate – mint a fresh keypair for every member.

  • controller – host to admit as an extra spoke.

  • endpoints – hostname to the underlay address its peers dial; a host left out is dialled by its hostname.

  • addresses – hostname to the mesh address it already holds, kept across a rotation.

cli.administration.inventory.mesh.plan.primary_meshes(specs: list[MeshSpec], topology: Topology, controller: str | None = None, controller_mesh: str | None = None) → dict[str, str]

The first declared mesh each host belongs to.

Parameters:

  • specs – every declared mesh, in declaration order.

  • topology – who the inventory puts into each mesh.

  • controller – host admitted as an extra spoke of controller_mesh.

  • controller_mesh – the mesh controller joins.

Returns:

hostname to the name of its primary mesh.

cli.administration.inventory.mesh.transport module

cli.administration.inventory.mesh.transport.mesh_address(host_vars_dir: Path, host: str, mesh_name: str) → str | None
cli.administration.inventory.mesh.transport.mesh_ssh_args(base: str, *, persist: str = '600s') → str

The repo’s ssh_args retuned for a host reached over the mesh.

Parameters:

  • base – the ssh_args every other host uses.

  • persist – how long to keep an idle master alive.

cli.administration.inventory.mesh.transport.repo_ssh_args(config_file: Path | None = None) → str
cli.administration.inventory.mesh.transport.switch_to_mesh(host_vars_dir: Path, hosts: list[str], mesh_name: str, *, user: str, private_key_file: str) → dict[str, str]

Point every member of mesh_name at its mesh address over SSH.

Returns:

Host to the address it was switched to; a host without one is left alone.

cli.administration.inventory.mesh.write module

cli.administration.inventory.mesh.write.existing_addresses(host_vars_dir: Path, hosts: list[str], mesh_name: str) → dict[str, str]
cli.administration.inventory.mesh.write.existing_public_keys(host_vars_dir: Path, hosts: list[str], mesh_name: str) → dict[str, str]
cli.administration.inventory.mesh.write.host_vars_path(host_vars_dir: Path, host: str) → Path
cli.administration.inventory.mesh.write.private_key_name(mesh_name: str | None = None) → str
cli.administration.inventory.mesh.write.prune_foreign_meshes(host_vars_dir: Path, hosts: list[str]) → dict[str, list[str]]
cli.administration.inventory.mesh.write.write_mesh(mesh: Mesh, host_vars_dir: Path, vault_password_file: Path, primary: dict[str, str] | None = None) → list[Path]

Write mesh into every member’s host_vars and return the paths.

Parameters:

  • mesh – the resolved mesh.

  • host_vars_dir – directory holding one <host>.yml per member.

  • vault_password_file – password file the private keys are encrypted with.

  • primary – hostname to its primary mesh; an absent host counts this mesh as its primary.

Module contents

class cli.administration.inventory.mesh.Mesh(spec: MeshSpec, members: tuple[~cli.administration.inventory.mesh.model.MeshMember, ...]=<factory>)

Bases: object

A spec resolved against an inventory.

Parameters:

  • spec – the declaration this mesh was resolved from.

  • members – every host in the mesh, hub first.

property hub: MeshMember
property is_full: bool
member(host: str) → MeshMember | None
members: tuple[MeshMember, ...]
peers_of(host: str) → tuple[MeshMember, ...]
spec: MeshSpec
property spokes: tuple[MeshMember, ...]
class cli.administration.inventory.mesh.MeshMember(host: str, address: str, private_key: str | None, public_key: str, is_hub: bool, endpoint: str = '')

Bases: object

One host’s place in a resolved mesh.

Parameters:

  • host – inventory hostname.

  • address – the member’s address inside the mesh subnet.

  • endpoint – the underlay address its peers dial.

  • private_key – the member’s own secret half, or None when the member already holds one.

  • public_key – the half its peers receive.

  • is_hub – whether this member routes for the others.

address: str
endpoint: str = ''
host: str
is_hub: bool
private_key: str | None
public_key: str
class cli.administration.inventory.mesh.MeshSpec(name: str, subnet: str, listen_port: int, routed_range: str = '')

Bases: object

One declared mesh.

Parameters:

  • name – identifier of the mesh, used as the interface name.

  • subnet – the mesh address range, as a.b.c.0/24.

  • listen_port – UDP port the hub, or every member of a full mesh, listens on.

  • routed_range – the range a spoke routes through the hub.

listen_port: int
name: str
routed_range: str = ''
subnet: str
cli.administration.inventory.mesh.existing_public_keys(host_vars_dir: Path, hosts: list[str], mesh_name: str) → dict[str, str]
cli.administration.inventory.mesh.plan_mesh(spec: MeshSpec, topology: Topology, existing_public_keys: dict[str, str] | None = None, *, rotate: bool = False, controller: str | None = None, endpoints: dict[str, str] | None = None, addresses: dict[str, str] | None = None) → Mesh

Resolve spec into a mesh whose members are addressed and keyed.

Parameters:

  • spec – the mesh to resolve.

  • topology – who the inventory puts into each mesh.

  • existing_public_keys – hostname to already-issued public key.

  • rotate – mint a fresh keypair for every member.

  • controller – host to admit as an extra spoke.

  • endpoints – hostname to the underlay address its peers dial; a host left out is dialled by its hostname.

  • addresses – hostname to the mesh address it already holds, kept across a rotation.

cli.administration.inventory.mesh.write_mesh(mesh: Mesh, host_vars_dir: Path, vault_password_file: Path, primary: dict[str, str] | None = None) → list[Path]

Write mesh into every member’s host_vars and return the paths.

Parameters:

  • mesh – the resolved mesh.

  • host_vars_dir – directory holding one <host>.yml per member.

  • vault_password_file – password file the private keys are encrypted with.

  • primary – hostname to its primary mesh; an absent host counts this mesh as its primary.