Home DevOpsGitOps with Argo CD: A Beginner’s Guide to Continuous Delivery

GitOps with Argo CD: A Beginner’s Guide to Continuous Delivery

by Knowledge Base Linux
GitOps with Argo CD - Git repository syncing to Kubernetes illustration

In a traditional CI/CD setup, a pipeline pushes changes to your cluster and then forgets about them. If someone edits a deployment by hand afterwards, nothing notices. GitOps flips this around: a controller inside the cluster continuously compares the live state with the desired state stored in Git, and corrects any difference. This guide introduces GitOps with Argo CD, the most popular GitOps controller for Kubernetes, and deploys a real application with it.

What GitOps Actually Means – GitOps with Argo CD

GitOps rests on four ideas:

  • The entire system is described declaratively, usually as Kubernetes YAML in a Git repository.
  • The Git repository is the single source of truth. If it is not in Git, it should not exist in the cluster.
  • Software agents pull the desired state from Git and apply it automatically. Nothing pushes into the cluster from outside.
  • The same agents watch for drift and continuously work to match the live state to Git (self-healing).

The practical benefits are significant: every change is a Git commit with an author and a review trail, rollbacks are a git revert, and a destroyed cluster can be rebuilt by pointing Argo CD at the same repository.

Prerequisites – GitOps with Argo CD

  • A running Kubernetes cluster. A local Minikube installation on Ubuntu is perfect for learning.
  • kubectl configured to talk to the cluster.
  • A Git repository (public, for the first experiment) containing Kubernetes manifests.

Step 1: Install Argo CD

Argo CD runs inside its own namespace:

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

Wait until all pods show Running. Then expose the web UI locally with a port-forward:

kubectl port-forward svc/argocd-server -n argocd 8080:443

The initial admin password is stored in a secret. The username is admin:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d; echo

Open https://localhost:8080, log in, and change the password under User Info. Exploring the UI is the fastest way to build intuition for GitOps with Argo CD before you automate anything.

GitOps with Argo CD - drift detection and self-healing illustration

Step 2: Declare an Application

In GitOps, even Argo CD’s own applications are declared as YAML. An Application resource tells Argo CD which Git repository and path to watch, and where to deploy:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/YOUR-USERNAME/YOUR-REPO.git
    targetRevision: HEAD
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply it with kubectl apply -f application.yaml. Two automated options matter here: prune: true deletes resources that disappear from Git, and selfHeal: true reverts manual edits made directly in the cluster. Together they make Git the real source of truth rather than a suggestion.

Step 3: Make a Change the GitOps Way

Now edit a manifest in Git, for example change the replica count or the container image tag, commit, and push. Within about three minutes (the default polling interval), Argo CD detects the new commit, marks the application OutOfSync, and because automated sync is enabled, applies the change itself. Edit the same deployment with kubectl scale and watch Argo CD undo your change. That small experiment teaches the GitOps model better than any diagram.

Step 4: Roll Back

Because every state lives in Git history, a rollback is simply:

git log --oneline
git revert <bad-commit-sha>
git push

Argo CD then syncs the cluster back to the previous known-good state. There is no special rollback tooling to learn and no mystery about what changed: the diff is a normal Git diff.

Troubleshooting Common Problems

Application stuck in OutOfSync

Open the application in the UI and read the sync status and events. Common causes are invalid YAML, a missing namespace, or a resource the Argo CD service account cannot create. The UI’s app diff view shows exactly which fields differ.

Repository cannot be reached

For private repositories, add credentials under Settings > Repositories using a personal access token or an SSH deploy key, and confirm the cluster has outbound network access.

Sync keeps reverting a field you want

Some controllers, especially HorizontalPodAutoscaler, legitimately fight GitOps over fields like replica counts. Use the ignoreDifferences section of the Application to exclude those fields from comparison.

Best Practices for Production GitOps

When Argo CD manages more than a demo, structure matters. Use the app-of-apps pattern: one root Application that creates child Applications, so an entire environment is bootstrapped from a single kubectl apply. Separate configuration repositories from application code repositories; the CI pipeline builds images and updates image tags in the config repo, while developers review config changes like code. For multiple environments, keep a base set of manifests with per-environment overlays (Kustomize is the common choice) instead of copying folders that drift apart. Enable SSO and RBAC early, because the Argo CD UI can change production. Add notifications for failed syncs, and use sync waves and hooks when ordering matters, for example running database migrations before the new app version. Finally, back up your Git repositories religiously: in GitOps, Git history is your disaster-recovery plan.

Conclusion

GitOps with Argo CD turns deployments into a continuous, auditable reconciliation between Git and your cluster: declare the desired state, let the controller apply it, and roll back with a Git revert. Start with one small application and automated sync, then grow toward app-of-apps structures and multiple environments. The Argo CD official documentation covers advanced topics such as SSO, projects, and sync waves when you are ready.

You may also like

KbLinux

Typically replies within a day

Hello, Welcome to the site. Please click below button for chatting me through Telegram.