Dapr meets GitOps: A Guide to Dapr and Argo CD

In the evolving world of platform engineering, consistency, resilience, and developer velocity are critical. That’s where Dapr—the Distributed Application Runtime—shines. It abstracts away the complexities of building distributed systems by offering pluggable building blocks for service invocation, state management, pub/sub messaging, and more. Platform teams can provide these capabilities as standardized, reusable primitives that developers consume without worrying about the underlying infrastructure.

When combined with Argo CD’s GitOps automation for Kubernetes, Dapr enables platform engineers to enforce consistent operational practices while empowering application teams to self-serve deployments. Git becomes the single source of truth, and Argo CD ensures the cluster always reflects what’s declared in version control. The result: reduced complexity for developers, automated infrastructure governance, and faster, safer application delivery.

This guide shows how to integrate Dapr and Argo CD to streamline microservices development and deployment. If you’re already familiar with Dapr concepts, this hands-on walkthrough will show you how to scale these benefits across environments with minimal friction.

Argo CD Concepts

Argo CD Applications

An Application is a Kubernetes custom resource definition (CRD) that forms the cornerstone of Argo CD's GitOps approach. It defines:

• Source: Where your application configuration lives, like a git repository, Helm chart, or directory path.
• Destination: Where your application should be deployed, for example, a Kubernetes cluster and namespace.
• Sync Policy: How Argo CD should keep your application in sync with your Git repository.
• Sync Options: Special behaviors to apply during synchronization.

This resource creates a declarative link between your Git repository (the source of truth) and your Kubernetes cluster, allowing Argo CD to continuously monitor and reconcile differences between them.

‍

Sync Policies and Options

Sync policies determine how Argo CD maintains synchronization between the desired state and the system that is actually deployed on your cluster. For example:

• Automated Sync: Automatically apply changes from Git to your cluster.
• Prune Resources: Remove Kubernetes resources that no longer exist in Git.
• Self-Heal: Revert unauthorized changes made directly to the cluster.

Sync options provide additional control over the synchronization process. For example:

• CreateNamespace=true: Automatically create the target namespace if it doesn't exist.
• Apply/Patch Options: Control how resources are applied to the cluster.
• RespectIgnoreDifferences=true: During the sync stage, respect the `IgnoreDifferences` configuration (described below).
• Resource customizations: Specify custom behaviors for certain resource types.

These configurations are crucial for automated GitOps workflows, ensuring that your applications deploy consistently across environments without manual intervention.

Ignore differences in application level config

Argo CD allows you to ignore differences at a specific JSON path in any of your Kubernetes resources.

When deploying Dapr using Argo CD, you will need to add the ignoreDifferences property to your application YAML:

ignoreDifferences:  
- group: apiextensions.k8s.io
  kind: CustomResourceDefinition    
  jsonPointers:      
  - /spec/conversion/webhook/clientConfig/service/namespace      
  - /spec/conversion/webhook/clientConfig/caBundle

This configuration is necessary because:

1. CRD Reconciliation: Dapr installs Custom Resource Definitions (CRDs) that Kubernetes controllers modify after installation.
2. Webhook Configurations: The caBundle and service namespace fields are dynamically updated by a Mutating webhook configuration.
3. Avoiding Sync Conflicts: Without these exclusions, Argo CD would continually try to revert these fields to match Git.

By telling Argo CD to ignore differences in these specific fields, you prevent unnecessary sync conflicts while still maintaining GitOps principles for your Dapr Kubernetes deployment.

Step-by-Step Integration Guide

You can also follow this step-by-step process in the following GitHub repository for a better reference: https://github.com/dapr/samples/tree/master/dapr-argocd

Pre-requisites: 

• A GitHub account.
• A Kubernetes cluster and kubectl

Step 1: Setup GitHub repository

Fork the repository https://github.com/dapr/samples/tree/master/dapr-argocd or create your own following the same structure.

Step 2: Install Argo CD

Start by installing Argo CD on your Kubernetes cluster:

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

Install the Argo CD CLI (macOS):

brew install argocd

For Linux and Windows users, follow the instructions here.

Access the Argo CD UI:

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

Retrieve and use the initial admin password:

argocd admin initial-password -n argocd
argocd login localhost:8080

Step 3: Deploy Dapr Using Argo CD

