Argo CD Pull Integration with Open Cluster Management

A Kubernetes operator that enables pull-based Argo CD application delivery for multi-cluster environments using Open Cluster Management (OCM) and Argo CD Agent.

This repository provides the advanced pull model powered by argocd-agent, delivering superior Argo CD UI integration with full application status synchronization, detailed resource health, and live state comparison. While slightly more complex to set up than the basic model, the OCM GitOpsCluster custom resource automates the entire deployment setup process.

The basic pull model is also supported for simpler use cases.

TLDR: See Getting Started with Advanced Pull Model (argocd-agent)

Overview

Traditional Argo CD deployments use a "push" model where applications are pushed from a centralized Argo CD instance to remote clusters. This project enables a "pull" model where remote clusters pull their applications from a central hub, providing better scalability, security, and resilience.

Two Deployment Models

Basic Pull Model

The basic pull model is a simpler approach that wraps Argo CD Application CRs in OCM ManifestWork objects and distributes them to managed clusters. It uses Argo CD's skip-reconcile feature to prevent the hub from reconciling applications, allowing local Argo CD instances on managed clusters to handle reconciliation.

graph LR
    subgraph "Hub Cluster"
        ArgoCD[Argo CD]
        Controller[Pull Controller]
        OCMHub[OCM Hub]
    end
    
    subgraph "Managed Cluster"
        OCMAgent[OCM Agent]
        ArgoCDLocal[Argo CD Controller]
        K8sResources[K8s Resources]
    end
    
    ArgoCD -->|Applications| Controller
    Controller -->|wraps in ManifestWork| OCMHub
    OCMHub -->|pulls| OCMAgent
    OCMAgent -->|applies Application CR| ArgoCDLocal
    ArgoCDLocal -->|reconciles| K8sResources
    OCMAgent -.->|basic status| OCMHub

Loading

How it works:

1. Argo CD Applications on the hub are marked with apps.open-cluster-management.io/pull-to-ocm-managed-cluster: "true" label
2. Applications include the argocd.argoproj.io/skip-reconcile: "true" annotation to prevent hub-side reconciliation
3. A controller wraps these Applications in ManifestWork objects
4. OCM agents pull the ManifestWork and apply the Application CRs to managed clusters
5. Local Argo CD instances reconcile the applications
6. Basic status information is reflected back through ManifestWork

For complete documentation and deployment instructions, see: OCM Basic Pull Model Solution

Advanced Pull Model (argocd-agent)

The advanced pull model powered by argocd-agent provides multi-cluster GitOps with superior Argo CD integration. This model delivers the full Argo CD experience across all your clusters with complete status synchronization visible in the Argo CD UI.

graph LR
    subgraph "Hub Cluster"
        ArgoCD[Argo CD + Argo CD Agent Principal]
        GitOpsCluster[GitOpsCluster CR]
        Controller[GitOpsCluster Controller]
    end
    
    subgraph "Managed Cluster"
        ArgoCDAgent[Argo CD Agent]
        K8sResources[K8s Resources]
    end
    
    GitOpsCluster -->|automates setup| Controller
    Controller -->|deploys addon via OCM| ArgoCDAgent
    ArgoCD -->|Application CRs via gRPC| ArgoCDAgent
    ArgoCDAgent -->|reconciles Application| K8sResources
    ArgoCDAgent -.->|full status sync| ArgoCD

Loading

Key Benefits:

• Superior Argo CD UI Integration: Full application details, resource tree, live state, and sync status displayed perfectly in the Argo CD UI
• Complete Status Synchronization: Detailed resource health, sync state, and errors reflected back to the hub in real-time
• Better Argo CD Core Integration: Built on the official argocd-agent project with direct integration to Argo CD core
• Automated Setup via OCM GitOpsCluster: The OCM GitOpsCluster CR automates the entire deployment process - while more advanced than the basic model, it handles all complexity

How it works:

