GitOps Principles Skill

Complete guide for implementing GitOps methodology in Kubernetes environments - the operational framework where Git is the single source of truth for declarative infrastructure and applications.

What is GitOps?

GitOps is a set of practices that uses Git repositories as the source of truth for defining the desired state of infrastructure and applications. An automated process ensures the production environment matches the state described in the repository.

The OpenGitOps Definition (CNCF)

GitOps is defined by four core principles established by the OpenGitOps project (part of CNCF):

Principle	Description
1. Declarative	The entire system must be described declaratively
2. Versioned and Immutable	Desired state is stored in a way that enforces immutability, versioning, and retention
3. Pulled Automatically	Software agents automatically pull desired state from the source
4. Continuously Reconciled	Agents continuously observe and attempt to apply desired state

Core Concepts Quick Reference

Git as Single Source of Truth

┌─────────────────────────────────────────────────────────────────┐
│                        GIT REPOSITORY                           │
│  (Single Source of Truth for Desired State)                    │
├─────────────────────────────────────────────────────────────────┤
│  manifests/                                                     │
│  ├── base/                    # Base configurations             │
│  │   ├── deployment.yaml                                        │
│  │   ├── service.yaml                                           │
│  │   └── kustomization.yaml                                     │
│  └── overlays/                # Environment-specific            │
│      ├── dev/                                                   │
│      ├── staging/                                               │
│      └── production/                                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ Pull (not Push)
┌─────────────────────────────────────────────────────────────────┐
│                      GITOPS CONTROLLER                          │
│  (ArgoCD / Flux / Kargo)                                       │
│  - Continuously watches Git repository                          │
│  - Compares desired state vs actual state                       │
│  - Reconciles differences automatically                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ Apply
┌─────────────────────────────────────────────────────────────────┐
│                    KUBERNETES CLUSTER                           │
│  (Actual State / Runtime Environment)                          │
└─────────────────────────────────────────────────────────────────┘

Push vs Pull Model

Push Model (Traditional CI/CD)	Pull Model (GitOps)
CI system pushes changes to cluster	Agent pulls changes from Git
Requires cluster credentials in CI	Credentials stay within cluster
Point-in-time deployment	Continuous reconciliation
Drift goes undetected	Drift automatically corrected
Manual rollback process	Rollback = `git revert`

Key GitOps Benefits

Auditability: Git history = deployment history
Security: No external access to cluster required
Reliability: Automated drift correction
Speed: Deploy via PR merge
Rollback: Simple git revert
Disaster Recovery: Redeploy entire cluster from Git

Repository Strategies

Monorepo vs Polyrepo

Monorepo (Single repository for all environments):

gitops-repo/
├── apps/
│   ├── app-a/
│   │   ├── base/
│   │   └── overlays/
│   │       ├── dev/
│   │       ├── staging/
│   │       └── prod/
│   └── app-b/
└── infrastructure/
    ├── monitoring/
    └── networking/

Polyrepo (Separate repositories):

# Repository per concern
app-a-config/          # App A manifests
app-b-config/          # App B manifests
infrastructure/        # Shared infrastructure
cluster-bootstrap/     # Cluster setup

Multi-Repository Pattern (This Project)

Separates infrastructure from values for security boundaries:

infra-team/                    # Base configurations, ApplicationSets
├── applications/              # ArgoCD Application definitions
└── helm-base-values/          # Default Helm values

argo-cd-helm-values/           # Environment-specific overrides
├── dev/                       # Development values
├── stg/                       # Staging values
└── prd/                       # Production values

Benefits:

Different access controls per repo
Separation of concerns
Environment-specific secrets isol

...

gitops-principles-skill

SKILL.md