[ArgoCD] Architecture Internals: Source Code Level Deep Dive

User (Web UI / CLI / CI)
       |
       v
  API Server (gRPC/REST)
       |
       +-------> Repository Server (gRPC)
       |                |
       +-------> Application Controller
       |                |
       +-------> Redis (TCP)
       |
       +-------> Dex (OIDC)

// API Server gRPC service registration
func (s *ArgoCDServer) Run(ctx context.Context, listeners ...net.Listener) {
    grpcServer := grpc.NewServer(grpcOpts...)
    application.RegisterApplicationServiceServer(grpcServer, s.appService)
    repository.RegisterRepositoryServiceServer(grpcServer, s.repoService)
    project.RegisterProjectServiceServer(grpcServer, s.projectService)
    session.RegisterSessionServiceServer(grpcServer, s.sessionService)
}

1. User sends login request
2. API Server delegates OIDC auth to Dex (for SSO)
3. Dex authenticates against external IdP (GitHub, LDAP, etc.)
4. On success, JWT token is issued
5. Subsequent requests include JWT in Bearer header
6. API Server validates JWT and performs RBAC authorization

# Default policy format
p, ROLE, RESOURCE, ACTION, OBJECT, EFFECT

# Example: grant proj-admin all application permissions for my-project
p, role:proj-admin, applications, *, my-project/*, allow

# Group mapping
g, my-github-team, role:proj-admin

1. Application Controller requests manifest generation from repo-server
2. repo-server clones Git repository (shallow clone by default)
3. Checks out specified revision (branch, tag, commit)
4. Detects manifests in the path and renders with appropriate tool
5. Returns result to Application Controller and caches in Redis

// Tool detection logic (simplified)
func detectTool(path string) string {
    if fileExists(path, "Chart.yaml") {
        return "helm"
    }
    if fileExists(path, "kustomization.yaml") ||
       fileExists(path, "kustomization.yml") ||
       fileExists(path, "Kustomization") {
        return "kustomize"
    }
    return "directory" // plain YAML
}

1. Parse Chart.yaml for chart metadata
2. Run helm dependency build if dependencies exist
3. Load values files (default values.yaml + user overrides)
4. Run helm template to generate final manifests
5. Parse generated YAML and validate

1. Parse kustomization.yaml
2. Resolve bases/resources references
3. Apply patches and overlays
4. Apply namePrefix, nameSuffix, labels, annotations transforms
5. Output final YAML

# CMP configuration example - plugin.yaml
apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: custom-jsonnet
spec:
  version: v1.0
  generate:
    command: [jsonnet]
    args: [main.jsonnet]
  discover:
    fileName: main.jsonnet

Cache key: HASH(git-url + revision + path + tool + params)
Cache TTL: Default 24 hours (ARGOCD_REPO_SERVER_CACHE_EXPIRATION)
Cache invalidation: On Git revision change

// Informer-based resource watching (simplified)
func (c *ApplicationController) watchResources() {
    factory := informers.NewSharedInformerFactory(clientset, resyncPeriod)

    factory.Apps().V1().Deployments().Informer().AddEventHandler(
        cache.ResourceEventHandlerFuncs{
            AddFunc:    c.onResourceAdd,
            UpdateFunc: c.onResourceUpdate,
            DeleteFunc: c.onResourceDelete,
        },
    )
}

Loop:
  1. Query all Application resources
  2. For each Application:
     a. Request desired state (manifests) from Repository Server
     b. Query actual state from target cluster
     c. Compare desired vs actual state (Diff)
     d. Update Sync Status (Synced / OutOfSync)
     e. Update Health Status (Healthy / Degraded / Progressing, etc.)
     f. Execute auto-sync if enabled
  3. Wait until next cycle (default 180 seconds)

Comparison targets:
  - Last Applied Configuration (stored in annotation)
  - Live State (actual cluster state)
  - Desired State (manifests from Git)

Diff process:
  1. Normalize Live State and Desired State
  2. Remove defaults (fields auto-added by Kubernetes)
  3. Exclude ignored fields (resourceVersion, generation, etc.)
  4. Perform structural comparison of remaining fields

// Normalization example
func normalizeResource(resource *unstructured.Unstructured) {
    // Remove managed fields from metadata
    removeFields(resource, "metadata.managedFields")
    removeFields(resource, "metadata.resourceVersion")
    removeFields(resource, "metadata.uid")
    removeFields(resource, "metadata.generation")
    removeFields(resource, "metadata.creationTimestamp")

    // Remove status field (not declarative state)
    removeFields(resource, "status")
}

-- Custom health check defined in argocd-cm ConfigMap
hs = {}
if obj.status ~= nil then
    if obj.status.conditions ~= nil then
        for _, condition in ipairs(obj.status.conditions) do
            if condition.type == "Ready" and condition.status == "True" then
                hs.status = "Healthy"
                hs.message = condition.message
                return hs
            end
        end
    end
end
hs.status = "Progressing"
hs.message = "Waiting for resource to become ready"
return hs

1. User or Auto-Sync triggers Sync
2. Application Controller requests latest manifests from Repository Server
3. Start sync operation after manifest generation completes
4. Execute PreSync hooks (if any)
5. Synchronize main resources (equivalent to kubectl apply)
6. Execute PostSync hooks (if any)
7. Verify resource state via Health Check
8. Update Sync Status

# Sync Wave example
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: '-1' # Lower numbers execute first

Prune target identification:
  1. Query list of resources in cluster
  2. Filter resources with ArgoCD tracking label/annotation
  3. Identify resources not present in current Git manifests
  4. Delete according to cascade or foreground deletion policy

app|resources|CLUSTER_URL|NAMESPACE: resource tree cache
git|manifest|REPO_URL|REVISION|PATH: manifest cache
repo|connection|REPO_URL: connection state cache

1. User clicks SSO login in ArgoCD UI
2. API Server redirects to Dex authorization endpoint
3. Dex delegates auth to configured connector (e.g., GitHub)
4. User authenticates with external IdP
5. External IdP redirects to Dex callback URL
6. Dex generates ID Token (includes user info and groups)
7. API Server validates ID Token and issues ArgoCD JWT
8. JWT includes user group information (used for RBAC)

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-alpha
  namespace: argocd
spec:
  description: 'Team Alpha project'
  # Allowed source repositories
  sourceRepos:
    - 'https://github.com/org/team-alpha-*'
  # Allowed target clusters/namespaces
  destinations:
    - server: 'https://kubernetes.default.svc'
      namespace: 'team-alpha-*'
  # Allowed cluster-scoped resources (restricted)
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  # Denied namespace-scoped resources
  namespaceResourceBlacklist:
    - group: ''
      kind: ResourceQuota
    - group: ''
      kind: LimitRange
  # Role definitions
  roles:
    - name: developer
      description: 'Development team role'
      policies:
        - p, proj:team-alpha:developer, applications, get, team-alpha/*, allow
        - p, proj:team-alpha:developer, applications, sync, team-alpha/*, allow
      groups:
        - team-alpha-devs

Application Controller
  --gRPC--> Repository Server (manifest generation requests)
  --gRPC--> API Server (status updates)

API Server
  --gRPC--> Repository Server (repository validation)
  --HTTP--> Dex (authentication)
  --TCP---> Redis (cache/sessions)

Repository Server
  --TCP---> Redis (manifest cache)
  --HTTPS--> Git Server (repository clone)

- API Server generates and manages TLS certificates
- Each component loads certificates from argocd-server-tls Secret
- mTLS (mutual TLS) can be optionally enabled