ArgoCD: GitOps for Kubernetes

By Kokil Thapa | Last reviewed: September 2026

Manual kubectl apply breaks down the moment more than one engineer touches production. ArgoCD: GitOps for Kubernetes fixes that by treating Git as the single source of truth and letting the cluster reconcile declared state continuously. If you understand the Kubernetes control plane and worker node architecture, Argo CD adds a reconciliation controller on top. This guide covers install, Application CRDs, sync policies, RBAC, multi-cluster patterns, and the production mistakes I see on real deployments.

What is ArgoCD and how does GitOps for Kubernetes work?

GitOps means every change to cluster state flows through Git first. A human or CI pipeline commits YAML, opens a pull request, merges, and a controller applies the result. No one SSHes into a node to hot-patch a Deployment at 11 p.m.

Argo CD is the most widely adopted GitOps controller for Kubernetes. It runs inside the cluster as a set of controllers and a web UI. It polls Git (or receives webhooks), renders manifests, compares them to live resources, and syncs when drift appears.

The official Argo CD documentation describes four core components: the API server, repository server, application controller, and Redis cache. Together they form a pull-based pipeline that is auditable and reversible.

The OpenGitOps project defines four principles: declarative, versioned, automatically pulled, and continuously reconciled. Argo CD implements all four without requiring a proprietary pipeline language. Your manifests stay plain YAML, Helm charts, or Kustomize overlays.

On teams I work with that run Laravel on Kubernetes, GitOps removes the "works on my machine" deploy gap. Application code still ships through CI, but cluster configuration—Ingress rules, HPA thresholds, ConfigMaps—lives in Git and syncs through Argo CD. See our Kubernetes for Laravel getting started guide for the app-side setup.

Core Argo CD custom resources

Three CRDs matter day to day:

• Application — maps a Git source path to a destination cluster and namespace.
• AppProject — scopes which repos, clusters, and resource types an Application may use.
• ApplicationSet — generates many Applications from a template (monorepo folders, cluster labels, Git file generators).

AppProjects are your blast-radius control. Without them, any Application can deploy cluster-scoped resources like ClusterRoles to any registered cluster. Lock that down before onboarding ten microservice teams.

How do you install ArgoCD on a Kubernetes cluster?

Argo CD installs into its own namespace. The upstream manifest bundle is the fastest path for a lab cluster. Production clusters should pin a specific release tag and store the manifest in Git for repeatability.

1. Create the namespace: kubectl create namespace argocd
2. Apply the install manifest from the tagged release you chose.
3. Wait for all pods in argocd namespace to reach Running state.
4. Retrieve the initial admin password from the argocd-initial-admin-secret Secret.
5. Port-forward or expose the server through Ingress with TLS.
6. Change the default admin password and configure SSO.

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 -w

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

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

Install the CLI on your workstation for scripting and bootstrap tasks:

curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x argocd && sudo mv argocd /usr/local/bin/

argocd login localhost:8080 --username admin --password <initial-password> --insecure

If you built the cluster with Kubespray or another bare-metal tool, confirm your CNI and ingress controller are healthy first. A broken network policy blocks the repo server from reaching GitHub. Our Kubespray deployment guide covers node prep that Argo CD assumes is already done.

Production hardening checklist

Lab defaults are not production defaults. Before pointing Argo CD at a revenue cluster, address these items:

• Enable Dex or OIDC SSO instead of sharing the admin password.
• Restrict the server Service to ClusterIP and front it with Ingress plus cert-manager TLS.
• Configure repository credentials as Kubernetes Secrets referenced by Argo CD.
• Disable auto-sync on stateful workloads until you validate rollback behaviour.
• Set resource requests on Argo CD pods so they survive node pressure events.

For ongoing cluster administration beyond GitOps, our Linux system administration service covers the server-side work many Nepal teams outsource after the initial Kubernetes build.

How do you create an ArgoCD Application for GitOps deployment?

An Application CRD is the contract between Git and the cluster. Here is a minimal example deploying plain manifests from a repo subdirectory:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web-frontend
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/k8s-manifests.git
    targetRevision: main
    path: apps/web-frontend/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: web-prod
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply it with kubectl apply -f application.yaml or register it through the UI. Argo CD creates the destination namespace if CreateNamespace=true is set.

