cloudogu/gitops-patterns

Intro

This repo collects some patterns (AKA strategies, models, approaches, best practices, etc.) about GitOps process design (AKA GitOps repository structures, etc.) as well as links to talks, articles and example repos.

It originated in schnatterer's talk about the "perfect" GitOps process, our experience in consulting, and our GitOps trainings for both Flux and ArgoCD.

For questions or suggestions you are welcome to join us at our community forum.

PRs welcome!

Contents

• Pattern areas
• GitOps Patterns
  • Operator deployment
    • Hub and Spoke
    • Standalone
    • Namespaced
    • Split-Instance
  • Repository structure
    • Monorepo
    • Repo per Team
    • Repo per Application
    • Repo per environment
  • Promotion
    • Environments
      • Folder/Directory per environment
      • Repo per environment
      • Branch per environment
      • Preview environments
    • Implementation
      • Configuration Management, includes Umbrella Chart
      • Global Environments vs Environment per App
      • Config update
  • Wiring
    • Bootstrapping
    • Linking, includes Nesting (e.g. App of Apps), Templating
• Public GitOps Repo Examples
  • GitOps Playground
  • ArgoCD autopilot
  • Flux Monorepo
  • Flux repo per team/tenant
  • 📕 Path to GitOps examples
  • Environment variations
• Synonyms
• References

Pattern areas

Let's categorize GitOps patterns into separate areas to make them easier to grasp.

• Operator deployment: GitOps operators ↔ Clusters/Namespaces
• Repository: How many repos?
• Promotion:
  • Environments: How to model environments/stages?
  • Implementation: How to implement the actual process of promotion?
• Wiring: Bootstrapping operator, linking repos and folders

GitOps Patterns

Operator deployment

• Hub and Spoke ¹² 1 Operator : n Clusters
  
• Standalone ¹: 1 Operator : 1 Cluster
  
• Namespaced ³: n Operators : 1 Cluster
  
• Split-Instance ¹: 1 Operator : n Clusters; components split between management and target clusters

Repository structure

• Monorepo ²⁴
  Opposite: polyrepo ²
• Repo per Team ⁴
  More generalized: Team ➡️ Tenant⁴
• Repo per Application ²⁴
  Implementations:
  • Config replication ³
  • Repo pointer ⁵³
• Repo per environment ⁴
  Synonym: Environment per repository⁶, Repo per Stage

Promotion

We understand promotions as the process of deploying applications to different environments.
Sometimes, the term "promotion" is prefixed with other words: Release/Application/Environment/Workload/Change Promotion

For promotion, we see different sets of patterns:

• one regarding the modelling of environments and
• one regarding the implementation of the actual process of promotion.

Environments

• Folder/Directory per environment
  Synonym: Environment per folder ⁶
• Repo per environment ⁴
  Synonym: Environment per repo ⁶
• Branch per environment
  Synonym: Environment per branch ⁶
  Often discouraged ⁵ or declared an anti-pattern⁷⁸, but can work ⁹.
• Preview environments ^{10 11 12}
  Synonyms: ephemeral, dynamic, pull request¹³, test, temporary¹⁰
  Beyond the GitOps world also known as "Preview Deployments"¹⁴ and "Deploy Previews"¹⁵

Implementation

• Configuration Management
  Synonyms: Templating, Patching, Overlay, Rendering
  • plain kustomize (kustomize.yaml)
  • Helm
    • via CRD such as HelmRelease (Flux) or Application (ArgoCD)
    • via Umbrella Chart¹⁶
    • via helm template on CI server
• Global Environments vs Environment per App³
  
• Config update
  Who updates image (version) in GitOps repo, creates branch and PR?
  • Manual: Human pushes branch and create PR 🥵
  • Image Updater: Operator pushes branch, create PR manually
  • CI Server: Build job pushes branch, creates PR
  • Dependency Bot: Bot pushes branch, creates PR

Wiring

• Bootstrapping , e.g. using kubectl or operator-specific CLI such as flux or argocd-autopilot
• Linking e.g. using Operator-specific CRDs such as Kustomization (Flux) or Application (ArgoCD)
  • Nesting, e.g. App of Apps pattern ¹⁷ (ArgoCD)
  • Templating, e.g. implemented using ApplicationSets

Public GitOps Repo Examples

See also ³.

GitOps Playground

cloudogu/gitops-playground

