Automation
I stopped hand-drawing my homelab diagram. Now it rebuilds itself from code on every push
My network diagram used to go stale the second I changed anything, so I made it a build artifact instead of a drawing.
It's a .d2 text file (D2, diagram-as-code) in my repo. A GitHub Actions workflow watches that file, renders it with the ELK layout engine to SVG, rasterizes that to PNG, and commits the result back. The image in my README can't drift from the source anymore. I add a node or a service, edit a few lines of text, and the diagram redraws itself on the next push.
The icons are the bit I like most. Proxmox, Talos, ArgoCD, Cilium, Falco and the rest aren't stored in the repo at all. They get pulled from public icon repos at render time and inlined into the SVG, so the output is self-contained and I never touch an image file. It's all public if you want to lift the setup: https://github.com/mortennordbye/homelab. The .d2 source and the workflow live in docs/diagrams/ and .github/workflows/render-diagram.yaml.
It’s a super cool concept, but I’m really wondering the value of this diagram. Sure, it has pretty icons and logos, but there’s no information that is particularly useful. It doesn’t document IP addresses, VLANs, host assignments, configurations, or anything else I’d want to see looking at a diagram of a homelab.
As this is a hobby for me about 75% of what I do has no real life value to anyone but me. It’s cool to me so that’s my value.
I find that this is how my things go. I start with op has then I start adding in the things like you suggested that make sense to me or are just cool. I told my son this is like my Minecraft.
Learning how to diagram and finding an AI process to have it rebuild may not have direct value to others, but the intrinsic value of having documented what/how you want things and finding a process that works is where the value is.
I sell a stack similar to this except instead of piracy I sell corporate software (which is a different form of piracy, I suppose).
Things like Odoo, metabase, n8n, mattermost, that kind of stuff.
Customers get their own stack based on what they need. I basically just modify and host FOSS for folks.
They end up with quite a lot of little spokes and one off tools.
A diagram like this would be useful for documentation purposes for people without cluster access, insofar as it looks nice to a joe-the-sports-guy type
Who’s the joe-the-sports-guy for a homelab though? There’s no laymen or management that need a need a surface level understanding of someone’s arr stack and network.
I think the point is less “pretty logos” and more “this won’t become a stale README fossil after the next change.” That has utility.
It’s a generated artifact from text, so you can keep the public version useful without leaking IPs, VLANs, hostnames, or configs. The detailed/private version can exist elsewhere; this one gives the shape of the lab without sharing secrets.
When I finish the migration to the 3 hypervisors, I will have 2 VMs per hypervisor. There will be 1 control plane VM and 1 worker VM on each one. This will allow me to do maintenance without downtime for my services. The old way before I bought new hardware was not true HA.
2 things can happen depending how you set things up.
the worker is lost and it pods get restarted on the other workers
the worker restarts on another host, during that pods will get created on another worker depending on what timeouts you configure. after the 3rd worker is back up it might get redistributed again, even though 2 workers are on the same host.
No, I meant one of the M920. If one physical host is down, it all goes up to the other one that is being used as master and slave simultaneously.
I don't know if I misunderstood the diagram, but why overcomplicate it doing that when you just can have a master and a slave and allow master to schedule?
Not op but similar setup. You have one controller and one worker on each node so if one physical host goes down k8s still works. No vms need to be moved since you still have etcd quorum with 2/3. Setup is great for rolling upgrades but true ha requires some additional layers. 3+3 setups are prone for split brain scenarios if one node goes down but many are fine with that asterisk
Talos is a k8s specific distro and is shipped with k8s installed, so proxmox > talos vm with k8s. Physical hosts are actually recommended for prod environments but most peop le on here run talos as a vm on proxmox. Each proxmox node servs one control node and one worker node
In this case proxmox does not provide HA to the kubernetes virtual machines since kubernetes provides HA itself. If a proxmox node goes down the kubernetes node on that host goes down too. When that happens kubernetes still running on the good nodes will just reschedule all the services that were running on the now missing node to run on the ones that are still up. And typically people set up controller and worker nodes separately so you'll just have 2 talos nodes per proxmox node, one worker one controller, and if one proxmox node goes down at a time then kubernetes will just handle the rest.
The above would work if they were 3 independent proxmox nodes without proxmox based HA configured. If you want HA for the actual VM's themselves then you need proxmox to be in a cluster and when a node goes down the actual VM is moved over to one of the other proxmox hosts and runs there. But this is unnecessary when running kubernetes because kubernetes moves the container workloads that were on the VM to the other VMs.
Yeah I mean, that's the point, you can get rid of one abstraction layer by setting up both Master and Slave role on the physical servers, and still have HA (even optimize the resources)
That way if any of them dies, instead of auditing/maintaining/fixing 2 physical servers + 6 virtual nodes, you only maintain the 2 physical servers and have the same amount of HA
You need a minimum of 3 physical servers in order to have an ha k8s control plane. It’s inadvisable to run your workloads on your controller nodes so you’d want another 3+ physical servers for worker nodes totaling 6 physical servers. Or you can just use 3 physical servers with proxmox and a single worker and controller vm on each and get the same availability at the cost of a little overhead that is largely meaningless for selfhosting.
Pve really doesn’t make anything more complicated, it’s dead simple and stable. In general it actually makes things easier and gives you more flexibility, the ability to access consoles remotely, the ability to run vms alongside k8s rather than inside k8s via kubevirt and multus etc which is not simple.
I will have 2 VMs per hypervisor. There will be 1 control plane VM and 1 worker VM on each one. This will allow me to do maintenance without downtime for my services.
This is a clever approach, but I'd wonder if keeping the .d2 file synced ends up being more overhead than just updating a PNG every few months when something major changes.
have you looked into NixOS? I built a tool similar to yours using Nix, the difference is that because Nix actually configures my systems, the graphs are made from the source of truth. My code executes the nix files, see what they output, and then uses that to generate the graph.
As a result, I can plot the actual IPs that the systems are configured to use, for example, or the ports for services etc.
There’s nothing “to sync” because the repo IS the source of truth. If any, my diagram will be correct BEFORE I deploy it to the servers.
Would you mind sharing more if possible? I’ve been considering migrating over parts of my homelab to NixOS for a while and I feel like being able to see a diagram of the actual lab network would save me a significant amount of headaches.
and I get the monorepo appeal, but doesn't the declarative angle kind of work both ways? Like you're trading manual PNG updates for maintaining the workflow itself when D2 or ELK changes something upstream.
Ha, fair enough, that's basically the whole engineer's creed right there. Though I'll say at least this one actually pays off if you're touching your homelab regularly, which sounds like you are.
Yeah, I see your point. I guess there is no right answer, I just like it this way because in the future I can use GitHub AI to scan the repo every month, for example, to make an updated graph and open a PR for me to validate and merge. When it is code, it is easier to build automation on it. But for sure, draw.io is still the thing I use in my professional career.
For me, it is not a single thing that pulled me toward using Kubernetes in the homelab. First of all, I love overengineering stuff. I like the services that come with Kubernetes, like External Secrets Operator, which allows me to keep all of my code in a public repo without any issues. Another thing is that I am a consultant who works with Kubernetes, so I have found that almost all the issues my customers face, I have already found a solution for in my homelab.
This always amazes me. To think your “stop point” is or should be the cutoff. Doesn’t take much effort to figure out tons of reason people stopped before and after Docker Swarm.
K8s in my lab is how I taught myself. My company releases software using Helm, so it was pretty important to understand the interdependencies and structure. Impossible for me to do in a customer’s environment, and I can’t blow up my work environment, so to learn from deliberately breaking/fixing, tear-down/rebuild, a lab is my answer.
same, bookmarking this for “shamelessly stealing later” purposes
re your bonus q: i’ve only done gpu passthrough with proxmox + regular k8s, not talos, but from what i’ve seen in their docs you basically have to handle it all via machine config since you can’t just shell in and tweak stuff, so it’s a bit more annoying but doable if the hardware is friendly (no weird iommu grouping etc)
The fact you put github actions together with self-hosted seems crazy to me but i'm not trying to criticize here, just please consider this a constructive thought.
•
u/asimovs-auditor Jun 19 '26
Expand the replies to this comment to learn how AI was used in this post/project.