Helm and Kustomize need no special wrapper. Point source.path at a Kustomize overlay or set source.helm values inline or from a values file in the repo. Our Kustomize template-free config guide pairs well with Argo CD because both favour plain YAML over templating sprawl.

Sync policies that survive production

automated.selfHeal: true reverts manual kubectl edits. That is usually what you want for app Deployments. It is dangerous for CRDs managed outside Argo CD or for resources someone debugged by patching live.

automated.prune: true deletes cluster resources removed from Git. A bad commit that deletes a PersistentVolumeClaim name can cause data loss. Use PruneLast sync option or protect critical resources with the argocd.argoproj.io/sync-options: Prune=false annotation.

Progressive delivery integrates through Argo Rollouts. The Rollouts controller replaces Deployments with canary or blue-green strategies while Argo CD tracks the Rollout resource as the sync target. Validate your testing and optimization process before enabling auto-sync on customer-facing paths.

What is the difference between ArgoCD and Flux for GitOps?

Both controllers implement GitOps for Kubernetes. The choice often comes down to UI preference, multi-tenancy model, and how your team structures repos. I have run both on client infrastructure; neither is universally superior.

Pick Argo CD when developers and ops staff want a visual diff and one-click sync. Pick Flux when you prefer everything as Kubernetes CRDs with no separate UI server. Our detailed Flux vs Argo CD comparison walks through migration paths in both directions.

For multi-cluster fleets, Argo CD's hub-spoke model lets one management cluster host the Argo CD instance and push to registered child clusters. Read our multi-cluster GitOps patterns article before wiring production traffic across regions.

How do you manage secrets and RBAC in ArgoCD GitOps workflows?

Never commit plaintext Secrets to Git. That rule sounds obvious until someone base64-encodes a database password and calls it safe. Base64 is encoding, not encryption.

Common patterns that work in production:

• Sealed Secrets — encrypt Secrets client-side; only the cluster controller decrypts them.
• External Secrets Operator — sync from AWS Secrets Manager, HashiCorp Vault, or GCP Secret Manager.
• SOPS + age/GPG — encrypt values in Git; Argo CD decrypts at render time with a plugin or KSOPS.

Our Kubernetes secrets management guide covers rotation and audit trails that Argo CD alone does not provide. Treat the GitOps repo as sensitive even when Secrets are encrypted—RBAC on the repo matters.

AppProject RBAC example

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-payments
  namespace: argocd
spec:
  description: Payment microservices only
  sourceRepos:
    - https://github.com/myorg/payments-k8s.git
  destinations:
    - namespace: payments-*
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ""
      kind: Namespace
  namespaceResourceWhitelist:
    - group: apps
      kind: Deployment
    - group: ""
      kind: Service
    - group: networking.k8s.io
      kind: Ingress

Map OIDC groups to Argo CD roles in the argocd-rbac-cm ConfigMap. Developers get sync access to their AppProject. Only platform admins get cluster-level resource permissions.

When debugging RBAC issues, the JSON formatter tool helps prettify API error responses from failed sync attempts. Paste the Argo CD application conditions JSON and read the denied resource clearly.

How do you troubleshoot ArgoCD sync failures in production?

Most sync failures fall into five buckets. Work through them in order before escalating.

1. Render errors — invalid Helm values or Kustomize patch. Check the repo server logs.
2. Permission denied — AppProject whitelist blocks the resource kind or destination namespace.
3. Resource conflict — another controller owns the field Argo CD tries to set.
4. Health check stuck — Deployment has wrong label selector or probe never passes.
5. OutOfSync loop — a mutating webhook rewrites fields after sync; use ignoreDifferences.

Inspect application state from the CLI:

argocd app get web-frontend --show-operation
argocd app diff web-frontend
argocd app logs web-frontend

CrashLoopBackOff in the synced Deployment is an app problem, not an Argo CD problem. Argo CD applied the manifest correctly; the container fails at runtime. Our CrashLoopBackOff debugging guide covers the kubectl steps after GitOps confirms sync success.

