| name | flux-gitops-patterns |
| description | Use when designing GitOps repository structure, setting up dependency chains between resources, implementing multi-environment deployments, configuring secrets management with Flux, setting up notifications and alerts, or optimizing reconciliation intervals |
Flux CD GitOps Patterns
Implement GitOps best practices with Flux CD, including repository structure, dependency management, and deployment patterns.
Keywords
flux, fluxcd, gitops, patterns, architecture, repository, structure, kustomization, helmrelease, dependencies, multi-tenant, multi-cluster, secrets, sops, designing, creating, deployment, deployments, notification, alerts, alerting, reconciliation, interval
When to Use This Skill
- Designing GitOps repository structure
- Setting up dependency chains between resources
- Implementing multi-environment deployments
- Configuring secrets management with Flux
- Setting up notifications and alerts
- Optimizing reconciliation intervals
Related Skills
Quick Reference
| Task | Pattern/Command |
|---|
| Monorepo layout | clusters/, infrastructure/, apps/ directories |
| Multi-repo layout | Separate repos per team/concern |
| Component layout | namespace.yaml, repository.yaml, release.yaml |
| Force sync | flux reconcile ks flux-system --with-source |
| Variable substitution | spec.postBuild.substitute / substituteFrom |
| Encrypt secrets | SOPS with spec.decryption.provider: sops |
| Set up alerts | Alert + Provider in notification.toolkit.fluxcd.io |
Repository Patterns
Monorepo (Recommended for Small Teams)
homelab/
├── clusters/
│ ├── production/
│ │ ├── flux-system/
│ │ ├── infrastructure.yaml
│ │ └── apps.yaml
│ └── staging/
│ ├── flux-system/
│ └── ...
├── infrastructure/
│ ├── kustomization.yaml
│ ├── cert-manager/
│ ├── external-dns/
│ └── external-secrets/
├── apps/
│ ├── kustomization.yaml
│ ├── grafana/
│ └── loki/
└── helm/
└── local-charts/
Multi-Repo (Enterprise)
fleet-infra/ # Flux bootstrap, cluster configs
├── clusters/
│ ├── production/
│ └── staging/
platform-components/ # Shared infrastructure
├── cert-manager/
├── ingress-nginx/
└── monitoring/
team-alpha-apps/ # Team-specific apps
├── app1/
└── app2/
Component Structure
component-name/
├── namespace.yaml # Namespace isolation
├── repository.yaml # HelmRepository source
├── release.yaml # HelmRelease deployment
└── kustomization.yaml # Resource orchestration
Dependency Management
Kustomization Dependencies
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: apps
namespace: flux-system
spec:
dependsOn:
- name: infrastructure
- name: configs
interval: 10m
path: ./apps
prune: true
wait: true
sourceRef:
kind: GitRepository
name: flux-system
Deployment Order
Flux System (bootstrapped)
└─> Infrastructure (CRDs, operators)
├─> Configs (ConfigMaps, Secrets)
└─> Monitoring (Prometheus, Grafana)
└─> Apps (depends on all above)
Source Configuration
GitRepository
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
name: flux-system
namespace: flux-system
spec:
interval: 10m
url: https://github.com/org/repo
ref:
branch: main
secretRef:
name: flux-system
ignore: |
/*
!/clusters/
!/infrastructure/
!/apps/
OCI Repository
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
name: podinfo
namespace: flux-system
spec:
interval: 10m
url: oci://ghcr.io/stefanprodan/manifests/podinfo
ref:
tag: latest
provider: generic
HelmRepository
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
name: bitnami
namespace: flux-system
spec:
interval: 30m
url: https://charts.bitnami.com/bitnami
Variable Substitution
Environment Variables
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
spec:
postBuild:
substitute:
CLUSTER_NAME: production
DOMAIN: example.com
ENVIRONMENT: prod
substituteFrom:
- kind: ConfigMap
name: cluster-vars
- kind: Secret
name: cluster-secrets
Usage in Manifests
apiVersion: networking.k8s.io/v1
kind: Ingress
spec:
rules:
- host: app.${DOMAIN}
Secrets Management
SOPS Integration
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
spec:
decryption:
provider: sops
secretRef:
name: sops-age
External Secrets Pattern
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
name: app-secrets
spec:
refreshInterval: 1h
secretStoreRef:
kind: ClusterSecretStore
name: vault
target:
name: app-secrets
creationPolicy: Owner
data:
- secretKey: db-password
remoteRef:
key: secret/data/app
property: password
Notification Patterns
Provider Configuration
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
metadata:
name: discord
namespace: flux-system
spec:
type: discord
secretRef:
name: discord-webhook
Alert Configuration
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
metadata:
name: on-call-alerts
namespace: flux-system
spec:
providerRef:
name: discord
eventSeverity: error
eventSources:
- kind: GitRepository
name: '*'
- kind: Kustomization
name: '*'
- kind: HelmRelease
name: '*'
namespace: '*'
Interval Guidelines
| Resource Type | Recommended Interval | Rationale |
|---|
| GitRepository | 10m | Balance freshness vs API calls |
| HelmRepository | 30m | Charts update less frequently |
| Kustomization | 10m | Sync with Git interval |
| HelmRelease | 15m | Allow chart fetch first |
| OCIRepository | 10m | Similar to Git |
GitOps Principles
- Declarative - Desired state in Git, not imperative commands
- Versioned - All changes tracked in Git history
- Automated - Flux applies changes automatically
- Auditable - Git log provides complete audit trail
- Self-healing - Drift automatically corrected
Anti-Patterns to Avoid
| Anti-Pattern | Problem | Solution |
|---|
| Direct kubectl apply | Bypasses GitOps | Always commit to Git |
| Forgotten suspensions | Resources don't update | Document, set reminders |
| Missing dependsOn | Race conditions | Define explicit dependencies |
| Secrets in Git (plaintext) | Security breach | Use SOPS or External Secrets |
| Very short intervals | API throttling | Use 10m+ for most resources |
| Wildcard sources | Security risk | Explicit resource names |
