Skip to main content

​
Design Philosophy

Argo CD is designed with a component-based architecture that provides:

Modularity

Components interact via interfaces, allowing replacement without system-wide changes

Single Responsibility

Clear boundaries help determine where functionality should be implemented

Reusability

Well-defined interfaces promote service discoverability and reuse

​
Architecture Overview

The default Argo CD installation includes multiple components and Kubernetes controllers. Controllers use proprietary interfaces (CRDs) and lack the modular nature of components.

​
Logical Layers

Argo CD’s architecture is organized into four logical layers with top-down dependencies:

​
UI Layer

The presentation layer where users interact with Argo CD.

Web App

Powerful web interface for managing applications deployed in Kubernetes clusters

CLI

Command-line tool for automation, scripting, and interacting with the Argo CD API

​
Application Layer

Provides capabilities supporting the UI layer.

API Server

Exposes the proprietary API that powers both the Web App and CLI functionality. Handles authentication, authorization, and request routing.

​
Core Layer

Implements the main GitOps functionality through components and Kubernetes controllers.
Responsibilities:
  • Reconciles Application resources in Kubernetes
  • Synchronizes desired state (from Git) with live state (in Kubernetes)
  • Reconciles Project resources
  • Continuously monitors and maintains application health
Type: StatefulSet

​
Infrastructure Layer

Tools that Argo CD depends on for its infrastructure.
Purpose:
  • Provides caching layer to reduce requests to Kubernetes API and Git providers
  • Supports UI operations
  • Improves performance and responsiveness
Type: Deployment
Purpose:
  • Controllers connect to Kubernetes API for the reconciliation loop
  • Stores all Argo CD resources and configuration
  • Target for application deployments
Type: External Dependency
Purpose:
  • Stores desired state of Kubernetes resources
  • Source of truth for GitOps workflows
  • Supports Git repos, Helm repos, and OCI artifact repos
Type: External Dependency
Purpose:
  • Provides authentication with external OIDC providers
  • Enables SSO integration
  • Can be replaced with other OIDC solutions
Type: Deployment (Optional)
Check the user management documentation for alternatives to Dex.

​
Component Dependencies

The diagram shows dependencies between components: Component Dependencies Dependency Rules:
  • Components in upper layers may depend on components in lower layers
  • Components in lower layers never depend on components in upper layers
  • This maintains clear separation of concerns and prevents circular dependencies

​
Development Implications

​
Working with the Repo Server

When developing features that involve manifest generation:
1

Understand the Pipeline

Source (Git/Helm/OCI) → Repo Server → Manifests → Application Controller → Kubernetes
2

Consider Caching

Redis caches results to improve performance. Clear cache during development for testing.
3

Test with Multiple Tools

Verify your changes work with Helm, Kustomize, and plain YAML manifests.

​
Working with Controllers

When modifying controller behavior:
Reconciliation Loop Considerations
  • Controllers continuously reconcile desired vs. actual state
  • Ensure your changes don’t create infinite reconciliation loops
  • Test performance impact with multiple applications
  • Consider rate limiting and back-off strategies

​
API Server Development

When adding API endpoints: 
// Example API server considerations:
// 1. Authentication and authorization checks
// 2. Input validation
// 3. Rate limiting
// 4. Audit logging
// 5. Error handling and user-friendly messages

​
Port Reference

When running locally or debugging:
ComponentAPI PortMetrics PortDebug Port
argocd-server808080839345
argocd-repo-server808180849346
argocd-redis6379--
argocd-applicationset-controller-80859347
argocd-application-controller-80869348
argocd-notifications-controller-80879349
These ports are used by Tilt development setup. See the Tilt guide for more details.

​
Resource Storage

Argo CD stores its state in Kubernetes as Custom Resources: 
apiVersion: argoproj.io/v1alpha1
kind: Application
Represents a deployed application with its source and destination.

​
Next Steps

Running Locally

Run Argo CD components locally for development

Debugging

Debug Argo CD components

UI Extensions

Extend the Argo CD web interface

Custom Health Checks

Add health checks for custom resources

Build docs developers (and LLMs) love

Get started for freeTalk to us