k8s-gitops: a home Kubernetes cluster managed entirely from Git

An educational project, and the declaration is the deliverable

My Own Cloud is presented as an educational project designed to provide a hands-on learning experience for mastering Kubernetes cluster configurations and best practices. The repository showcases a declarative implementation of a Kubernetes cluster following GitOps principles that can be used with a variety of tools and workflows.

The stated main goal is to demonstrate best practices for implementing enterprise-grade security, observability and comprehensive cluster configuration management using GitOps in a Kubernetes environment, while fostering learning and growth in the Kubernetes community.

That framing explains the shape of the repository better than any feature list would. The point is not that the configuration is the best way to run a cluster, but that it is fully visible, so that a reader can see how the pieces fit and change them. The project also says it leverages a range of open source tools and platforms to demonstrate the power of the CNCF ecosystem.

The technology stack is visible in the readme's badges rather than in prose. There is a badge for the Kubernetes version, one for the Talos version and one for the Flux version, each pointing at a live endpoint, so a reader can see at a glance what the cluster is currently running. There are also badges for the cluster age in days, the uptime in days, the node count, the pod count, the CPU usage and the memory usage, all served from the same endpoint.

Those live badges are a design decision in their own right. A configuration repository can drift from reality, and a badge that reports the actual node count is a small, continuous check that the Git state and the running cluster still agree.

Three Talos nodes and a NAS, on specific consumer hardware

The hardware table is unusually concrete, and it is the part of the readme that most limits who can copy this.

The current setup is one Ubiquiti UDM-Pro-Max as the router and gateway, with 8TB of storage, one Ubiquiti USW-Pro-Max-48-PoE as the network switch, and three Asus NUC 14 Pro machines as the Kubernetes nodes. Each node has 14 cores, 48GB of RAM and 1TB of NVMe plus a 1TB SSD, on AMD64, running Talos Linux. Storage is a separate NAS with 8 cores, 16GB and 48TB running TrueNAS, and there are three JetKVM devices for remote KVM access.

A collapsed section holds the decommissioned hardware, and that list is a useful record of the project's history. There was a Protectli FW6E as the router on VyOS with 4 cores and 16GB, Protectli VP2410 and FW2B boxes as nodes on Talos, four Raspberry Pi 4 Model B nodes on ARM64, and six Rock Pi 4 Model C nodes also on ARM64.

The progression from a rack of small ARM machines to three NUCs is the story of a homelab cluster that outgrew its first hardware, and keeping the old list in the repository is a small courtesy to anyone who followed the same path. The ARM64 entries also explain why the Talos and Flux configuration in the repository has to accommodate more than one architecture.

Talos Linux is the operating system under the Kubernetes nodes, and it is worth noting what that means for the configuration: Talos is an immutable, API-driven operating system, so a node is described rather than configured, which is what makes a GitOps workflow on top of it coherent rather than bolted on.

The cloud dependencies, and what they cost

Most of the infrastructure runs on the author's own hardware, but the readme is honest about the parts that do not, and it puts a price on them.

Cloudflare handles DNS management and securing the domain, at about 69 Australian dollars per year. Google Cloud Platform is used for backups through Google Cloud Storage, and for its OAuth for authentication, at around 20 per year. GitHub is used for code management and version control and also for OAuth authentication, and it is free. Let's Encrypt generates certificates for secure communication within the network, and that is free as well.

The list is short, which is the point. A self-hosted cluster that is genuinely self-hosted needs DNS, certificates and somewhere to put backups, and those three are exactly what is bought. Everything else, the machines, the network, the storage and the cluster itself, is the hardware table above.

The GitHub entry is doing more work than it looks. It is the code host, the version control, the place the Flux configuration is reconciled from, and the OAuth provider. That concentration is a single point of failure for the whole setup, and it is also the reason the readme mentions both Renovate and GitHub Actions: the dependency updates and the reconciliation are both GitHub-side activities.

The costs are given in Australian dollars, and they are worth reading as a number rather than a footnote. Roughly 89 Australian dollars a year is what this configuration spends on hosted services, with the hardware amortised separately or ignored.

A repository laid out by the boundary of the cluster

The top-level directory listing shows the design decision that makes a GitOps repository work, which is that it covers more than the cluster.

There is a talos/ directory for the machine configuration, since Talos describes the nodes themselves. There is a kubernetes/ directory for the cluster and its workloads, which is what Flux reconciles. There is a terraform/ directory for the parts of the estate that live outside the cluster, and that is the distinction that matters, because a resource managed by Terraform and a resource managed by Flux have different lifecycles and different failure modes.

Then there is the supporting infrastructure. A .renovate/ directory holds the Renovate configuration for dependency updates, a .taskfiles/ directory with a Taskfile.yml at the root holds the task runner, a hack/ directory holds the scripts, and a .sops.yaml file configures SOPS for secret encryption. A .yamllint.yaml lints the YAML, a .pre-commit-config.yaml runs the pre-commit checks, and there is a .archive/ directory for the retired files.

The secret handling is the part to notice. A .sops.yaml in the root means encrypted secrets are committed alongside the manifests, which is the approach that makes a fully declarative repository possible without a separate secret store, at the cost of the encryption key management that implies.

There is also a wrangler.toml at the root and a CLAUDE.md, and the primary language of the repository is recorded as PHP, which almost certainly reflects the wrangler configuration rather than the substance of the project. The substance is Kubernetes manifests, Talos configuration and Terraform.

A three year old release line with a moving main branch

The maintenance picture is the one place where the repository is out of step with itself, and it is worth understanding before copying any of it.

The three most recent releases are v0.34.0 from 2023-05-07, v0.33.0 from 2023-04-30 and v0.32.0 from 2023-04-23. They are close together, which suggests a release rhythm of roughly weekly at that time, and the last of them is more than three years old.

Against that, the branch is active. The repository is not archived, the default branch is main, and the last push was on 2026-10-20, the day before the current date. So the configuration is being maintained while the tags stopped.

The practical reading is that this is a living configuration repository rather than a released product, and the tags are the point at which the author felt the state was worth naming. The renovate/ directory in the tree explains part of it: with automated dependency updates running against Kubernetes manifests, Flux controller versions and Talos versions, the configuration changes constantly and a meaningful release boundary is hard to maintain.

For a reader, that means you should follow the main branch rather than a tag, and that the badges in the readme are the more useful indicator of what the cluster actually runs. The Apache 2.0 licence, with the LICENSE file at the root, leaves no restriction on reusing any of it, which is the point of publishing an infrastructure configuration at all.

Editorial conclusion

This repository suits a homelab operator or a Kubernetes learner who wants a complete, readable example of GitOps across more than just the workload manifests, because the network, the machines and the cloud dependencies are all in the same place. It does not suit a team looking for a reusable platform or a production reference, since the hardware table names specific consumer devices and the release history stops in 2023. Before adopting any of it, read the hardware and cloud services tables to see how much of the setup assumes that particular network, and note that secrets are managed with SOPS while the Terraform directory covers the parts of the estate that live outside the cluster.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. xunholy/k8s-gitops on GitHub