Managing Kubernetes deployments manually can quickly become complex and error-prone, especially as teams grow and applications scale. Developers often struggle to keep clusters in sync with the desired state, face delays in deployment due to manual processes, and encounter challenges tracking changes across environments. Frequent misconfigurations, lack of visibility, and slow recovery from failures make continuous delivery difficult to maintain

That’s where Argo CD comes in. It automates the deployment process by using a Git-based workflow, making it easier to manage, track, and roll back changes with confidence.

In this article, we explore Argo CD’s features and use it to deploy a simple demo app.

What is Argo CD? 

Argo CD is a tool that helps you deliver applications to Kubernetes. It uses a method called GitOps. This means it watches your Git repositories and applies any changes to your Kubernetes cluster automatically.

Kubernetes handles container tasks. It starts your containers, replaces them if they fail, and spreads your service across the computers in your cluster.

You get the best results from Kubernetes when you use it in a continuous delivery setup. When developers merge new code, the system runs automatic deployments. This way, updates reach the cluster quickly and follow the same steps every time.

Features Of Argo CD

Argo CD helps teams manage Kubernetes deployments with ease. It offers several useful features:

• GitOps-based deployment: Argo CD uses Git as the main source of truth. It keeps your Kubernetes clusters in sync with what’s written in the Git repository.
• Declarative application definitions: It supports tools like Helm, Kustomize, Jsonnet, and plain YAML to define how your apps should run.
• Automated synchronization: Argo CD automatically updates your Kubernetes cluster when someone changes the setup in Git. It makes sure the cluster always matches the desired state.
• Real-time application status monitoring: It checks the health and sync status of your apps all the time. You can see everything clearly through its web dashboard and difference (diff) views.
• Role-based access control (RBAC): Argo CD lets you control who can do what. You set permissions for different users and teams.
• Multi-cluster support: It manages many Kubernetes clusters at once, all from one place.
• Web UI and CLI: It gives you a simple web interface and a command-line tool to manage apps, view changes, and fix issues.

Intuit first released Argo CD in May 2019 as part of the Argo project. It supports GitOps-style continuous delivery for Kubernetes. Since then, it has become an important part of modern deployment workflows and joins the CNCF (Cloud Native Computing Foundation) ecosystem.

Read Also: Data Management in Kubernetes with Portworx

Core Elements of Argo CD Architecture

Argo CD is easy to learn once you get the basic concepts. Here are the main parts of Argo CD’s architecture:

Application controller: The Application Controller is a component you install in your Kubernetes cluster. It follows the Kubernetes controller pattern to check the state of your applications and compare them with the ones in your Git repository.

Application: An application in Argo CD is a set of Kubernetes resources that work together to deploy your application. Argo CD stores the details of each application as a Custom Resource Definition (CRD) in the cluster.

Live state: The live state shows the current setup of your application inside the cluster. For example, it includes the number of Pods and the image they’re using.

Target state: The target state is the desired version of your application as defined in your Git repository. When something changes in the repository, Argo CD works to update the live state to match the target state.

Refresh: A refresh happens when Argo CD fetches the target state from your Git repository. It compares the target state with the live state but does not apply any changes yet.

Sync: Sync is the process of applying the changes found during a refresh. Each sync moves your cluster closer to the target state.

API server: The Argo CD API server provides REST and gRPC APIs used by the CLI, Web UI, and other integrations.

Git repository: The Git repository is the single source of truth for your applications. It stores all the configurations for your apps and environments.

Now that you understand the basic concepts, you can follow the official documentation to deploy an example application to Kubernetes using Argo CD.

How Argo CD Works: From Git to Kubernetes

DevOps engineers, platform teams, and Kubernetes admins mostly use Argo CD. They use it to manage app deployments through a GitOps workflow.

Argo CD follows the GitOps model. This model treats your Git repository as the single source of truth. The repository stores everything your app needs to run like Kubernetes manifests, Helm charts, Kustomize templates, and config files. These files clearly show what a correct deployment looks like.

It compares what your Git repo declares with what is actually running in your Kubernetes cluster. If it finds a difference, it applies the changes needed to fix it. You can set this process to run automatically. That way, your cluster always stays in sync with the repo, even if someone changes things manually with Kubectl.

This offers both a command-line tool (CLI) and a web interface (UI). It supports multi-cluster and multi-user setups, works with single sign-on (SSO) systems, creates audit logs, and supports advanced deployment strategies like canary and blue/green deployments. It also allows rollbacks, so you can quickly go back to a stable version if something goes wrong.

Push vs. Pull CI/CD

Traditional CI/CD tools use a push model. In this model, your pipeline pushes updates to the Kubernetes cluster using tools like Kubectl or Helm. It needs direct access to your cluster.

Argo CD uses a pull model. It runs inside your Kubernetes cluster and pulls the latest changes from your Git repository. Then it applies the updates automatically, without needing a pipeline.

