# 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](https://mnx.io/blog/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.
```shell
$ hostdb allocate --path tests/testdata/config.yaml
ninja
reptile
warning
subject
llama
```
## Validation
You can verify your machine manifest is valid:
```shell
$ hostdb validate --path tests/testdata/config.yaml
Success
```
## Development
```
$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install -r requirements.txt
$ py.test
```
Raw data
{
"_id": null,
"home_page": "https://github.com/allenporter/hostdb",
"name": "hostdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Allen Porter",
"author_email": "allen.porter@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/53/52/e00666f9509e5a8dd2dc650889f7630cbeccd7ff4a82a5aa8da1d263cea5/hostdb-2.1.0.tar.gz",
"platform": null,
"description": "# hostdb\n\nThis is a library for managing homelab hosts using infrastructure as code\nprinciples. The primary motivation is to help manage bare metal machines and\nother network infrastructure in an inventory below the kubernetes cluster.\n\n## Details\n\nThis library started as a hybrid using terraform for machine management and\nexposting the terrafrom state as a dynamic ansible inventory plugin. The initial\nuse case was for managing VMs in proxmox as well as their DNS records, however\ngiven trouble around the proxmox API with breaking changes and lack of a stable\nterraform provider, there is a desire for something simpler and less intertwined\nto specific brittle APIs.\n\nThe idea now is that the inventory can exist as its own primitive then be used\nwith other components for provisioning (e.g. could still be used as an\nansible inventory plugin).\n\nThis library also contains modules useful for allocating new hostnames, and generally validating\nthat the host database is setup correctly.\n\n## Machine naming\n\nMachines are allocated following [A Proper Server Naming Scheme](https://mnx.io/blog/a-proper-server-naming-scheme/) that helps us treat our machines like cattle, but still find them. The basics are:\n\n - You have a domain name that all hosts are assigned to e.g. `example.com`\n - A site has a geography within the domain e.g. `lax.example.com`\n - Every host assigned a name from a wordlist e.g. `blast.example.com`. However\n we don't have to care about the hosts name in practice.\n - Every machine has one or more purposes (e.g. a service that it runs) and has\n a CNAME for each. Serial numbers are added to identify the service.\n e.g. `kapi01.lax.example.com`\n\nHostnames are allocated using a wordlist `hostdb/resources/wordlist` which are reasonably\ninteresting names recommended from the naming scheme above.\n\nThis is just a quick summary, but see the above article for more details.\n\n# Manifest format\n\nInfrastructure is defined through a manifest in yaml:\n```\n---\nsite:\n domain: lax.example.com\n name: Los Angeles\n env: prod\n\nmachines:\n- host: friend\n desc: Router\n ip: 192.168.1.1\n mac: 00:11:22:33:44:55\n services:\n - rtr01\n- host: lagoon\n desc: Kubernetes API server\n ip: 192.168.1.10\n mac: 00:11:22:33:44:56\n services:\n - kapi01\n# Retired machines\n- host: latin\n```\n\nAll parameters are included in the ansible inventory as host variables.\n\nThe `services` output assigns machines to DNS names which are the same\nprefixes used as the ansible inventory group.\n```\n\"rtr01\": \"friend\",\n\"kapi01\": \"lagoon\",\n```\n\nThese can be used with a DNS provider.\n\n## Ansible inventory\n\nSee examples/ansible/README.md for an example of how to use a manifest to drive\nan ansible inventory with an inventory plugin.\n\n\n## Provisioning\n\nWhen provisioning a new host, you need to pick a new host name then add it to the\nmanifest and deploy the machine using your method of choice (e.g. some IaC provider).\nThe `allocate` command can help you pick an available name from the wordlist that\nhas not already been allocated. Run the command and it shows you 5 choices to pick from\nso you don't get stuck with a name you don't like. The rest of the names are thrown back\ninto the pool.\n\n```shell\n$ hostdb allocate --path tests/testdata/config.yaml\nninja\nreptile\nwarning\nsubject\nllama\n```\n\n## Validation\n\nYou can verify your machine manifest is valid:\n\n```shell\n$ hostdb validate --path tests/testdata/config.yaml\nSuccess\n```\n\n## Development\n\n```\n$ python3 -m venv venv\n$ source venv/bin/activate\n$ pip3 install -r requirements.txt\n$ py.test\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Hostdb manages homelab hosts using infrastructure as code principles.",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/allenporter/hostdb"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dbe5506a0f0ad32f426bb3704aa9b3854cb10469a4910262e238e5b9f013fe83",
"md5": "aff6e8a7fcd3b7e305be1ba5d533f9c0",
"sha256": "311b7bf49fa756211263a9dcd757ac5a98a32a25410117a6ca4a088162111dda"
},
"downloads": -1,
"filename": "hostdb-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aff6e8a7fcd3b7e305be1ba5d533f9c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19929,
"upload_time": "2024-05-13T00:45:31",
"upload_time_iso_8601": "2024-05-13T00:45:31.864829Z",
"url": "https://files.pythonhosted.org/packages/db/e5/506a0f0ad32f426bb3704aa9b3854cb10469a4910262e238e5b9f013fe83/hostdb-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5352e00666f9509e5a8dd2dc650889f7630cbeccd7ff4a82a5aa8da1d263cea5",
"md5": "25fd4302389a9e16524379ed6e471425",
"sha256": "3f7d80c6c8e2157316883fe08f9e42f1c94cfd5b5f48a21bf4d59b7afcd727f6"
},
"downloads": -1,
"filename": "hostdb-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "25fd4302389a9e16524379ed6e471425",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21928,
"upload_time": "2024-05-13T00:45:33",
"upload_time_iso_8601": "2024-05-13T00:45:33.351271Z",
"url": "https://files.pythonhosted.org/packages/53/52/e00666f9509e5a8dd2dc650889f7630cbeccd7ff4a82a5aa8da1d263cea5/hostdb-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 00:45:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allenporter",
"github_project": "hostdb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hostdb"
}
JSON
