gitops-principles

What this skill does

# 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

1. **Auditability**: Git history = deployment history
2. **Security**: No external access to cluster required
3. **Reliability**: Automated drift correction
4. **Speed**: Deploy via PR merge
5. **Rollback**: Simple `git revert`
6. **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 isolated

## Branching Strategies

### Environment Branches

```
main ────────────────────────────────────► Production
  │
  └──► staging ──────────────────────────► Staging cluster
         │
         └──► develop ───────────────────► Development cluster
```

### Trunk-Based with Overlays (Recommended)

```
main ────────────────────────────────────► All environments
  │
  ├── overlays/dev/       → Dev cluster
  ├── overlays/staging/   → Staging cluster
  └── overlays/prod/      → Prod cluster
```

### Release Branches

```
main
  │
  ├── release/v1.0 ──────► Production (v1.0)
  ├── release/v1.1 ──────► Production (v1.1)
  └── release/v2.0 ──────► Production (v2.0)
```

## Sync Policies and Strategies

### Automated Sync

```yaml
syncPolicy:
  automated:
    prune: true       # Delete resources not in Git
    selfHeal: true    # Revert manual changes
```

### Manual Sync (Production Recommended)

```yaml
syncPolicy:
  automated: null     # Require explicit sync
```

### Sync Options

| Option | Use Case |
|--------|----------|
| `CreateNamespace=true` | Auto-create missing namespaces |
| `PruneLast=true` | Delete after successful sync |
| `ServerSideApply=true` | Handle large CRDs |
| `ApplyOutOfSyncOnly=true` | Performance optimization |
| `Replace=true` | Force resource replacement |

## Declarative Configuration Patterns

### Kustomize Pattern

```yaml
# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patchesStrategicMerge:
  - replica-patch.yaml
images:
  - name: myapp
    newTag: v1.2.3
```

### Helm Pattern

```yaml
# Application pointing to Helm chart
spec:
  source:
    repoURL: https://charts.example.com
    chart: my-app
    targetRevision: 1.2.3
    helm:
      releaseName: my-app
      valueFiles:
        - values.yaml
        - values-prod.yaml
```

### Multi-Source Pattern

```yaml
spec:
  sources:
    - repoURL: https://charts.bitnami.com/bitnami
      chart: nginx
      targetRevision: 15.0.0
      helm:
        valueFiles:
          - $values/nginx/values-prod.yaml
    - repoURL: https://github.com/org/values.git
      targetRevision: main
      ref: values
```

## Progressive Delivery Integration

GitOps enables progressive delivery patterns:

### Blue-Green Deployments

```yaml
# Two applications, traffic shift via Ingress/Service
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-blue
---
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: app-green
```

### Canary with Argo Rollouts

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: {duration: 5m}
        - setWeight: 50
        - pause: {duration: 10m}
```

### Environment Promotion (Kargo)

```
Warehouse → Dev Stage → Staging Stage → Product