Create an Argo CD application to deploy Dapr, replace <your-repository> with your own repository (e.g., https://github.com/my-repo/dapr-argocd.git).

argocd app create dapr \
	--repo <your-repository> \
	--path gitops/dapr \
	--dest-server https://kubernetes.default.svc \
	--dest-namespace dapr-system

The corresponding YAML for this application:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: dapr
  namespace: argocd
spec:
  project: default
  source:
    repoURL: <your-repository>
    path: gitops/dapr
  destination:
    server: https://kubernetes.default.svc
    namespace: dapr-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
  # Important for Dapr CRDs
  ignoreDifferences:
    - group: apiextensions.k8s.io
      kind: CustomResourceDefinition
      jsonPointers:
        - /spec/conversion/webhook/clientConfig/service/namespace
        - /spec/conversion/webhook/clientConfig/caBundle

Sync the application:

argocd app sync dapr

Step 4: Deploy Redis Using Argo CD

Dapr needs a state store for its components. For this we will deploy Redis with the following command:

argocd app create redis \
  --repo <your-repository> \
  --path gitops/redis \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace redis

Sync and verify:

argocd app sync redis
kubectl get pods -n redis

Step 5: Configure Dapr Components

Create the namespace for your application:

kubectl create namespace argocd-demo

Deploy the Dapr components (in this case, a state store configuration):

argocd app create dapr-components \
  --repo <your-repository> \
  --path gitops/dapr-components \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace argocd-demo

Sync the components:

argocd app sync dapr-components

Step 6: Deploy Sample Applications

Deploy NodeJS and Python applications:

# Node application
argocd app create node \
  --repo <your-repository> \
  --path app/node \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace argocd-demo

# Python application
argocd app create python \
  --repo <your-repository> \
  --path app/python \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace argocd-demo

Sync and verify:

argocd app sync node
argocd app sync python

Verify the deployments:

kubectl get pods -n argocd-demo

Your applications should now be running with Dapr sidecars injected.

Navigating the Argo CD UI

The Argo CD UI provides a powerful visual interface for managing and monitoring your applications. Here's how to use it to verify your Dapr and application deployments:

Accessing the Application Dashboard

1. Navigate to your Argo CD UI (typically at https://localhost:8080 if port-forwarding)
2. Login using your credentials
3. You'll see the main applications dashboard showing all your Argo CD applications

Understanding the Application Tiles

Each application tile provides at-a-glance information:

• Health status: Green (Healthy), Yellow (Progressing), Red (Degraded)
• Sync status: Green (Synced), Yellow (Out of sync), Red (Unknown/Error)
• Application name and namespace

Drill Down into Application Details

Click on any application (e.g., "dapr") to view detailed information:

1. Summary tab: Shows overall status, sync history, and resource tree.
2. Sync status: Immediately see if your desired state matches the live state.
3. Resource tree: Hierarchical view of all Kubernetes resources in the application.

Verify Dapr and Component Deployments

For the Dapr application:

1. Check that all deployments, services, and CRDs are in a Healthy and Synced state
2. Verify that the Dapr control plane pods are running (look for dapr-* resources)
3. Ensure there are no failed resources in the tree view

For Dapr components:

1. Click on the "dapr-components" application
2. Verify the state store or pub/sub components appear in the resource tree
3. Check that they are properly synced and healthy

Debug Issues in the UI

If you encounter problems:

1. Red resources: Click on any red (unhealthy) resources to see detailed status
2. Events: View Kubernetes events related to problematic resources
3. Logs: Access logs directly from the UI by clicking on pods
4. Diff view: See exactly what differences exist between your Git and cluster states

Manually Triggering Sync

If applications are out of sync:

1. Click the "SYNC" button at the top of the application detail page
2. Review the resources that will be applied
3. Choose sync options if needed (e.g., "Prune" to remove resources)
4. Click "SYNCHRONIZE" to execute the sync operation

Viewing Application Topology

The Argo CD UI also offers a network view to visualize relationships:

1. Click on an application.
2. Select the "NETWORK" tab.
3. See a visual representation of how resources connect to each other.

This visualization is particularly helpful for understanding the relationship between your applications, the Dapr control plane, and Dapr components like the Redis state store.

Conclusion

For platform engineering teams, integrating Dapr with Argo CD delivers a powerful one-two punch: Dapr standardizes critical microservice capabilities like state stores and service communication, while Argo CD automates and audits every change through GitOps workflows.

This combination allows teams to enforce best practices, reduce deployment drift, and enable self-service infrastructure—all without sacrificing control or security. Dapr’s modular architecture means platform teams can evolve the underlying runtime independently, while developers continue to rely on a consistent, API-driven interface.

By adopting Dapr and Argo CD together, organizations gain a scalable, reliable foundation for cloud-native applications—one that reduces toil, fosters autonomy, and ultimately accelerates innovation.

Look out for Part II in this series: Using Diagrid Conductor with Argo CD.