The homelab service catalog
I inventoried what the homelab actually runs. The list was longer than the number of services that matter, and more honest than the architecture diagram.
- homelab
- sre
- operations
I sat down to inventory the homelab last week. I expected a short list. The list was longer than the number of services that actually matter.
Three k3s nodes. Twelve VMs and a Pi-hole LXC. Twenty Argo CD Applications. Ten PersistentVolumeClaims. Twenty-seven Longhorn pods. A private registry, a secrets manager, a password manager, a VPN, a status page and a handful of public websites.
That is not a service catalog. That is a pile of YAML and a few VMs.
A service catalog is a different document. It says what the service is for, who uses it, who owns it, where its data lives, how it is backed up, how it is monitored and what to do when it breaks. The cluster can tell me what is running. It cannot tell me what is supposed to be running.
The inventory made that difference obvious.
What is actually in there
The homelab has five kinds of workload, even though they all look like pods from the outside.
Personal sites. The site you are reading, the Ridgwaysystems site and the old BlakeRides site. These are small Rails or static applications, and they are the easiest to reason about because I am the only user and the only stakeholder.
Client and product surfaces. Arcline, Tally 340B, Stormy Sweets, the OS4CA preview, Iter and RideAware. Some are active, some are previews, and some are in various states of being parked or rebuilt. These are the ones with other people attached.
Internal admin. Argo CD, Infisical, Passbolt, Forgejo and its registry, DefectDojo, NetBird and the status page. These are the tools I use to run everything else.
Platform. Traefik, Longhorn, Cloudflare Tunnel, CoreDNS, the image updater and the k3s control plane. These are not services in the product sense. They are the floor.
Infrastructure services. Postgres, Pi-hole, the DNS VM, OpenProject, the scanner VM, the Docker host and the game server. Some are part of the platform. Some are side projects. One of them is a Dragonwilds server, which is exactly the kind of thing a homelab is for.
The first useful count was not the number of pods. It was the number of services with a real user, a real owner and a real reason to exist.
That number is smaller.
The configuration has ghosts
The cluster has twenty Argo CD Applications. The catalog has maybe a dozen services that are actually doing something.
The gap is made of ghosts.
There are deployments scaled to zero whose Ingress objects and hostnames are still in the repository. There is a product that Argo says is suspended while five pods are still running. There are public endpoints returning 503. There is a service that has been in ImagePullBackOff for four days. There is a route in Terraform that does not resolve and a working public hostname that is not in Terraform at all.
I am not going to turn a client's broken route into public content. The pattern is the point: the cluster is full of things that exist because they were once useful, and nothing in the system asks whether they are still supposed to exist.
Kubernetes is very good at keeping things running. It is not good at telling you that they should be turned off.
What the inventory exposed
The service list did not just show me what I run. It showed me the operating gaps around it.
The status page has no checks. Uptime Kuma is running, the page loads, and there are zero monitors configured. It has also restarted thirteen times in six days. A status page with no checks is a decoration.
There is no offsite backup. Longhorn has no backup target. There are snapshots, but they are not a restore plan, and they are on the same host as the data. Postgres backups are manual or undocumented. A few applications have their own dump feature. That is not the same thing as a backup system.
One host carries everything. All three k3s nodes are VMs on one Proxmox host. Longhorn replicates between those VMs, which protects against a VM failure, not a host failure. The Cloudflare Tunnel connectors run on the same cluster. If the host goes, the sites, the registry, the tunnel and the status page go with it.
There is a degraded volume. One Longhorn volume is running with one of its two replicas stopped. The application still serves traffic, which is exactly why nobody noticed. A degraded volume with no alert is a future outage with a scheduled date.
Memory has no N+1 headroom. The cluster is using around 60 to 67 percent of its memory. If one node goes away, the remaining two have just enough room for the current workload and not much else. That is a design constraint disguised as a utilization number.
None of this is a Kubernetes problem. It is an inventory and ownership problem. The cluster is doing what I told it to do. I just never wrote down what I meant.
Why a service catalog matters
A service catalog is not documentation for its own sake. It is how you make operating decisions.
For every service, I want to be able to answer:
- What does it do, and who uses it?
- Who owns it?
- What tier is it?
- Where does its data live, and how is that data backed up?
- How is it monitored, and who gets the alert?
- What is the runbook when it breaks?
- Is it still supposed to exist?
If I cannot answer those questions, the service is a candidate for retirement, not a candidate for another dashboard.
The tier matters because not every service deserves the same treatment. A personal site can tolerate a few minutes of downtime. A client portal cannot. A staging environment does not need the same backup retention as production. An experiment does not need a pager.
This is also the first artifact I would build for a client. Before the SLO workshop, before the Terraform review, before the cost analysis, I want the service list. It tells me what the business thinks it runs, what the infrastructure actually runs and where the two disagree.
The disagreement is usually the interesting part.
The tiers I would use
Tier 0 is the things that have to work for a person outside the house: public sites, client-facing applications, the registry that ships them, DNS and the tunnel. These need backups, external monitoring and a restore test.
Tier 1 is the things that make Tier 0 operable: Argo CD, Infisical, Passbolt, Postgres, Forgejo, the scanner. These need backups and monitoring too, but the response can be different.
Tier 2 is previews, experiments, old brands and anything that is not currently a product. These can be allowed to break. They should not be allowed to accumulate quietly.
The tier is a promise about how much attention the service gets. If everything is Tier 0, nothing is.
What I am changing
The first change is to write the catalog down in the homelab repository, with one row per service: name, purpose, URL, owner, tier, source repository, data store, backup, monitoring, runbook and status.
The second is to use it to make decisions. The ghosts need a keep, fix or retire decision, not another year of running because nobody turned them off. The degraded volume needs repair. The backup target needs to exist before the next service is added.
The third is to stop treating the Argo CD application list as the inventory. Argo knows what it has been told to sync. It does not know what the business needs, what the user expects or what I intended when I added the app.
The catalog is the source of truth for intent. The cluster is the source of truth for state. The work is keeping them close enough that the difference is visible.
The homelab is allowed to be messy
A homelab is allowed to have a game server, a half-finished preview, three versions of a project and a VM that exists because I wanted to learn something. That is the point of having one.
But a homelab that other people use is not allowed to be undocumented.
The moment a client site, a customer portal or a public product runs on it, the standard changes. Not because the hardware becomes enterprise hardware, but because someone else is now depending on the inventory being real.
I still run a homelab. I just want the catalog to match the reality.
The first step is to write down what is actually there. The second is to decide what should not be.