CtrlK
BlogDocsLog inGet started
Tessl Logo

nitinjain999/platform-skills

Production-grade platform engineering handbook — Kubernetes, Terraform, Flux CD, GitHub Actions, AWS, and more.

67

Quality

84%

Does it follow best practices?

Impact

—

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

README.mdexamples/fluxcd/basic-monorepo/

Basic Monorepo Structure

A simple GitOps repository structure using Kustomize overlays for environment differences.

Structure

basic-monorepo/
├── clusters/
│   ├── production/
│   │   ├── flux-system/           # Flux bootstrap
│   │   ├── infrastructure.yaml    # Infrastructure Kustomization
│   │   └── apps.yaml              # Apps Kustomization
│   └── staging/
│       ├── flux-system/
│       ├── infrastructure.yaml
│       └── apps.yaml
├── infrastructure/
│   ├── base/                      # Shared infrastructure
│   │   ├── kustomization.yaml
│   │   ├── ingress-nginx/
│   │   └── cert-manager/
│   ├── production/                # Production overrides
│   │   └── kustomization.yaml
│   └── staging/                   # Staging overrides
│       └── kustomization.yaml
└── apps/
    ├── base/                      # Base app definitions
    │   ├── kustomization.yaml
    │   └── my-app/
    ├── production/                # Production config
    │   └── kustomization.yaml
    └── staging/                   # Staging config
        └── kustomization.yaml

Bootstrap

1. Fork and Clone

git clone https://github.com/YOUR_ORG/YOUR_REPO.git
cd YOUR_REPO

2. Bootstrap Production

flux bootstrap github \
  --owner=YOUR_ORG \
  --repository=YOUR_REPO \
  --branch=main \
  --path=clusters/production \
  --personal=false

3. Bootstrap Staging

flux bootstrap github \
  --owner=YOUR_ORG \
  --repository=YOUR_REPO \
  --branch=main \
  --path=clusters/staging \
  --personal=false

How It Works

Cluster Configuration

Each cluster defines what to reconcile:

# clusters/production/infrastructure.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: infrastructure
  namespace: flux-system
spec:
  interval: 10m
  path: ./infrastructure/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  wait: true
  timeout: 5m

Layer Dependencies

Apps depend on infrastructure:

# clusters/production/apps.yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  dependsOn:
    - name: infrastructure
  interval: 5m
  path: ./apps/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system

Environment Overlays

Staging references base with patches:

# infrastructure/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../base
patches:
  - target:
      kind: Deployment
      name: ingress-nginx-controller
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 1  # Staging uses fewer replicas

Production references base without changes or with production-specific patches:

# infrastructure/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../base
patches:
  - target:
      kind: Deployment
      name: ingress-nginx-controller
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3  # Production uses more replicas

Key Patterns

1. Separate Concerns

  • clusters/: What each cluster reconciles
  • infrastructure/: Shared platform components
  • apps/: Application workloads

2. Use Dependencies

Infrastructure must be ready before apps:

spec:
  dependsOn:
    - name: infrastructure

3. Wait for Readiness

Block until resources are healthy:

spec:
  wait: true
  timeout: 5m

4. Minimal Overlays

Keep environment differences small. Most configuration should be in base.

Adding New Applications

  1. Create base definition:
mkdir -p apps/base/new-app
cat <<EOF > apps/base/new-app/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: new-app
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: new-app
  template:
    metadata:
      labels:
        app: new-app
    spec:
      containers:
      - name: app
        image: nginx:1.25.0
        ports:
        - containerPort: 80
EOF
  1. Add to base kustomization:
cat <<EOF >> apps/base/kustomization.yaml
resources:
  - new-app/
EOF
  1. Add environment-specific values if needed:
# apps/production/kustomization.yaml
resources:
  - ../base
patches:
  - target:
      kind: Deployment
      name: new-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5  # More replicas in production
  1. Commit and push:
git add apps/
git commit -m "Add new-app deployment"
git push
  1. Wait for reconciliation:
flux reconcile kustomization apps --with-source
kubectl get deployment new-app -w

Troubleshooting

Check Reconciliation Status

flux get kustomizations -A

View Logs

flux logs --kind=kustomize-controller --since=10m

Force Sync

flux reconcile kustomization apps --with-source

Validate Locally

kustomize build apps/production

Advantages

  • ✅ Simple structure, easy to understand
  • ✅ All environments in one repository
  • ✅ Clear environment boundaries
  • ✅ Minimal overlay complexity

Limitations

  • ❌ All teams share one repository (RBAC harder)
  • ❌ Single team's changes can affect others
  • ❌ Harder to scale to many independent teams

When to Use

  • Single platform team managing all environments
  • Consistent app portfolio across environments
  • Simple RBAC requirements
  • Small to medium scale deployments

Next Steps

  • Add Helm release patterns for third-party apps
  • Add image automation patterns for updates
  • Consider a multi-tenant split when teams need stronger repo boundaries

examples

fluxcd

basic-monorepo

README.md

README.md

BEFORE_AFTER.md

CHANGELOG.md

CODE_OF_CONDUCT.md

COMMANDS.md

CONTRIBUTING.md

EDITOR_INTEGRATIONS.md

GETTING_STARTED.md

HOW_IT_WORKS.md

install.sh

INSTALLATION.md

LAUNCH.md

PROMPTS.md

QUICKSTART.md

README.md

renovate.json

SECURITY.md

SKILL.md

tessl.json

tile.json