How argoproj/gitops-engine works
Project type and purpose
• This is a Go-based, reusable GitOps library + example “agent” CLI.
• Core purpose: provide Kubernetes resource caching, diffing, sync planning, manifest generation, health assessment, and reconciliation logic.
File structure
• Top-level “agent” folder: standalone CLI that consumes the engine to deploy itself into clusters via Kustomize manifests.
• “pkg/engine”: entry point to the core library.
• “pkg/cache”, “pkg/diff”, “pkg/sync”, “pkg/health”, “pkg/utils”: modular subpackages realizing specific GitOps functions.
• “internal/kubernetes_vendor”: vendored Kubernetes client code.
• “specs” and “docs”: design proposals and usage guidance (not part of runtime path).
README
• Confirms core features: cache, reconciliation, sync planning, Git access, manifest generation.
• Points to design spec in specs/design.md for deeper architecture rationale.
Decompose into main components
a. Consumer layer
• Agent CLI (agent/main.go + Kustomize manifests)
b. Engine core
• Engine façade (pkg/engine)
• Cache manager (pkg/cache)
• Diff engine (pkg/diff + internal/fieldmanager)
• Sync planner & executor (pkg/sync)
• Health evaluator (pkg/health)
• Utility modules (pkg/utils for I/O, JSON, kube client, tracing, testing)
c. External systems
• Git server(s) (GitOps repo)
• Kubernetes API server(s)
• Optional plugin/hook tools (e.g., Helm hooks under pkg/sync/hook/helm)
Relationships and data flow
• Agent CLI invokes Engine façade →
• Reads desired manifests from Git → engine uses utils/kube + utils/io to fetch and parse →
• Cache layer loads live cluster state from K8s API →
• Diff engine computes desired vs. live →
• Sync planner builds reconciliation plan (pkg/sync → hook orchestration) →
• Sync executor applies resources to K8s →
• Health evaluator monitors resource health →
• Engine returns status back to CLI/user or higher-level orchestrator.
• All components communicate via well-defined Go interfaces and share the same process.
Architectural patterns
• Layered modular design (separation of cache, diff, sync, health, utils).
• Pluggable hooks (strategy pattern under pkg/sync/hook).
• Use of mocks for testing (pkg/*/mocks) demonstrates dependency-inversion for unit tests.
• Externalization of K8s vendor code under internal/ for API compatibility.
Technologies and frameworks
• Go modules, Go interfaces
• Kubernetes client-go (vendored)
• Kustomize for agent deployment
• Standard Git protocols (SSH/HTTPS) via Go-git or native exec
• CI/CD workflows (GitHub Actions via .github/workflows/ci.yaml)
• Dockerfile for containerized agent
Detail
• Module names exactly as in the file tree for clarity.
• Interfaces (e.g., SyncContext, ClusterCache, DiffRunner).
• That all modules live in-process and interconnect via Go calls, not via network calls.
• Optional flows (e.g., fieldmanager under diff/internal).