This pull-based method is safer. You don’t need to expose your cluster’s API or store credentials in your CI/CD platform. If someone hacks your Git repo, they only access your code, not your live cluster.

Read Also: An Ultimate Guide to Become a Certified Kubernetes Administrator (CKA)

Deploy a Basic NGINX Web Server with Argo CD

This guide helps you deploy a basic NGINX server using Argo CD. It assumes you already have a Kubernetes cluster and you install kubectl and helm on your machine.

Step 1: Create Your GitHub Repository

Go to GitHub and create a new repository. Clone the repo to your machine:

$ git clone https://github.com/<username>/<repo>.git

Create a file named deployment.yaml and add the following:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: argo-demo
  labels:
    app.kubernetes.io/name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: nginx
  template:
    metadata:
      labels:
        app.kubernetes.io/name: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
          - name: http
            containerPort: 80

This file defines a Deployment with 3 NGINX replicas.

Create another file service.yaml. It creates a LoadBalancer service that exposes your Deployment to the outside of your cluster.

apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: argo-demo
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: http

This exposes your NGINX app outside the cluster.

Finally, create a namespace file:

apiVersion: v1
kind: Namespace
metadata:
  name: argo-demo

Save your changes in your local repository, then upload them to GitHub.

$ git add .
$ git commit -m "Added initial Kubernetes YAML files"
$ git push

You’re all set to install Argo and begin deploying your app.

Step 2: Install the Argo CD CLI

Download the latest Argo CLI from GitHub. Choose the binary that matches your operating system. Make it executable and move it to a folder included in your system’s PATH. The steps below use version 2.6.1, so replace it with the latest version number.

$ wget https://github.com/argoproj/argo-cd/releases/download/v2.6.1/argocd-linux-amd64
$ chmod +x argocd-linux-amd64
$ mv argocd-linux-amd64 /usr/bin/argocd

Check if it works:

$ argocd version
argocd: v2.6.1+3f143c9
  BuildDate: 2023-02-08T19:18:18Z
  ...

Or install it using Homebrew:

$ brew install argocd

Step 3: Install Argo CD in Your Cluster

Next, install Argo in your Kubernetes cluster. This process adds the Argo CD API, controller, and Custom Resource Definitions (CRDs).

Start by creating a namespace for Argo:

$ kubectl create namespace argocd
namespace/argocd created

Next, use kubectl to apply Argo CD’s YAML manifest to your cluster. Before applying it, you can review the manifest to see which resources it will create.

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

It may take a few seconds for all Argo components to start running in your cluster. Use kubectl to list the deployments in the argocd namespace and monitor their progress.

Continue once all deployments are ready:

$ kubectl get deployments -n argocd
NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
argocd-applicationset-controller   1/1     1            1           67s
argocd-dex-server                  1/1     1            1           67s
argocd-notifications-controller    1/1     1            1           67s
argocd-redis                       1/1     1            1           67s
argocd-repo-server                 1/1     1            1           67s
argocd-server                      1/1     1            1           67s

Step 4: Access Argo CD

Argo CD doesn’t automatically make its API server available on an external IP. Instead, you can connect to it by starting a new port-forwarding session with kubectl. Open another terminal window and run the following command:

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

This command maps your local port 8080 to port 443 of Argo’s service. To open the Argo UI, go to localhost:8080 in your browser. You’ll likely see a warning that the connection is not secure—that’s because Argo uses a self-signed certificate.

It’s fine to use this setup while testing, but before moving to production, you should follow the steps in the Argo documentation to set up TLS properly using an Ingress route.

Before log in, you need to get the password for the default admin user. Argo generates this password automatically during installation. To find it, run the following argocd command:

$ argocd admin initial-password -n argocd
zHKv74zvDNtVMaOB

Use these credentials to log in to Argo.

After logging in, go to User Info in the left sidebar, then click the Update Password button at the top of the screen. Follow the steps to set a unique password of your choice.

Now you can delete the Kubernetes secret that holds the original admin password. Run the following command to remove it:

$ kubectl delete secret argocd-initial-admin-secret -n argocd
secret "argocd-initial-admin-secret" deleted

To log in to the Argo CLI, run the argocd login command and provide the API server’s URL as an argument, like this:

$ argocd login localhost:8080

Accept the self-signed certificate warning and enter your credentials.

Step 5: Register and Deploy Your App

You’re all set to begin deploying apps with Argo. To start, run the following CLI command to register your app:

$ argocd app create argo-demo \
  --repo https://github.com/<username>/<repo>.git \
  --path . \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace argo-demo
application 'argo-demo' created

Let’s break down what this command does:

• --repo tells Argo the URL of your Git repository.
• --path tells Argo where to look inside your repo for the files it needs to deploy, like Kubernetes manifests or Helm charts. We use . here because the files are in the root folder of the repo.
• --dest-server sets the address of the Kubernetes cluster where you want to deploy the app. If Argo is running in the same cluster, you can use kubernetes.default.svc.
• --dest-namespace sets the Kubernetes namespace where the app should go. This should match the metadata.namespace in your resource files.

