Personal Kubernetes Cluster

Welcome to my personal Kubernetes cluster repository! This project uses Pkl for configuration management, enabling modular, type-safe, and maintainable infrastructure code. The cluster runs on Talos Linux nodes (Hetzner) and is deployed via ArgoCD GitOps.

Structure

• /personal-cluster: The live cluster config and ArgoCD source.
  • index.pkl — root app-of-apps that lists every child Application.
  • apps/*.pkl — ArgoCD Application definitions, each pointing at a components/*.pkl entrypoint.
  • components/*.pkl — actual workload definitions consuming the shared packages.
  • secrets/ — sealed SopsSecrets.
• /packages: Reusable Pkl packages for various workloads and tools.
• /pkl-packages: Source for the Pkl registry hosting the packages. https://pkl-pkgs.lucsoft.de/
• /pkl-helmchart: Serves any Helm chart's values as a typed Pkl package. https://pkl-helm.lucsoft.de/
• /pkl-argo-plugin: ArgoCD ConfigManagementPlugin that renders Pkl into manifests.
• /talos, /talos-test: Talos node configuration.
• /tools: Deno utilities (e.g. bootstrap-secret, mc-router-scaler).

Packages

The following Pkl packages are available under /packages:

• argo.ArgoCD — Deploying and managing ArgoCD.
• com.SopsSecretsOperator — SOPS-encrypted secrets management.
• com.VictoriaMetrics — VictoriaMetrics operator CRDs (alerting, scrape targets, storage).
• dev.Knative — Knative serverless workloads.
• io.CertManager — TLS certificate management with cert-manager.
• io.CloudNativePG — PostgreSQL clusters via CloudNativePG.
• io.EnvoyGateway — Envoy Gateway policy and proxy CRDs (gateway.envoyproxy.io).
• io.Fission — Fission serverless functions.
• io.Traefik — Traefik ingress controller.
• io.k3s.HelmController — Managing Helm charts via the k3s Helm controller.
• io.k8s.GatewayAPI — Upstream Gateway API standard channel (Gateway, HTTPRoute, …).
• itzg.minecraft — Minecraft server workloads.
• lucsoft.k8s.NetworkPolicies — Kubernetes network policies.
• lucsoft.k8s.Resource — Generic Kubernetes resource helpers.
• lucsoft.k8s.Workload — Generic Kubernetes workloads.
• microsoft.AzurePipelines — Azure Pipelines agents.

Up to date list can be found in the repository https://pkl-pkgs.lucsoft.de/.

Getting Started

1. Clone this repository.
2. Install Pkl.
3. Explore the personal-cluster directory for cluster setup.
4. Use the packages in /packages to compose and manage your workloads.

Render any component locally with:

pkl eval personal-cluster/components/<Component>.pkl

Helm values as Pkl

pkl-helmchart turns a chart into a typed Pkl package, so helm.valuesObject is checked at eval time instead of being a free-form Dynamic:

package://pkl-helm.lucsoft.de/charts/https/charts.jetstack.io/cert-manager@1.20.2
package://pkl-helm.lucsoft.de/charts/oci/ghcr.io/traefik/helm/traefik@37.3.0

valuesObject = Values.toValues(new Values {
  crds { enabled = true }
})

Every property is nullable with no default, so only what you set is rendered and the chart's own defaults still apply. Append /Values.pkl, /Values.json or /values.yaml to any chart URL to inspect what was generated.

---

Feel free to explore and adapt the configurations for your own use!