Skip to main content
The Kimbernetes repository follows a structured approach to organize Kubernetes manifests, separating bootstrap configuration from application deployments using a layered Kustomize overlay pattern.

​
Repository Overview

kimbernetes-k8s-flux/
├── cluster/
│   └── kimawesome/
│       ├── flux-system/
│       │   ├── gotk-components.yaml
│       │   ├── gotk-sync.yaml
│       │   └── kustomization.yaml
│       ├── kustomization.yaml
│       └── kustomization.flux.yaml
├── overlays/
│   ├── base/
│   │   ├── bind9/
│   │   ├── cert-manager/
│   │   ├── grafana/
│   │   ├── kgateway/
│   │   ├── metallb/
│   │   ├── prometheus/
│   │   ├── sealed-secrets/
│   │   └── ...
│   └── kimawesome/
│       ├── loadbalancer/
│       ├── infrastructure/
│       ├── applications/
│       ├── site/
│       ├── kustomization.yaml
│       └── README.md
├── cilium-values.yaml
├── .gitignore
└── README.md

​
Directory Structure Explained

​
cluster/

The cluster/ directory contains the Flux bootstrap configuration and cluster-level resources. This is the entry point that Flux monitors.
Purpose: Flux system components and sync configuration
  • gotk-components.yaml - All Flux CRDs and controllers (v2.7.5)
  • gotk-sync.yaml - GitRepository and Kustomization resources that define what Flux watches
  • kustomization.yaml - Kustomize configuration to tie everything together
These files are generated by flux bootstrap and should not be manually edited unless you know what you’re doing.

​
overlays/

The overlays/ directory is organized into two main layers: base and environment-specific (kimawesome).

​
overlays/base/

Contains reusable, environment-agnostic configurations. These are the building blocks that can be used across multiple environments.
cert-manager/ - TLS certificate managementmetallb/ - Bare-metal load balancersealed-secrets/ - Encrypted secrets managementmetrics-server/ - Cluster metrics collectionkgateway/ - Kubernetes Gateway API implementation
grafana/ - Monitoring and visualization stack
  • grafana-operator/ - Grafana Operator for managing Grafana instances
  • grafana-alloy/ - Grafana Alloy for telemetry collection
  • grafana-loki/ - Log aggregation system
prometheus/ - Metrics collection and alerting
bind9/ - DNS server deploymentn8n/ - Workflow automationyopass/ - Secure secret sharingknowledge-hub/ - Internal knowledge basetools/ - Utility applications
  • http-echo/ - HTTP echo service for testing
  • mysql/ - Database deployments
  • no/ - Additional tooling
Each base component follows a similar structure: 
overlays/base/<component>/
├── kustomization.yaml       # Resource references
├── namespace.yaml          # (if needed) Namespace definition
├── helm-repository.yaml    # (if Helm) Chart repository
├── helm-release.yaml       # (if Helm) Chart release config
├── deployment.yaml         # (if manifest) Deployment
└── service.yaml           # (if manifest) Service
Base configurations should be generic and parameterizable. They should not contain environment-specific values like domain names, IP addresses, or credentials.

​
overlays/kimawesome/

Contains environment-specific configurations and patches that extend the base configurations. This layer is organized by function:

loadbalancer/

MetalLB configuration with IP address pools specific to the kimawesome environment
# kustomization.flux.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: metallb
  namespace: kube-system
spec:
  interval: 10m
  path: "./overlays/kimawesome/loadbalancer"
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
    namespace: flux-system

infrastructure/

Core infrastructure services with environment-specific settingsSubdirectories include:
  • apigateway/ - Gateway configuration
  • cert-manager/ - Certificate issuers
  • gatewayapi/ - Gateway API resources
  • observability/ - Monitoring stack
  • sealed-secrets/ - Secret encryption keys
  • vpn/ - VPN configuration

applications/

Application workloads deployed to the clusterOrganized into:
  • dns-server/ - DNS server with config
  • tooling/ - n8n, yopass, and other tools
  • version-management/ - Version control applications
  • steering-k8s/ - Cluster management tools

site/

Website and documentation deploymentsContains:
  • articles/ - Article content
  • knowledge-hub/ - Knowledge base application
The kimawesome overlay structure uses dependency management: 
# infrastructure depends on loadbalancer
apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
kind: Kustomization
metadata:
  name: infrastructure
  namespace: flux-system
spec:
  interval: 10m
  path: "./overlays/kimawesome/infrastructure"
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  dependsOn:
    - name: metallb
      namespace: kube-system

​
How Overlays Reference Base

Environment-specific overlays inherit from base configurations using Kustomize’s resources field: 
# overlays/kimawesome/infrastructure/cert-manager/kustomization.yaml
namespace: cert-manager
resources:
  - ../../../base/cert-manager
This pattern:
  1. References the base configuration at overlays/base/cert-manager/
  2. Sets the namespace for all resources
  3. Can add patches, ConfigMaps, or additional resources
1

Base defines the blueprint

The base configuration in overlays/base/cert-manager/ contains generic Helm repository and release definitions
2

Environment adds specifics

The kimawesome overlay at overlays/kimawesome/infrastructure/cert-manager/ sets the namespace and can add environment-specific patches
3

Flux reconciles the result

The kustomize-controller processes both layers and applies the final manifests to the cluster

​
Flux Kustomization Resources

The repository uses Flux’s Kustomization custom resources to define what Flux should reconcile: Each Flux Kustomization resource is defined in a *.flux.yaml file: 
# overlays/kimawesome/kustomization.yaml
resources:
  - loadbalancer/kustomization.flux.yaml
  - infrastructure/kustomization.flux.yaml
  - applications/kustomization.flux.yaml
  - site/kustomization.flux.yaml

​
Root Level Files

Configuration values for the Cilium CNI plugin. Used during cluster bootstrap to configure:
  • Kube-proxy replacement
  • NodePort enablement
  • Gateway API integration
Excludes temporary files, secrets, and local development artifacts from version control.
Contains cluster creation instructions, bootstrap procedures, and operational notes specific to the kimawesome cluster.

​
Directory Naming Conventions

Consistency is key - Following naming conventions makes the repository easier to navigate and maintain.
PatternPurposeExample
kustomization.yamlStandard Kustomize configurationResource aggregation
kustomization.flux.yamlFlux Kustomization CRDGitOps sync definition
helm-repository.yamlHelm repository sourceChart source definition
helm-release.yamlHelm release configurationChart deployment settings
namespace.yamlNamespace definitionNamespace creation
*-config.yamlConfigMap resourcesApplication configuration
*-secret.yamlSealed Secret resourcesEncrypted credentials
  1. Check overlays/base/ for the base configuration
  2. Look in overlays/kimawesome/ subdirectories for environment-specific overlays
  3. Search for kustomization.flux.yaml files to understand deployment order

​
Next Steps

Flux Components

Learn about the Flux controllers that reconcile these configurations

Kustomize Overlays

Deep dive into how overlays work and how to create new ones

Adding Applications

Step-by-step guide to adding new applications to the repository

Managing Secrets

Learn how to securely manage secrets with Sealed Secrets

Build docs developers (and LLMs) love

Get started for freeTalk to us