Repository structure

---

Table of Contents

1. Organization principles
2. Structure with Kustomize
3. Structure with Helm
4. Mono-repo vs Multi-repo
5. Naming conventions
6. Hands-on exercises

---

1 - Organization principles

Objectives

Objective	Why
Clarity	Quickly find what you're looking for
Separation	Isolate environments
Reusability	DRY (Don't Repeat Yourself)
Permissions	Control who can change what

Typical structure

gitops-repo/
├── README.md
├── .gitignore
├── apps/                    # Applications métier
│   ├── frontend/
│   ├── backend/
│   └── worker/
├── infrastructure/          # Composants plateforme
│   ├── cert-manager/
│   ├── ingress-nginx/
│   └── monitoring/
├── clusters/               # Configuration par cluster
│   ├── dev/
│   ├── staging/
│   └── prod/
└── base/                   # Ressources partagées
    └── namespaces/

App vs Infra separation

🔝 Back to table of contents

---

2 - Structure with Kustomize

Base + Overlays

apps/
└── myapp/
    ├── base/
    │   ├── kustomization.yaml
    │   ├── deployment.yaml
    │   ├── service.yaml
    │   └── configmap.yaml
    └── overlays/
        ├── dev/
        │   ├── kustomization.yaml
        │   └── replicas-patch.yaml
        ├── staging/
        │   ├── kustomization.yaml
        │   └── replicas-patch.yaml
        └── prod/
            ├── kustomization.yaml
            ├── replicas-patch.yaml
            └── resources-patch.yaml

Base (common resources)

# apps/myapp/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

commonLabels:
  app: myapp

# apps/myapp/base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 1  # Valeur par défaut
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: myapp:latest
          resources:
            requests:
              memory: "64Mi"
              cpu: "100m"

Overlay (per-env customization)

# apps/myapp/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: production

resources:
  - ../../base

patches:
  - path: replicas-patch.yaml
  - path: resources-patch.yaml

images:
  - name: myapp
    newTag: v1.2.3

# apps/myapp/overlays/prod/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 5

# apps/myapp/overlays/prod/resources-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
        - name: myapp
          resources:
            requests:
              memory: "512Mi"
              cpu: "500m"
            limits:
              memory: "1Gi"
              cpu: "1"

Test Kustomize

# Voir le rendu final
kustomize build apps/myapp/overlays/prod

# Avec kubectl
kubectl kustomize apps/myapp/overlays/prod

🔝 Back to table of contents

---

3 - Structure with Helm

Charts and Values

apps/
└── myapp/
    ├── Chart.yaml
    ├── values.yaml           # Valeurs par défaut
    ├── values-dev.yaml
    ├── values-staging.yaml
    ├── values-prod.yaml
    └── templates/
        ├── deployment.yaml
        ├── service.yaml
        └── configmap.yaml

Or reference external charts

apps/
└── myapp/
    ├── dev/
    │   └── helmrelease.yaml
    ├── staging/
    │   └── helmrelease.yaml
    └── prod/
        └── helmrelease.yaml

HelmRelease (Flux)

# apps/myapp/prod/helmrelease.yaml
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: myapp
  namespace: production
spec:
  interval: 5m
  chart:
    spec:
      chart: myapp
      version: 1.2.3
      sourceRef:
        kind: HelmRepository
        name: internal-charts
  values:
    replicaCount: 5
    image:
      tag: v1.2.3
    resources:
      requests:
        memory: 512Mi

ArgoCD with Helm

# Application ArgoCD avec Helm
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp-prod
spec:
  source:
    repoURL: https://github.com/org/gitops-repo
    path: apps/myapp
    helm:
      valueFiles:
        - values-prod.yaml

🔝 Back to table of contents

---

4 - Mono-repo vs Multi-repo

Mono-repo

gitops-monorepo/
├── apps/
│   ├── app1/
│   ├── app2/
│   └── app3/
├── infrastructure/
└── clusters/

Pros	Cons
Unified view	Complex permissions
Atomic changes	Large repo
Simplified CI/CD	Large blast radius

Multi-repo

org/gitops-apps-team-a
org/gitops-apps-team-b
org/gitops-infrastructure
org/gitops-cluster-prod

Pros	Cons
Fine-grained permissions	Fragmented view
Autonomous teams	Difficult coordination
Limited blast radius	Duplication

Recommended hybrid

# Repo 1: Infrastructure (platform team)
gitops-infrastructure/
├── cert-manager/
├── ingress/
└── monitoring/

# Repo 2: Applications (dev teams)
gitops-apps/
├── team-a/
│   ├── service1/
│   └── service2/
└── team-b/
    └── service3/

# Repo 3: Clusters (platform team)
gitops-clusters/
├── dev/
├── staging/
└── prod/

🔝 Back to table of contents

---

5 - Naming conventions

Files

# Ressources Kubernetes
deployment.yaml          # Bon
myapp-deployment.yaml    # Acceptable
myapp.deployment.yaml    # Acceptable

# Patches Kustomize
replicas-patch.yaml
resources-patch.yaml
ingress-patch.yaml

# Values Helm
values.yaml              # Base
values-dev.yaml          # Par environnement
values-prod.yaml

Folders

# Style kebab-case
apps/my-awesome-app/     # Bon
apps/my_awesome_app/     # Moins standard
apps/MyAwesomeApp/       # À éviter

# Environnements
overlays/dev/
overlays/staging/
overlays/prod/
# ou
environments/development/
environments/staging/
environments/production/

Commits

# Format
<type>(<scope>): <description>

# Types
feat:     Nouvelle fonctionnalité
fix:      Correction de bug
chore:    Maintenance
docs:     Documentation
refactor: Refactoring

# Exemples
feat(frontend): deploy v2.3.0
fix(backend): increase memory to 1Gi
chore(deps): update nginx-ingress to 1.9.0

Branches

# Pour les PR
feature/add-new-service
fix/increase-backend-memory
chore/update-monitoring

# Environnements (si branch per env)
main        # Production
staging
develop

🔝 Back to table of contents

---

6 - Hands-on exercises

Quiz

Q1. What is the difference between base and overlays in Kustomize?

Answer

• base: Common resources shared across all environments
• overlays: Environment-specific customizations (dev, staging, prod)

Q2. When to prefer Kustomize vs Helm?

Answer

• Kustomize: Simple manifests, lightweight patches, no complex templating
• Helm: Complex charts, many variables, external charts to use

Exercise: Structure a repo

Create the structure for:

• 3 microservices
• 2 environments (dev, prod)
• Using Kustomize

Solution

gitops-repo/
├── apps/
│   ├── api/
│   │   ├── base/
│   │   │   ├── kustomization.yaml
│   │   │   ├── deployment.yaml
│   │   │   └── service.yaml
│   │   └── overlays/
│   │       ├── dev/
│   │       │   └── kustomization.yaml
│   │       └── prod/
│   │           └── kustomization.yaml
│   ├── frontend/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── dev/
│   │       └── prod/
│   └── worker/
│       ├── base/
│       └── overlays/
│           ├── dev/
│           └── prod/
└── clusters/
    ├── dev/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

🔝 Back to table of contents

---

Key takeaways

• Separate apps and infrastructure
• Kustomize: base + overlays to avoid duplication
• Helm: for complex or external charts
• Mono-repo for small teams, Multi-repo for large orgs
• Consistent naming and commit conventions

🔝 Back to table of contents

---

← Previous chapter | Next chapter: Secrets management →