• Repo pattern: Per team mixed with per app
• Operator pattern: Standalone (Hub and Spoke, namespaced)
• Operator: ArgoCD (Flux)
• Boostrapping: Helm, kubectl
• Linking: ArgoCD Application
• Features:
  • Env per app Pattern
  • Operate ArgoCD with GitOps
  • Config Update via CI server
  • Mixed repo patterns
  • ArgoCD and Flux examples

ArgoCD autopilot

argoproj-labs/argocd-autopilot

• Repo pattern: Monorepo
• Operator pattern: Standalone / Hub and Spoke
• Operator: ArgoCD
• Boostrapping: argocd-autopilot
• Linking: kustomize.yaml, ArgoCD Application, ApplicationSet
• Features:
  • Operate ArgoCD with GitOps
  • In the future: a lot more automation and YAML creation

Flux Monorepo

fluxcd/flux2-kustomize-helm-example

• Repo pattern: Monorepo
• Operator pattern: Standalone
• Operator: Flux
• Boostrapping: flux CLI
• Linking: kustomize.yaml, Flux Kustomization
• Features: cross-cutting infra

Flux repo per team/tenant

fluxcd/flux2-multi-tenancy

• Repo pattern: Repo per team/tenant
• Operator pattern: Standalone
• Operator: Flux
• Boostrapping: flux CLI
• Linking: kustomize.yaml, Flux Kustomization
• Features: cross-cutting infra

📕 Path to GitOps examples

christianh814/example-kubernetes-go-repo

christianh814/example-kubernetes-goflux-repo

christianh814/example-openshift-go-repo

• Repo pattern: Monorepo
• Operator pattern: Standalone
• Operator: [ArgoCD] [flux]
• Boostrapping: kubectl
• Linking: kustomize.yaml,
  • ArgoCD Application, ApplicationSet /
  • Flux Kustomization
• Features:
  • Cross-cutting infra and app(s)
  • ArgoCD and Flux examples

Environment variations

kostis-codefresh/gitops-environment-promotion

• Operator: ArgoCD (Flux)
• Features:
  • Env variants for a single app
  • Promotion "via cp"

Synonyms

• Patterns ≈ strategies, models, approaches, best practices, standards
• GitOps process design ≈ GitOps repository structures,
• GitOps Operator ≈ GitOps controller
• Config Repo = GitOps repo, Infra repo, Payload repo
  
• App repo = Source code repo, Source repo
  
• Environment = Stage
• Folder = Directory
• Templating ≈ Templating, Patching, Overlay, Rendering, Bundling, Packaging?

References

Footnotes

1. Article A Comprehensive Overview of Argo CD Architectures – 2023 by Dan Garfield ↩ ↩² ↩³

2. Article/Book How to set up your GitOps directory structure by Christian Hernandez ↩ ↩² ↩³ ↩⁴

3. Slides The perfect GitOps process: repos, folders, stages, patterns by Johannes Schnatterer ↩ ↩² ↩³ ↩⁴ ↩⁵

4. Documentation Flux | Ways of structuring your repositories ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

5. Talk GitOps: Core Concepts & Ways of Structuring Your Repos by Pinky Ravi and Scott Rigby ↩ ↩²

6. Lesson GitOps at Scale Lesson series - Git repository strategies by Codefresh (paywalled) ↩ ↩² ↩³ ↩⁴

7. Article Stop Using Branches for Deploying to Different GitOps Environments by Kostis Kapelonis ↩

8. Article Git best practices: Workflows for GitOps deployments by Christian Hernandez ↩

9. Article Monitoring and Hardening the GitOps Delivery Pipeline with Flux by Florian Heubeck ↩

10. Article Creating Temporary Preview Environments Based On Pull Requests With Argo CD And Codefresh by Codefresh ↩ ↩²

11. Talk GitOps Con Europe - Implementing Preview Environments with GitOps in Kubernetes by François Le Pape, Remazing ↩

12. Talk Preview Environments with ArgoCD by Brandon Phillips ↩

13. Video Environments Based On Pull Requests (PRs): Using Argo CD To Apply GitOps Principles On Previews by Viktor Farcic ↩

14. Documentation Vercel: Preview Deployments ↩

15. Documentation Netlify: Deploy Previews ↩

16. Documentation Helm | Chart Development Tips and Tricks ↩

17. Documentation ArgoCD: Cluster Bootstrapping - App Of Apps Pattern ↩