Backup the Argo CD namespace and your Git repos together. Velero captures cluster state; Git captures desired state. After a disaster, restore Velero snapshots and let Argo CD reconcile. See Velero backup and restore for Kubernetes for the full procedure.

When should teams adopt ArgoCD GitOps for Kubernetes?

GitOps pays off when deploy frequency exceeds manual kubectl tolerance. Three engineers pushing YAML from laptops without review is the breaking point for most small teams.

Strong fit scenarios:

• Microservices with independent release cadences sharing one cluster.
• Regulated environments needing audit trails tied to Git commits.
• Multi-environment promotion (dev → staging → prod) via branch or overlay folders.
• Platform teams offering self-service namespaces to product squads.

Weak fit scenarios:

• Single monolith on one VPS with monthly deploys—a Deployer or GitLab CI SSH pipeline is simpler.
• Teams without Git discipline who bypass PR review under deadline pressure.
• Stateful systems where automated prune can delete PVCs before backups run.

On a booking platform like Adventure Third Pole Trek, Laravel handles the app layer while Kubernetes runs background workers and queue consumers. GitOps keeps worker Deployment replicas and HPA rules consistent across deploys without touching the PHP release pipeline.

For enterprise platforms with compliance requirements, our enterprise application development service includes GitOps pipeline design alongside application code. Budget-conscious Nepal teams often start at Rs 15,000–25,000/month (~USD 110–185) for managed cluster ops after the initial setup.

Pair Argo CD with CI that builds container images but does not apply manifests. CI pushes images and updates the image tag in Git; Argo CD syncs the tag change. That separation keeps credentials for cluster write access out of CI runners. The Kubernetes object management docs explain why declarative workflows scale better than imperative patches.

If you are bootstrapping GitOps from scratch, read our companion piece on GitOps with Argo CD declarative deployments and the Flux GitOps Toolkit deep dive before committing to either controller. Ongoing support belongs in a support and maintenance plan once the cluster carries production traffic.

Key Takeaways

• ArgoCD: GitOps for Kubernetes makes Git the source of truth; the controller reconciles drift on a loop you configure.
• Install from pinned release manifests, enable SSO, and scope teams with AppProjects before granting sync access.
• Use automated sync with caution—enable prune and selfHeal only after validating rollback and backup paths.
• Never store plaintext Secrets in Git; use Sealed Secrets, External Secrets, or SOPS encryption.
• Argo CD excels when teams want a visual diff UI and hub-spoke multi-cluster management; Flux suits CRD-only platform shops.
• Classify sync failures as render, RBAC, conflict, health, or drift loops before touching live resources manually.

People Also Ask

Does ArgoCD replace CI/CD pipelines?

No. CI builds, tests, and pushes container images. Argo CD handles continuous delivery—applying manifests to Kubernetes after the image exists. Keep CI credentials separate from cluster admin access for a cleaner security boundary.

Can ArgoCD deploy to multiple Kubernetes clusters?

Yes. Register external cluster credentials as Secrets and reference them in Application destinations. One Argo CD instance on a management cluster can sync Applications to many spoke clusters without installing Argo CD on each spoke.

What happens if someone kubectl edits a resource managed by ArgoCD?

With selfHeal enabled, Argo CD reverts the change on the next reconciliation cycle. With selfHeal disabled, the Application shows OutOfSync until someone syncs manually or merges a Git change that matches the live edit.

Is ArgoCD suitable for small teams without dedicated DevOps staff?

Yes, if one person owns the cluster and the team already uses Git for code review. The learning curve is the Application CRD model and sync policies, not Kubernetes itself. Single-VPS Laravel apps without Kubernetes should stay on simpler deploy tools until cluster complexity justifies GitOps.

Ship GitOps with confidence

ArgoCD: GitOps for Kubernetes turns deploy anxiety into a reviewable Git workflow. Start with one non-critical Application, manual sync, and a hardened AppProject. Add auto-sync and multi-cluster registration only after your backup, secrets, and rollback paths are tested.

Need help designing a GitOps pipeline for a Laravel app, eCommerce platform, or legal-tech portal? Contact us to plan the cluster architecture, Argo CD bootstrap, and the handoff your team can maintain. Explore more on the blog or review related work in the portfolio.