Initial commit

2025-11-29 17:51:15 +08:00
commit a91d4d5a1c
25 changed files with 4094 additions and 0 deletions
--- a/references/repo_patterns.md
+++ b/references/repo_patterns.md
@@ -0,0 +1,184 @@
+# GitOps Repository Patterns (2024-2025)
+
+## Monorepo vs Polyrepo
+
+### Monorepo Pattern
+
+**Structure**:
+```
+gitops-repo/
+├── apps/
+│   ├── frontend/
+│   ├── backend/
+│   └── database/
+├── infrastructure/
+│   ├── ingress/
+│   ├── monitoring/
+│   └── secrets/
+└── clusters/
+    ├── dev/
+    ├── staging/
+    └── production/
+```
+
+**Pros**:
+- Single source of truth
+- Atomic changes across apps
+- Easier to start with
+- Simpler CI/CD
+
+**Cons**:
+- Scaling issues (>100 apps)
+- RBAC complexity
+- Large repo size
+- Blast radius concerns
+
+**Best for**: Startups, small teams (< 20 apps), single team ownership
+
+### Polyrepo Pattern
+
+**Structure**:
+```
+infrastructure-repo/     (Platform team)
+app-team-1-repo/        (Team 1)
+app-team-2-repo/        (Team 2)
+cluster-config-repo/    (Platform team)
+```
+
+**Pros**:
+- Clear ownership boundaries
+- Better RBAC (repo-level)
+- Scales to 100s of apps
+- Team autonomy
+
+**Cons**:
+- More complex setup
+- Cross-repo dependencies
+- Multiple CI/CD pipelines
+
+**Best for**: Large orgs, multiple teams, clear separation of concerns
+
+## Common Patterns
+
+### 1. Repo Per Team
+- Each team has own repo
+- Platform team manages infra repo
+- Hub cluster manages all
+
+### 2. Repo Per App
+- Each app in separate repo
+- Good for microservices
+- Maximum autonomy
+
+### 3. Hybrid (Recommended)
+- Infrastructure monorepo (platform team)
+- Application polyrepo (dev teams)
+- Best of both worlds
+
+## App-of-Apps Pattern (ArgoCD)
+
+**Root Application**:
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: root
+spec:
+  source:
+    repoURL: https://github.com/org/gitops
+    path: apps/
+  destination:
+    server: https://kubernetes.default.svc
+```
+
+**Apps Directory**:
+```
+apps/
+├── app1.yaml    (Application manifest)
+├── app2.yaml
+└── app3.yaml
+```
+
+**Benefits**: Centralized management, single sync point
+
+## Environment Structure
+
+### Option 1: Directory Per Environment
+```
+apps/
+├── base/
+│   └── kustomization.yaml
+└── overlays/
+    ├── dev/
+    ├── staging/
+    └── production/
+```
+
+### Option 2: Branch Per Environment
+```
+main branch      → production
+staging branch   → staging
+dev branch       → development
+```
+
+**Don't Repeat YAML**: Use Kustomize bases + overlays
+
+## Flux Repository Organization
+
+**Recommended Structure**:
+```
+flux-repo/
+├── clusters/
+│   ├── production/
+│   │   ├── flux-system/
+│   │   ├── apps.yaml
+│   │   └── infrastructure.yaml
+│   └── staging/
+├── apps/
+│   └── podinfo/
+│       ├── kustomization.yaml
+│       └── release.yaml
+└── infrastructure/
+    └── sources/
+        ├── gitrepositories.yaml
+        └── ocirepositories.yaml
+```
+
+## Kustomize vs Helm in GitOps
+
+**Kustomize** (recommended for GitOps):
+- Native Kubernetes
+- Declarative patches
+- No templating language
+
+**Helm** (when necessary):
+- Third-party charts
+- Complex applications
+- Need parameterization
+
+**Best Practice**: Kustomize for your apps, Helm for third-party
+
+## Promotion Strategies
+
+### 1. Manual PR-based
+```
+dev/ → (PR) → staging/ → (PR) → production/
+```
+
+### 2. Automated with CI
+```
+dev/ → (auto-promote on tests pass) → staging/ → (manual approval) → production/
+```
+
+### 3. Progressive with Canary
+```
+production/stable/ → canary deployment → production/all/
+```
+
+## 2024-2025 Recommendations
+
+1. **Start with monorepo**, migrate to polyrepo when needed
+2. **Use Kustomize bases + overlays** (don't repeat YAML)
+3. **Separate infrastructure from applications**
+4. **Implement promotion workflows** (dev → staging → prod)
+5. **Never commit directly to production** (always PR)