Declarative

Introduction GitOps is a modern approach to continuous deployment where Git serves as the single source of truth for both application code and infrastructure. Changes are made through Git commits, and automated agents ensure the live environment matches the desired state in Git. This guide visualizes the GitOps workflow: Declarative Infrastructure: Everything defined as code in Git Automated Sync: Agents continuously reconcile live state with Git Drift Detection: Automatic detection and correction of manual changes Pull-Based Deployment: Agents pull changes from Git (vs push-based CI/CD) Audit Trail: Complete history of changes in Git Part 1: GitOps Overview GitOps Principles %%{init: {'theme':'dark', 'themeVariables': {'primaryTextColor':'#e5e7eb','secondaryTextColor':'#e5e7eb','tertiaryTextColor':'#e5e7eb','textColor':'#e5e7eb','nodeTextColor':'#e5e7eb','edgeLabelText':'#e5e7eb','clusterTextColor':'#e5e7eb','actorTextColor':'#e5e7eb'}}}%% flowchart TD Start([GitOps Core Principles]) --> P1[1️⃣ DeclarativeAll config in Git as YAMLDesired state, not steps] Start --> P2[2️⃣ Versioned & ImmutableGit history is truthEvery change tracked] Start --> P3[3️⃣ Pulled AutomaticallyAgents pull from GitNo push access needed] Start --> P4[4️⃣ Continuously ReconciledAgents detect driftAuto-heal to Git state] P1 --> Example1[Example:Kubernetes manifestsTerraform codeHelm charts] P2 --> Example2[Example:git log shows who changed whatgit revert to rollbackgit blame for accountability] P3 --> Example3[Example:ArgoCD polls Git every 3minFluxCD watches Git repoNo CI/CD push needed] P4 --> Example4[Example:Manual kubectl edit detectedReverted to Git stateDrift alert sent] style P1 fill:#064e3b,stroke:#10b981 style P2 fill:#064e3b,stroke:#10b981 style P3 fill:#064e3b,stroke:#10b981 style P4 fill:#064e3b,stroke:#10b981 Part 2: GitOps vs Traditional CI/CD Architecture Comparison %%{init: {'theme':'dark', 'themeVariables': {'primaryTextColor':'#e5e7eb','secondaryTextColor':'#e5e7eb','tertiaryTextColor':'#e5e7eb','textColor':'#e5e7eb','nodeTextColor':'#e5e7eb','edgeLabelText':'#e5e7eb','clusterTextColor':'#e5e7eb','actorTextColor':'#e5e7eb'}}}%% graph TB subgraph Traditional[Traditional CI/CD PUSH Model] T1([Developer]) --> T2[git push] T2 --> T3[CI ServerGitHub ActionsJenkins] T3 --> T4[Build & Test] T4 --> T5[Docker Build] T5 --> T6[Push Image] T6 --> T7[Deploy Scriptkubectl apply] T7 --> T8[Kubernetes Cluster] Note1[Issues:❌ CI needs cluster credentials❌ Push-based security risk❌ No drift detection❌ Manual changes persist] end subgraph GitOps[GitOps PULL Model] G1([Developer]) --> G2[git push] G2 --> G3[Git RepositoryKubernetes manifestsHelm charts] G4[GitOps AgentArgoCD/FluxRunning IN cluster] G4 --> |Polls every 3min| G3 G4 --> G5{Desired state= Live state?} G5 --> |No| G6[Apply changeskubectl apply] G6 --> G7[Kubernetes Cluster] G5 --> |Yes| G8[No action needed] G7 --> |Detect drift| G4 Note2[Benefits:✅ No external cluster access✅ Pull-based security✅ Automatic drift detection✅ Self-healing✅ Audit trail in Git] end style Traditional fill:#7f1d1d,stroke:#ef4444 style GitOps fill:#064e3b,stroke:#10b981 Part 3: Complete GitOps Flow End-to-End Workflow %%{init: {'theme':'dark', 'themeVariables': {'primaryTextColor':'#e5e7eb','secondaryTextColor':'#e5e7eb','tertiaryTextColor':'#e5e7eb','textColor':'#e5e7eb','nodeTextColor':'#e5e7eb','edgeLabelText':'#e5e7eb','clusterTextColor':'#e5e7eb','actorTextColor':'#e5e7eb'}}}%% flowchart TD Start([Developer makes change]) --> Change[Update Kubernetes manifestdeployment.yaml:image: myapp:v2.0replicas: 5] Change --> Commit[git commit -m "Update to v2.0"] Commit --> Push[git push origin main] Push --> GitRepo[(Git Repositoryk8s-configs/├─ apps/│ └─ myapp/│ ├─ deployment.yaml│ ├─ service.yaml│ └─ ingress.yaml└─ infrastructure/ └─ namespaces.yaml)] GitRepo --> Webhook{Webhookconfigured?} Webhook -->|Yes| Notify[Notify ArgoCDimmediately] Webhook -->|No| Poll[ArgoCD pollsevery 3 minutes] Notify --> ArgoCD[ArgoCD ControllerDetect changes in Git] Poll --> ArgoCD ArgoCD --> Compare[Compare Git statevs Live cluster state] Compare --> Diff{Differencesdetected?} Diff -->|No| InSync[✅ Application in syncNo action neededStatus: Healthy] Diff -->|Yes| OutOfSync[⚠️ Application out of syncGit: image: v2.0Cluster: image: v1.0] OutOfSync --> SyncPolicy{Auto-syncenabled?} SyncPolicy -->|No| WaitManual[⏸️ Waiting formanual sync trigger] WaitManual --> ManualSync[User clicks "Sync"in ArgoCD UI] ManualSync --> ApplyChanges SyncPolicy -->|Yes| ApplyChanges[Apply changes from Gitkubectl apply -f deployment.yaml] ApplyChanges --> RolloutStart[Kubernetes Rolling UpdateCreate new pods with v2.0] RolloutStart --> HealthCheck[Health Check LoopCheck pod statusRun readiness probes] HealthCheck --> HealthStatus{All podshealthy?} HealthStatus -->|No| CheckTimeout{Exceededtimeout?} CheckTimeout -->|No| HealthCheck CheckTimeout -->|Yes| SyncFailed[❌ Sync FailedStatus: DegradedSend alert] SyncFailed --> Rollback{Auto-rollbackenabled?} Rollback -->|Yes| RevertGit[Revert to previousGit commitTrigger new sync] Rollback -->|No| Manual[Manual interventionrequired] HealthStatus -->|Yes| Synced[✅ Sync SuccessfulApplication: HealthyGit ≡ Cluster] Synced --> ContinuousMonitor[Continuous MonitoringDetect driftWatch for manual changes] ContinuousMonitor --> DriftDetect{Manual changedetected?} DriftDetect -->|Yes| DriftAlert[🚨 Drift Detected!Someone ran kubectl editCluster ≠ Git] DriftAlert --> AutoHeal{Self-healingenabled?} AutoHeal -->|Yes| RevertDrift[Revert manual changeRestore Git stateCluster ≡ Git again] AutoHeal -->|No| DriftNotify[Notify teamManual change persistsUpdate Git to match?] RevertDrift --> ContinuousMonitor DriftNotify --> ContinuousMonitor DriftDetect -->|No| ContinuousMonitor style InSync fill:#064e3b,stroke:#10b981 style Synced fill:#064e3b,stroke:#10b981 style OutOfSync fill:#78350f,stroke:#f59e0b style SyncFailed fill:#7f1d1d,stroke:#ef4444 style DriftAlert fill:#7f1d1d,stroke:#ef4444 Part 4: ArgoCD Sync Process Detailed Sync Flow %%{init: {'theme':'dark', 'themeVariables': {'primaryTextColor':'#e5e7eb','secondaryTextColor':'#e5e7eb','tertiaryTextColor':'#e5e7eb','textColor':'#e5e7eb','nodeTextColor':'#e5e7eb','edgeLabelText':'#e5e7eb','clusterTextColor':'#e5e7eb','actorTextColor':'#e5e7eb'}}}%% sequenceDiagram participant Dev as Developer participant Git as Git Repository participant ArgoCD as ArgoCD Controller participant K8s as Kubernetes API participant Pods as Application Pods Dev->>Git: git pushUpdate deployment.yamlimage: myapp:v2.0 Note over Git: Git Repository UpdatedCommit: abc123 alt Webhook Configured Git->>ArgoCD: Webhook: Repo changed else Polling loop Every 3 minutes ArgoCD->>Git: Poll for changes end end ArgoCD->>Git: Fetch latest commitgit pull origin main ArgoCD->>ArgoCD: Parse manifests:deployment.yamlservice.yaml ArgoCD->>K8s: Get live resourceskubectl get deployment myapp -o yaml K8s-->>ArgoCD: Current state:image: myapp:v1.0replicas: 3 Note over ArgoCD: Compare states:Git: v2.0, replicas: 5Live: v1.0, replicas: 3Diff detected! ArgoCD->>ArgoCD: Status: OutOfSyncHealth: Healthy alt Auto-Sync Enabled Note over ArgoCD: Auto-sync triggered else Manual Sync ArgoCD->>ArgoCD: Wait for user to click "Sync" end ArgoCD->>K8s: Apply changeskubectl apply -f deployment.yaml K8s->>K8s: Create new ReplicaSetfor image v2.0 K8s->>Pods: Start new podswith image v2.0 loop Rolling Update K8s->>Pods: Create 1 new pod Pods-->>K8s: Pod starting... K8s->>Pods: Run readiness probe Pods-->>K8s: Ready ✓ K8s->>Pods: Terminate 1 old pod Pods-->>K8s: Terminated ArgoCD->>K8s: Check sync progress K8s-->>ArgoCD: 2/5 pods updated end K8s-->>ArgoCD: All pods ready5/5 running v2.0 ArgoCD->>ArgoCD: Status: Synced ✓Health: Healthy ✓ ArgoCD->>Dev: Notification:✅ Sync successfulmyapp updated to v2.0 Note over ArgoCD,K8s: Continuous monitoringfor drift Note over K8s: Someone runs:kubectl scale deployment myapp --replicas=10 K8s->>Pods: Scale to 10 pods ArgoCD->>K8s: Poll live state K8s-->>ArgoCD: Live: replicas: 10Git: replicas: 5Drift detected! ArgoCD->>ArgoCD: Status: OutOfSyncHealth: HealthyDrift: Yes alt Self-Healing Enabled ArgoCD->>K8s: Revert to Git statekubectl apply -f deployment.yaml K8s->>Pods: Scale back to 5 pods Note over ArgoCD: Drift correctedCluster matches Git else No Self-Healing ArgoCD->>Dev: Alert: Manual change detectedCluster has 10 replicasGit has 5 replicas end Part 5: GitOps Repository Structure Recommended Directory Layout gitops-repo/ ├── apps/ │ ├── production/ │ │ ├── myapp/ │ │ │ ├── deployment.yaml │ │ │ ├── service.yaml │ │ │ ├── ingress.yaml │ │ │ └── kustomization.yaml │ │ └── database/ │ │ ├── statefulset.yaml │ │ └── service.yaml │ │ │ ├── staging/ │ │ └── myapp/ │ │ ├── deployment.yaml │ │ ├── service.yaml │ │ └── kustomization.yaml │ │ │ └── dev/ │ └── myapp/ │ └── ... │ ├── infrastructure/ │ ├── namespaces/ │ │ ├── production.yaml │ │ ├── staging.yaml │ │ └── dev.yaml │ │ │ ├── ingress-controller/ │ │ └── nginx-ingress.yaml │ │ │ └── monitoring/ │ ├── prometheus/ │ └── grafana/ │ ├── argocd/ │ ├── applications/ │ │ ├── myapp-production.yaml │ │ ├── myapp-staging.yaml │ │ └── infrastructure.yaml │ │ │ └── projects/ │ └── default-project.yaml │ └── README.md ArgoCD Application Definition # argocd/applications/myapp-production.yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: myapp-production namespace: argocd spec: # Where the app is defined in Git source: repoURL: https://github.com/myorg/gitops-repo targetRevision: main path: apps/production/myapp # Where to deploy destination: server: https://kubernetes.default.svc namespace: production # Sync policy syncPolicy: automated: prune: true # Delete resources not in Git selfHeal: true # Revert manual changes allowEmpty: false syncOptions: - CreateNamespace=true - PrunePropagationPolicy=foreground - PruneLast=true retry: limit: 5 backoff: duration: 5s factor: 2 maxDuration: 3m # Health assessment ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicas # Ignore HPA changes # Notifications notifications: - when: on-sync-succeeded destination: slack - when: on-sync-failed destination: pagerduty Part 6: Drift Detection and Self-Healing Drift Handling Flow %%{init: {'theme':'dark', 'themeVariables': {'primaryTextColor':'#e5e7eb','secondaryTextColor':'#e5e7eb','tertiaryTextColor':'#e5e7eb','textColor':'#e5e7eb','nodeTextColor':'#e5e7eb','edgeLabelText':'#e5e7eb','clusterTextColor':'#e5e7eb','actorTextColor':'#e5e7eb'}}}%% flowchart TD Start([Cluster State]) --> Monitor[ArgoCD monitorsevery 3 minutes] Monitor --> Compare[Compare:Git desired statevsCluster live state] Compare --> Check{Statesmatch?} Check -->|Yes| InSync[✅ In SyncNo action needed] Check -->|No| DriftType{Type ofdrift?} DriftType --> ManualEdit[Manual kubectl editSomeone changed replicasfrom 5 to 10] DriftType --> ResourceAdd[New resource addedNot in Gite.g., manual deployment] DriftType --> ResourceDelete[Resource deletedIn Git but not in cluster] ManualEdit --> SelfHeal1{Self-healingenabled?} ResourceAdd --> SelfHeal2{Pruneenabled?} ResourceDelete --> SelfHeal3{Self-healingenabled?} SelfHeal1 -->|Yes| Revert[Revert to Git statekubectl apply -f deployment.yamlReplicas: 10 → 5] SelfHeal1 -->|No| Alert1[🚨 Alert OnlyManual drift detectedReplicas changed] SelfHeal2 -->|Yes| Delete[Delete extra resourcekubectl delete deployment xyzNot in Git = Removed] SelfHeal2 -->|No| Alert2[⚠️ Alert OnlyExtra resource detectedNot managed by Git] SelfHeal3 -->|Yes| Recreate[Recreate resourcekubectl apply -f service.yamlRestore from Git] SelfHeal3 -->|No| Alert3[⚠️ Alert OnlyResource missingExpected in Git] Revert --> Healed[✅ Drift CorrectedCluster ≡ GitLog event] Delete --> Healed Recreate --> Healed Alert1 --> Decision[Team Decision:1. Update Git to match?2. Revert cluster to Git?] Alert2 --> Decision Alert3 --> Decision Healed --> InSync InSync -.->|Continue monitoring| Monitor style InSync fill:#064e3b,stroke:#10b981 style Healed fill:#064e3b,stroke:#10b981 style Alert1 fill:#78350f,stroke:#f59e0b style Alert2 fill:#78350f,stroke:#f59e0b style Alert3 fill:#78350f,stroke:#f59e0b Part 7: GitOps Workflow Best Practices Git Branching Strategy %%{init: {'theme':'dark', 'themeVariables': {'primaryTextColor':'#e5e7eb','secondaryTextColor':'#e5e7eb','tertiaryTextColor':'#e5e7eb','textColor':'#e5e7eb','nodeTextColor':'#e5e7eb','edgeLabelText':'#e5e7eb','clusterTextColor':'#e5e7eb','actorTextColor':'#e5e7eb'}}}%% gitGraph commit id: "Initial infrastructure" commit id: "Add myapp v1.0" branch feature/upgrade-v2 checkout feature/upgrade-v2 commit id: "Update to v2.0" commit id: "Add new config" checkout main commit id: "Hotfix: security patch" checkout feature/upgrade-v2 merge main id: "Merge main" checkout main merge feature/upgrade-v2 id: "PR merged" tag: "Deploy to staging" commit id: "Staging validated" tag: "Deploy to prod" Approval Process # PR approval workflow name: GitOps PR Validation on: pull_request: paths: - 'apps/**' - 'infrastructure/**' jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Validate Kubernetes YAML run: | kubeval apps/**/*.yaml kustomize build apps/production/myapp | kubeval - - name: Dry-run in staging run: | kubectl apply --dry-run=server -k apps/staging/myapp - name: Security scan run: | kubesec scan apps/production/myapp/deployment.yaml - name: Policy check run: | conftest test apps/production/myapp/*.yaml require-approval: needs: validate runs-on: ubuntu-latest steps: - name: Check required approvals if: contains(github.event.pull_request.files, 'apps/production') run: | # Require 2 approvals for production changes APPROVALS=$(gh pr view ${{ github.event.pull_request.number }} --json reviews -q '.reviews | length') if [ "$APPROVALS" -lt 2 ]; then echo "Production changes require 2 approvals" exit 1 fi Part 8: Comparison Table GitOps Tools Comparison Feature ArgoCD Flux Jenkins X Architecture Controller + UI Set of controllers Full platform UI Rich web UI No UI (CLI only) Web UI Multi-cluster ✅ Native support ✅ Via Flux controllers ✅ Supported Helm support ✅ Native ✅ Via Helm controller ✅ Native Kustomize support ✅ Native ✅ Via Kustomize controller ✅ Supported SSO/RBAC ✅ Built-in ❌ Use K8s RBAC ✅ Built-in Notifications ✅ Slack, email, webhook ✅ Via providers ✅ Various channels Drift detection ✅ Visual in UI ✅ CLI/metrics ✅ Supported Learning curve Medium Low High Best for Teams wanting UI GitOps purists Full CI/CD platform Conclusion GitOps provides: ...