All posts

Getting Started with Argo CD: A Practical Guide to GitOps on Kubernetes

Noah Burrell
kubernetes argo-cd gitops

If you have been working with Kubernetes for any length of time, you have probably experienced the pain of managing deployments manually. Keeping track of what is running where, ensuring your clusters match your intended state, and rolling back when things go wrong can quickly become overwhelming. This is the problem that Argo CD solves.

What is Argo CD?

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. Instead of pushing changes to your cluster with kubectl apply or CI pipelines that run deployment scripts, Argo CD continuously monitors your Git repository and ensures your cluster state matches what is defined there.

The core principle is simple: Git is the source of truth. Every change to your applications and infrastructure goes through Git, giving you a complete audit trail, easy rollbacks, and the ability to reproduce any environment from a single repository.

Why GitOps?

Before diving into the setup, it is worth understanding why GitOps has gained so much traction:

  • Auditability - Every change is a Git commit. You always know who changed what, when, and why.
  • Reproducibility - Your entire cluster state is defined in code. Spin up a new environment by pointing Argo CD at a repository.
  • Drift detection - Argo CD continuously compares the desired state in Git with the live state in your cluster and alerts you when they diverge.
  • Self-healing - Configure Argo CD to automatically sync, and it will correct any manual changes or drift in your cluster.
  • Developer experience - Developers use the tools they already know (Git, pull requests, code review) to deploy applications.

Installing Argo CD

Getting Argo CD running in your cluster takes just a few commands:

kubectl create namespace argocd

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

This deploys the Argo CD server, repo server, application controller, and supporting components into the argocd namespace.

Once the pods are running, retrieve the initial admin password:

argocd admin initial-password -n argocd

To access the UI, you can port-forward the Argo CD server:

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

Then open https://localhost:8080 in your browser and log in with the username admin and the password you retrieved above.

Deploying Your First Application

Argo CD uses the concept of an Application to represent a deployed set of Kubernetes resources. An Application ties together a Git repository (the source) and a target cluster and namespace (the destination).

Here is a minimal Application manifest using the official argocd-example-apps repository which can be applied directly to your cluster:

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated: {}
    syncOptions:
      - CreateNamespace=true
EOF

Argo CD will immediately detect the new Application, clone the repository, render the manifests from the specified path, and sync them to the target namespace. Within seconds you should see your application appear in the Argo CD UI with a green "Synced" and "Healthy" status.

Key Concepts to Understand

Projects

Projects provide a logical grouping of applications. They let you restrict which repositories, clusters, and namespaces an application can use. The default project is permissive, but for production environments you should define dedicated projects with tighter controls.

Sync Policies

The syncPolicy section controls how Argo CD handles changes:

  • Automated sync - Argo CD automatically applies changes when it detects drift between Git and the cluster.
  • Prune - Resources that exist in the cluster but are no longer defined in Git get deleted.
  • Self-heal - If someone manually changes a resource in the cluster, Argo CD reverts it to match Git.

For teams just starting out, I recommend enabling automated sync but leaving both prune and self-heal off. When you are new to Argo CD and Kubernetes, it can be confusing to have resources unexpectedly deleted or manual changes reverted before you understand why. Once your team is comfortable with the GitOps workflow and treats Git as the sole source of truth, enabling prune and self-heal is a natural next step.

Health Checks

Argo CD understands the health of Kubernetes resources. A Deployment is not considered healthy until its pods are running and passing readiness checks. This means the Argo CD UI gives you an accurate picture of your application's actual state, not just whether manifests were applied successfully.

Best Practices

After working with Argo CD across many environments, here are the patterns I have seen work well:

Separate your application code from your deployment manifests

Keep your Kubernetes manifests in a dedicated repository (or at least a dedicated directory) separate from your application source code. This decouples the deployment lifecycle from the development lifecycle. Your CI pipeline builds and publishes a container image, then updates the image tag in the manifests repository. Argo CD picks up the change and deploys it.

Use Kustomize or Helm for environment management

Rather than duplicating manifests for each environment, use Kustomize overlays or Helm values files to manage differences between staging and production. Argo CD has native support for both.

Start with the App of Apps pattern

As the number of applications grows, managing individual Application manifests becomes tedious. The App of Apps pattern uses one Argo CD Application to manage a directory of other Application manifests. Add a new service by committing a YAML file, and Argo CD takes care of the rest.

Implement RBAC early

Argo CD has a built-in RBAC system that integrates with SSO providers. Define roles that match your team structure from the start. Developers might only need read access and the ability to sync their own applications, while platform engineers manage the broader configuration.

What's Next

This guide covers the fundamentals, but Argo CD has much more to offer. In future posts I plan to explore:

  • ApplicationSets for templating applications across multiple clusters and environments
  • Notifications for integrating Argo CD events with Slack, email, and other channels
  • Secrets management strategies for handling sensitive data in a GitOps workflow
  • Multi-cluster deployments and the patterns that make them manageable

If you are looking for hands-on help adopting Argo CD or GitOps practices in your organization, get in touch. I offer training, architecture reviews, and embedded support to help teams get the most out of their Kubernetes platform.