The question that defines GitOps: if someone deletes a Deployment at 3 a.m., does the cluster recover automatically?

If the answer is "no", you have CI with kubectl apply, not GitOps. The difference is who controls the desired state.

Course seal: tested on Kubernetes 1.35 with ArgoCD 2.x.

The model

Git (estado desejado) ──► ArgoCD (comparação) ──► Cluster (estado real)
                              ▲                        │
                              └──── drift detectado ───┘

• Source of truth: Git repository.
• Agent: ArgoCD runs in the cluster and compares continuously.
• Result: Synced/OutOfSync and Healthy/Degraded.

Nobody applies with kubectl in production. If you do, ArgoCD reverts — and that is the correct behavior.

Installation

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
kubectl -n argocd get pods

Access:

kubectl -n argocd port-forward svc/argocd-server 8080:443
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d

In production: Ingress with TLS, SSO (OIDC), and ArgoCD RBAC. Local admin is only for bootstrap.

An Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: portal-homolog
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/portal-gitops.git
    targetRevision: main
    path: apps/portal/overlays/homolog
  destination:
    server: https://kubernetes.default.svc
    namespace: portal
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true
    retry:
      limit: 3
      backoff:
        duration: 10s
        factor: 2
        maxDuration: 3m

Points that matter:

• prune: true removes what left Git.
• selfHeal: true corrects manual changes.
• retry avoids staying Degraded due to a transient image error.

App-of-apps

One repository, many Applications:

gitops/
  bootstrap/
    root-app.yaml
  apps/
    portal/
      base/
      overlays/homolog
      overlays/prod
    observability/
    operators/

The root-app points to apps/ and ArgoCD discovers the rest. Adding a new environment = opening a PR.

Synchronization: manual or automatic

Mode	When to use
Manual (syncPolicy empty)	regulated production, approved window
Automated	homolog, staging, internal services
Automated + selfHeal	everything that needs to resist manual change
Automated + prune	disposable environments and mature GitOps

prune in production requires care: a path error in the PR can remove resources. Use Prune=false annotation on critical objects and protect the repository with mandatory review.

Drift: the silent enemy

Drift happens when someone:

• edits the Deployment in the dashboard;
• runs kubectl set image;
• applies a stray manifest;
• changes an HPA that changes replicas (replicas managed by HPA should not be in Git).

argocd app diff portal-homolog
argocd app history portal-homolog

HPA + replicas in Git is an eternal fight: ArgoCD wants 2, HPA wants 6. Remove replicas from the managed manifest when there is an HPA.

Secrets in GitOps

Do not commit Secret. Options:

• Sealed Secrets: encrypts and can go to Git.
• External Secrets Operator: fetches from Vault/secret manager.
• SOPS + age: encryption in the repository.

ArgoCD only needs to see the final resource; the secret origin stays outside.

Lab

1. Install ArgoCD and access the UI.
2. Create a GitOps repository with a simple Deployment.
3. Create the Application and synchronize.
4. Change the Deployment by hand (kubectl scale) and see selfHeal return to the Git value.
5. Delete the Deployment and confirm recreation.
6. Make a commit with replicas: 3 and follow the automatic sync.
7. Remove the resource from Git and see prune act.
8. Provoke an error (non-existent image) and observe Degraded + retry.

Common errors

Symptom	Cause
Eternal OutOfSync	field managed by another controller (HPA, webhook)
ComparisonError	wrong repo/path/branch or credential
Degraded after sync	image pull, quota, PVC pending
Orphan resource	prune: false
Sync overwrites HPA	replicas in manifest
Secret in Git	lack of Sealed/External Secrets
Sync loop	cluster default differs from manifest (ignoreDifferences)

ignoreDifferences is palliative: use when the field is really managed by another component, not to hide real drift.

Checklist

• [ ] ArgoCD with SSO and RBAC (local admin only at bootstrap).
• [ ] GitOps repository separate from application code.
• [ ] selfHeal and prune conscious per environment.
• [ ] replicas outside manifest where there is HPA.
• [ ] Secrets via Sealed/External Secrets.
• [ ] argocd app diff part of the PR process.
• [ ] Alerts for Degraded and OutOfSync.
• [ ] Backup of the GitOps repository.

Glossary

• Application: CRD that links repo/path to a destination.
• sync: apply the desired state.
• prune: remove resources absent from Git.
• selfHeal: automatically revert drift.
• drift: divergence between Git and cluster.
• app-of-apps: pattern of Applications that manage Applications.

Next

With versioned and reconciled deploy, the detail that the user feels is missing: zero downtime. Probes, rolling update, PDB, and HPA in the next chapter.

Next: Kubernetes Course 23 — Deploy without downtime: probes, rolling update, and HPA