After you run the command, Argo registers your app. To check its details, use the argocd app list command.

NAME              CLUSTER                         NAMESPACE   PROJECT  STATUS     HEALTH   SYNCPOLICY  CONDITIONS  REPO                                                   PATH  TARGET
argocd/argo-demo  https://kubernetes.default.svc  argo-demo   default  OutOfSync  Missing  <none>      <none>      https://github.com/ilmiont/spacelift-argo-cd-demo.git

The app also appears in the Argo web UI:

The app shows as “missing” and “out of sync” because creating it doesn’t automatically sync it with your cluster. To fix this, run a sync now so Argo can apply the current state defined in your repo.

$ argocd app sync argo-demo

The sync results appear in your terminal. You should see that the Namespace, Service, and Deployment objects are all synced to your cluster, just like in the output above. The messages for each object confirm they were created successfully.

$ argocd app list
NAME              CLUSTER                         NAMESPACE  PROJECT  STATUS  HEALTH   SYNCPOLICY  CONDITIONS  REPO                                                   PATH  TARGET
argocd/argo-demo  https://kubernetes.default.svc  argo-demo  default  Synced  Healthy  <none>      <none>      https://github.com/ilmiont/spacelift-argo-cd-demo.git  .   

Now the app is Synced and Healthy! It also appears in green in the Argo UI, showing that everything is working correctly.

As a final check, use kubectl to inspect the deployments in the app’s namespace. This will confirm that Nginx is running with three replicas.

Step 6: Update the App

Now, let’s update your app. Change the spec.replicas field in your deployment.yaml file to set the number of Pods in the Deployment to five:replicas from 3 to 5 in deployment.yaml.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: argo-demo
  labels:
    app.kubernetes.io/name: nginx
spec:
  replicas: 5
  ...

Commit and push:

$ git add .
$ git commit -m "Run 5 replicas"
$ git push

Sync the app again:

$ argocd app sync argo-demo

Check the updated deployment:

$ kubectl get deployment -n argo-demo

You should see 5 replicas now.

Enable Auto-Sync

To let Argo sync changes automatically

$ argocd app set argo-demo --sync-policy automated

To test auto-sync, change the spec.replicas field back to 3.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: argo-demo
  labels:
    app.kubernetes.io/name: nginx
spec:
  replicas: 3

Revert back to 3 replicas, commit and push:

$ git add .
$ git commit -m "Back to 3 replicas"
$ git push

Argo auto-syncs the change within 3 minutes. Check your deployment:

$ kubectl get deployment -n argo-demo

Step 7: Manage Your App

Argo’s command-line tool (CLI) and web app give you many ways to manage and check your deployments. You can start trying out the CLI commands and web interface to better control your app. Most features are available in both.

Click your app’s tile on the home screen to see an overview that shows its components along with their current sync and health states. Click the “App Details” button at the top left to view the app’s details, edit its configuration, and see events that show what Argo does.

Use the “History and Rollback” button to access previous deployments. This button lists all syncs Argo performs and gives you the option to restore an older version. If a deployment causes a bug, you use this screen to roll back before you push a fix to your repo.

Best Practices for Managing Kubernetes Deployments with Argo CD

Here are some best practices to follow when using Argo CD:

Use ApplicationSets for dynamic app management: Use ApplicationSets to automatically deploy similar apps (like for each tenant or cluster) from templates. This reduces manual work and avoids repeating the same configurations.

Pin Argo CD versions and CRDs: Do not let Argo CD or its custom resource definitions auto-upgrade. Instead, set specific versions to avoid unexpected changes or issues in production.

Use the app-of-apps pattern for hierarchical management: Manage large deployments using an “app of apps” approach. This means a main application controls multiple child applications, which makes managing them more organized.

Apply resource exclusions and ignore differences: Set up exclusions or diff rules (for example, ignore temporary annotations or status fields) to avoid false alerts about changes in the system.

Tag and label applications for automation and auditing: Add consistent labels and annotations to Argo CD apps. This helps with automation, filtering, reporting, and managing their lifecycle.

Run Argo CD in a dedicated namespace or cluster: Keep Argo CD in its own namespace or cluster. This makes access control easier, prevents conflicts, and simplifies management.

Conclusion

Argo CD simplifies Kubernetes application deployment by enabling GitOps workflows, where your Git repository becomes the source of truth. With features like the app-of-apps pattern, automated sync, rollback capabilities, and a secure pull-based model, Argo CD gives DevOps teams powerful control over application lifecycle management. By following the step-by-step guide to install Argo CD, deploy an NGINX app, and enable auto-sync, you’ve learned how to build a reliable, automated, and production-ready CI/CD pipeline in your Kubernetes environment.