Skip to main content

Hostdb manages homelab hosts using infrastructure as code principles.

Project description

hostdb

This is a library for managing homelab hosts using infrastructure as code principles. The primary motivation is to help manage bare metal machines and other network infrastructure in an inventory below the kubernetes cluster.

Details

This library started as a hybrid using terraform for machine management and exposting the terrafrom state as a dynamic ansible inventory plugin. The initial use case was for managing VMs in proxmox as well as their DNS records, however given trouble around the proxmox API with breaking changes and lack of a stable terraform provider, there is a desire for something simpler and less intertwined to specific brittle APIs.

The idea now is that the inventory can exist as its own primitive then be used with other components for provisioning (e.g. could still be used as an ansible inventory plugin).

This library also contains modules useful for allocating new hostnames, and generally validating that the host database is setup correctly.

Machine naming

Machines are allocated following A Proper Server Naming Scheme that helps us treat our machines like cattle, but still find them. The basics are:

  • You have a domain name that all hosts are assigned to e.g. example.com
  • A site has a geography within the domain e.g. lax.example.com
  • Every host assigned a name from a wordlist e.g. blast.example.com. However we don't have to care about the hosts name in practice.
  • Every machine has one or more purposes (e.g. a service that it runs) and has a CNAME for each. Serial numbers are added to identify the service. e.g. kapi01.lax.example.com

Hostnames are allocated using a wordlist hostdb/resources/wordlist which are reasonably interesting names recommended from the naming scheme above.

This is just a quick summary, but see the above article for more details.

Manifest format

Infrastructure is defined through a manifest in yaml:

---
site:
  domain: lax.example.com
  name: Los Angeles
  env: prod

machines:
- host: friend
  desc: Router
  ip: 192.168.1.1
  mac: 00:11:22:33:44:55
  services:
  - rtr01
- host: lagoon
  desc: Kubernetes API server
  ip: 192.168.1.10
  mac: 00:11:22:33:44:56
  services:
  - kapi01
# Retired machines
- host: latin

All parameters are included in the ansible inventory as host variables.

The services output assigns machines to DNS names which are the same prefixes used as the ansible inventory group.

"rtr01": "friend",
"kapi01": "lagoon",

These can be used with a DNS provider.

Ansible inventory

See examples/ansible/README.md for an example of how to use a manifest to drive an ansible inventory with an inventory plugin.

Provisioning

When provisioning a new host, you need to pick a new host name then add it to the manifest and deploy the machine using your method of choice (e.g. some IaC provider). The allocate command can help you pick an available name from the wordlist that has not already been allocated. Run the command and it shows you 5 choices to pick from so you don't get stuck with a name you don't like. The rest of the names are thrown back into the pool.

$ hostdb allocate --path tests/testdata/config.yaml
ninja
reptile
warning
subject
llama

Validation

You can verify your machine manifest is valid:

$ hostdb validate --path tests/testdata/config.yaml
Success

Development

$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install -r requirements.txt
$ py.test

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hostdb-2.1.0.tar.gz (21.9 kB view details)

Uploaded Source

Built Distribution

hostdb-2.1.0-py3-none-any.whl (19.9 kB view details)

Uploaded Python 3

File details

Details for the file hostdb-2.1.0.tar.gz.

File metadata

  • Download URL: hostdb-2.1.0.tar.gz
  • Upload date:
  • Size: 21.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for hostdb-2.1.0.tar.gz
Algorithm Hash digest
SHA256 3f7d80c6c8e2157316883fe08f9e42f1c94cfd5b5f48a21bf4d59b7afcd727f6
MD5 25fd4302389a9e16524379ed6e471425
BLAKE2b-256 5352e00666f9509e5a8dd2dc650889f7630cbeccd7ff4a82a5aa8da1d263cea5

See more details on using hashes here.

File details

Details for the file hostdb-2.1.0-py3-none-any.whl.

File metadata

  • Download URL: hostdb-2.1.0-py3-none-any.whl
  • Upload date:
  • Size: 19.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for hostdb-2.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 311b7bf49fa756211263a9dcd757ac5a98a32a25410117a6ca4a088162111dda
MD5 aff6e8a7fcd3b7e305be1ba5d533f9c0
BLAKE2b-256 dbe5506a0f0ad32f426bb3704aa9b3854cb10469a4910262e238e5b9f013fe83

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page