1. Create a OCM GitOpsCluster CR that references an OCM Placement to select target clusters
2. The controller automatically deploys OCM argocd-agent add-on, configures secure gRPC communication, manages certificates, and sets up cluster registration
3. argocd-agent connects to hub Argo CD and synchronizes applications with full status feedback

For detailed argocd-agent architecture and operational modes, see argocd-agent Documentation.

Comparison: Basic vs Advanced

Feature	Basic Pull Model	Advanced Pull Model (argocd-agent)
Ease of Setup	✅ Easier - minimal configuration	⚠️ More complex - automated via GitOpsCluster
Argo CD UI Display	⚠️ Limited UI information	✅ Full Argo CD UI with resource tree & live state
Application Status	⚠️ Basic status via ManifestWork	✅ Full detailed status via argocd-agent
Resource Health	⚠️ Limited health information	✅ Complete resource health details
Sync Status	⚠️ Basic sync information	✅ Detailed sync status and errors
Live State	⚠️ Not available	✅ Live state comparison
Argo CD Core Integration	⚠️ External controller	✅ Official argocd-agent project
Setup Automation	Manual RBAC and Argo CD setup	✅ Automated via GitOpsCluster CR
Certificate Management	Manual	✅ Automated
Cluster Registration	Manual cluster secrets	✅ Automated via addon
Skip Reconciliation	✅ Uses argocd.argoproj.io/skip-reconcile	✅ Agent handles reconciliation

When to Use Each Model

Use the Basic Pull Model if:

• You want quick setup with minimal components
• Basic status feedback is sufficient
• You're just getting started with pull-based deployments

Use the Advanced Pull Model (this repo) if:

• You need complete application status visibility on the hub
• You want automated setup and lifecycle management
• You need detailed resource health and sync information
• You need full Argo CD UI integration
• You want simplified management of many clusters via OCM GitOpsCluster CR

Getting Started with Advanced Pull Model (argocd-agent)

Installation

1. Setup OCM: Install Open Cluster Management on your hub cluster and register your managed clusters. See OCM Quick Start

2. Setup Load Balancer: Ensure your hub cluster has a load balancer configured for exposing Argo CD server to managed clusters for argocd-agent connectivity

3. Install Helm Chart:

# After OCM and load balancer setup:
#
# kubectl config use-context <hub-cluster>
helm repo add ocm https://open-cluster-management.io/helm-charts
helm repo update
helm search repo ocm
helm install argocd-agent-addon ocm/argocd-agent-addon

This installs the GitOpsCluster controller and creates a GitOpsCluster resource that automatically deploys argocd-agent to your managed clusters.

For complete documentation and deployment instructions, see: OCM Advanced Pull Model Argo CD Agent Solution

Understanding GitOpsCluster

The GitOpsCluster custom resource is the control plane for managing argocd-agent deployments. It automates the entire setup process:

• Cluster Selection: References an OCM Placement to select which managed clusters receive argocd-agent
• Automated Deployment: Deploys argocd-agent to all selected clusters via OCM addon framework
• Certificate Management: Automatically generates and distributes TLS certificates for secure gRPC communication
• Server Discovery: Auto-discovers Argo CD server address and port
• Status Monitoring: Provides conditions to track deployment status

Example GitOpsCluster configuration:

apiVersion: apps.open-cluster-management.io/v1alpha1
kind: GitOpsCluster
metadata:
  name: my-gitops-cluster
  namespace: open-cluster-management
spec:
  placementRef:
    kind: Placement
    name: argocd-placement  # OCM Placement to select clusters
  argoCDAgentAddon:
    mode: managed  # or "autonomous" - see argocd-agent docs

For detailed information about argocd-agent modes and configuration options, see the argocd-agent Documentation.

Development

See CONTRIBUTING.md for development guidelines.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

This project adheres to the Open Cluster Management Code of Conduct.

Community

• Slack: #open-cluster-mgmt on Kubernetes Slack
• GitHub Issues: Report bugs or request features
• Community: Open Cluster Management

License

argocd-pull-integration is licensed under the Apache License 2.0.