How to add any new application to your FluxCD fleet repo — step by step.
Overview
You have one fleet repo that acts as the control center for all your apps. Each app lives in its own independent repo and is registered in the fleet repo via a dedicated folder.
1fleet/2 clusters/my-cluster/3 flux-system/ ← Flux itself (DO NOT TOUCH)4 app1/ ← Registration for App 15 app2/ ← Registration for App 26 your-new-app/ ← Add new apps herePrerequisites
- FluxCD bootstrapped (
flux bootstrapalready run once) kubectlandfluxCLI installed- Your app has a GitHub repo with k8s manifests inside a
/k8sfolder
Part 1 — Prepare your App Repo
Your app repo only needs standard Kubernetes manifest files plus one kustomization.yaml that lists them.
App repo structure
1your-app-repo/2 k8s/3 kustomization.yaml ← lists all k8s files below4 deployment.yaml5 service.yaml6 ingress.yaml ← optionalk8s/kustomization.yaml
1apiVersion: kustomize.config.k8s.io/v1beta12kind: Kustomization3resources:4 - deployment.yaml5 - service.yaml6 - ingress.yaml⚠️ This file is not a Flux Kustomization — it's a plain kustomize resource list. No
spec:field here.
k8s/deployment.yaml (example)
1apiVersion: apps/v12kind: Deployment3metadata:4 name: your-app5 namespace: default6spec:7 replicas: 18 selector:9 matchLabels:10 app: your-app11 template:12 metadata:13 labels:14 app: your-app15 spec:16 containers:17 - name: your-app18 image: ghcr.io/yourorg/your-app:latest19 ports:20 - containerPort: 3000k8s/service.yaml (example)
1apiVersion: v12kind: Service3metadata:4 name: your-app5 namespace: default6spec:7 selector:8 app: your-app9 ports:10 - port: 8011 targetPort: 300012 type: ClusterIPPart 2 — Register the App in Your Fleet Repo
In your fleet repo, create a folder for the app under clusters/my-cluster/.
Each folder needs exactly 3 files.
Fleet repo structure for the app
1clusters/my-cluster/your-app/2 kustomization.yaml ← lists the other two files (native kustomize)3 gitrepository.yaml ← tells Flux where the app repo is4 flux-kustomization.yaml ← tells Flux how to deploy from that repoFile 1 — kustomization.yaml
This is the native kustomize file. It just lists the other two files so Flux can find them.
1apiVersion: kustomize.config.k8s.io/v1beta12kind: Kustomization3resources:4 - gitrepository.yaml5 - flux-kustomization.yaml✅ Make sure the filename is spelled correctly:
kustomization.yaml(notkustomizaton.yaml)
File 2 — gitrepository.yaml
Tells Flux which Git repo to watch and how to authenticate.
1apiVersion: source.toolkit.fluxcd.io/v12kind: GitRepository3metadata:4 name: your-app # must be unique across all apps5 namespace: flux-system6spec:7 interval: 1m0s8 ref:9 branch: main10 secretRef:11 name: flux-system # reuse the bootstrap secret for GitHub access12 url: https://github.com/yourorg/your-app-repo.git💡
secretRef.name: flux-systemreuses the SSH/PAT key that was created during bootstrap. All your private repos under the same GitHub account can use this secret.
File 3 — flux-kustomization.yaml
Tells Flux where inside the app repo to find k8s manifests, and how to apply them.
1apiVersion: kustomize.toolkit.fluxcd.io/v12kind: Kustomization3metadata:4 name: your-app # must match the GitRepository name above5 namespace: flux-system6spec:7 interval: 10m8 path: ./k8s # path inside your app repo where k8s files live9 prune: true # delete resources removed from git10 targetNamespace: default # namespace to deploy into11 sourceRef:12 kind: GitRepository13 name: your-app # must match GitRepository metadata.name⚠️
prune: truemeans if you delete a file from Git, Flux will delete it from the cluster too.
Part 3 — Push and Verify
1. Push to fleet repo
1cd fleet2git add clusters/my-cluster/your-app/3git commit -m "Add your-app to fleet"4git push2. Force reconcile (optional, skips the wait interval)
1flux reconcile source git flux-system2flux reconcile kustomization flux-system3. Check status
1# See all Flux resources2flux get all3
4# Check your specific app5flux get kustomization your-app6flux get source git your-app7
8# If something is wrong, check logs9flux logs --level=error10kubectl describe kustomization your-app -n flux-systemReal Examples
Example: chat2md app
clusters/my-cluster/chat2md/gitrepository.yaml
1apiVersion: source.toolkit.fluxcd.io/v12kind: GitRepository3metadata:4 name: chat2md5 namespace: flux-system6spec:7 interval: 1m0s8 ref:9 branch: main10 secretRef:11 name: flux-system12 url: https://github.com/dedkola/chat2MD.gitclusters/my-cluster/chat2md/flux-kustomization.yaml
1apiVersion: kustomize.toolkit.fluxcd.io/v12kind: Kustomization3metadata:4 name: chat2md5 namespace: flux-system6spec:7 interval: 10m8 path: ./k8s9 prune: true10 targetNamespace: default11 sourceRef:12 kind: GitRepository13 name: chat2mdclusters/my-cluster/chat2md/kustomization.yaml
1apiVersion: kustomize.config.k8s.io/v1beta12kind: Kustomization3resources:4 - gitrepository.yaml5 - flux-kustomization.yamlExample: tk-doc app
clusters/my-cluster/tk-doc/gitrepository.yaml
1apiVersion: source.toolkit.fluxcd.io/v12kind: GitRepository3metadata:4 name: tk-doc5 namespace: flux-system6spec:7 interval: 1m0s8 ref:9 branch: main10 secretRef:11 name: flux-system12 url: https://github.com/dedkola/tk-doc.gitclusters/my-cluster/tk-doc/flux-kustomization.yaml
1apiVersion: kustomize.toolkit.fluxcd.io/v12kind: Kustomization3metadata:4 name: tk-doc5 namespace: flux-system6spec:7 interval: 5m8 path: ./k8s9 prune: true10 targetNamespace: default11 sourceRef:12 kind: GitRepository13 name: tk-docclusters/my-cluster/tk-doc/kustomization.yaml
1apiVersion: kustomize.config.k8s.io/v1beta12kind: Kustomization3resources:4 - gitrepository.yaml5 - flux-kustomization.yamlQuick Reference
Adding a new app checklist
1[ ] App repo has /k8s folder with manifests2[ ] App repo has /k8s/kustomization.yaml listing all manifest files3[ ] Fleet repo: create clusters/my-cluster/<app-name>/ folder4[ ] Fleet repo: add kustomization.yaml (lists the other two files)5[ ] Fleet repo: add gitrepository.yaml (points to app repo)6[ ] Fleet repo: add flux-kustomization.yaml (deployment config)7[ ] Push to fleet repo8[ ] Run flux reconcile source git flux-system9[ ] Verify with flux get allCommon mistakes
| Mistake | Symptom | Fix |
|---|---|---|
kustomizaton.yaml (typo) | Flux ignores the folder | Rename to kustomization.yaml |
Wrong path: in flux-kustomization | kustomize build failed | Check where your k8s files actually are |
sourceRef.name doesn't match GitRepository.metadata.name | not found error | Make sure both names are identical |
Re-running flux bootstrap | Other apps disappear | Never re-run bootstrap; just add folders |
prune: true + deleted file | Resources deleted from cluster | Intentional — keep files in git to keep resources |
Useful commands
1# Watch all Flux resources live2flux get all --watch3
4# Force sync a specific app5flux reconcile kustomization your-app6
7# Force sync the app's git source8flux reconcile source git your-app9
10# See what Flux deployed for an app11kubectl get all -n default -l app=your-app12
13# Debug a failing kustomization14kubectl describe kustomization your-app -n flux-system15
16# See recent Flux events17flux eventsFleet Repo Final Structure
After adding multiple apps, your fleet repo should look like this:
1fleet/2 clusters/3 my-cluster/4 flux-system/5 gotk-components.yaml ← auto-generated, DO NOT EDIT6 gotk-sync.yaml ← auto-generated, DO NOT EDIT7 kustomization.yaml ← auto-generated, DO NOT EDIT8 chat2md/9 kustomization.yaml10 gitrepository.yaml11 flux-kustomization.yaml12 tk-doc/13 kustomization.yaml14 gitrepository.yaml15 flux-kustomization.yaml16 new-app/ ← just add a new folder, nothing else needed17 kustomization.yaml18 gitrepository.yaml19 flux-kustomization.yaml🎯 Golden rule: To add a new app — create a folder, add 3 files, push. That's it. Nobody needs to touch any other app's files.