Flux CD for the infrastructure on my home k3s cluster.
  • Dockerfile 82.3%
  • Shell 17.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-19 01:28:13 +00:00
.devcontainer added jq to the dev container 2026-11-19 01:28:13 +00:00
.github/workflows updated codeberg mirror 2026-05-23 12:09:39 -04:00
.scripts added script to create agent kube config 2026-10-23 23:51:23 +00:00
.woodpecker tested update to test workflow 2026-06-28 18:39:00 +00:00
apps Automated apps update 2026-11-18 08:00:01 +00:00
cluster Add Flux v2.10.0 component manifests 2026-11-12 23:52:52 +00:00
infrastructure added node selector to longhorn and cleaned up release manifest 2026-11-19 01:16:51 +00:00
.gitignore added k3s to gitignore 2026-06-27 13:30:11 +00:00
AGENTS.md added annotations to update automation to prevent overriding the suspend/resume windows 2026-10-24 12:40:08 +00:00
readme.md added script to create agent kube config 2026-10-23 23:51:23 +00:00
sops.md added notion import settings for outline 2026-10-25 18:07:52 +00:00

Flux CD Deployment

This repository is a Flux CD deployment for a k3s cluster, running on three Beelink Mini PC's. One k3s server node and one k3s worker node on each host. If you're reading this, and you're not the owner of this particular cluster, you really shouldn't try to use this repository directly. Feel free to reference the deployment strategy and specifics, but don't try to use them unless you know what you're doing.

Repository Structure

 ├── .devcontainer # Dev container definition
 |
 ├── .github       # GitHub actions
 |
 ├── .woodpecker   # Woodpecker CI actions
 |
 ├── apps             # Apps Folder:
 │   ├── application1 # All top-level applications
 │   ├── application2 # running in the cluster are
 │   └── application3 # defined in this folder.
 |
 ├── cluster                    # Cluster Folder:
 │   ├── cluster-apps           # Kustomization
 │   ├── cluster-infrastructure # Kustomization
 │   ├── flux-system            # Flux Kustomization - NO TOUCHY
 │   └── update-automation      # Flux Update Automations
 |
 └── infrastructure # Infrastructure Folder:
     ├── service1   # Core services required for the cluster
     ├── service2   # to operate are defined in this folder.
     └── service3   # Storage, Ingress, Databases, etc.

Reconciliation

Watch the Flux Kustomizations

flux get kustomizations --watch

Reconcile any changes

# Cluster
flux reconcile kustomization flux-system --with-source

# Apps
flux reconcile kustomization cluster-apps --with-source

# Infrastructure
flux reconcile kustomization cluster-infrastructure --with-source

Redeploy a HelmRelease

flux reconcile helmrelease <helmrelease_name> -n <namespace> --with-source --force

Local Machine Setup

This repo uses two dev container defined in the .devcontainer directory. The containers contains all the tools required for interacting with the cluster.

  • kubectl (with cnpg plugin)
  • helm
  • flux
  • k9s
  • longhornctl
  • sops

The admin container

The admin container has unrestricted access to the included tools. GitHub Copilot Chat is disabled in this container, preventing an AI slop agent from having the ability to directly mutate the cluster.

Using the admin container requires 2 mounts.

  • ~/.ssh with a valid SSH key for the cluster hosts.
  • ~/.kube with a valid kube config for the cluster.

The agent container

The agent container has read-only access to the included tools. GitHub Copilot Chat is available in this container, allow the agent to have diagnostic tools to read state and configuration from the cluster.

Using the agent container requires 1 mount.

  • ~/.kube-agent with a valid kube config for the agent-readonly service account in the cluster.

This agent-readonly kube config can be generated from the admin container by running:

.scripts/make-agent-kubeconfig.sh

Create a GitHub Token

The token needs to have repo access. I had to create it as a classic token.

https://github.com/settings/tokens

Bootstrap the Cluster

The command below will install Flux on the cluster and reference the repository.

flux bootstrap github \
  --components-extra=image-reflector-controller,image-automation-controller,source-watcher \
  --owner=cvsickle \
  --repository=cluster-flux \
  --branch=main \
  --path=cluster \
  --personal \
  --token-auth
# verify
flux check
# double verify
kubectl get pods -n flux-system

Misc. Commands

Get Helm Chart Versions

helm search repo <reponame>/<chartname> --versions

Helpful Things