Skip to content

OCM + ArgoCD ApplicationSet — Guestbook Architecture

Guestbook is deployed to OCM spoke clusters via an ApplicationSet with the clusterDecisionResource generator and ArgoCD managed-mode agents.

Components

Node Role Tech Description
Git Repo Source argoproj/argocd-example-apps Upstream Git repo containing guestbook manifests
OCM Placement OCM Placement → PlacementDecision Selects managed clusters via label open-cluster-management.io/managed-by-ocm
ApplicationSet Generator clusterDecisionResource controller Queries OCM PlacementDecisions; generates one Application per spoke in its namespace on the hub
ArgoCD Principal Orchestration argocd-agent-principal (LoadBalancer) Central hub that watches spoke-namespace Applications and pushes specs to agents via gRPC
Agent · Spoke-N Agent argocd-agent-agent (ManifestWork) Per-spoke agent that receives Application specs and syncs Git manifests to the cluster
guestbook · Spoke-N Workload guestbook-ui:80 Resulting Deployment + Service in the guestbook namespace

Flow: Guestbook Sync (6 steps)

  1. OCM evaluates Placement (placement → appset) The guestbook Placement matches all managed clusters. OCM creates a PlacementDecision in the argocd namespace listing ocm-spoke-1 and ocm-spoke-2.

  2. AppSet generates per-spoke Applications (appset → principal) The clusterDecisionResource generator reads PlacementDecisions via the ocm-placement-generator ConfigMap. For each decision it renders an Application CR in the spoke's hub namespace (ocm-spoke-N). The Application template uses {{clusterName}} for both the namespace and destination cluster reference.

  3. Principal pushes to Spoke-1 (principal → agent1) Principal detects the new Application in ocm-spoke-1 namespace and pushes the spec to the spoke-1 agent over an mTLS gRPC tunnel.

  4. Agent syncs → deploys on Spoke-1 (agent1 → pod1) Agent fetches manifests from the guestbook Git repo path and applies them to the spoke-1 cluster, creating the guestbook-ui Deployment and Service.

  5. Principal pushes to Spoke-2 (principal → agent2) Same push mechanism, targeting the spoke-2 agent.

  6. Agent syncs → deploys on Spoke-2 (agent2 → pod2) Identical sync and apply, resulting in an identical guestbook deployment on spoke-2.

Key Design Decisions

  • Placement-based multi-cluster expansion: The ApplicationSet generator replaces imperative per-spoke Application creation. Adding a new spoke only requires registering it with OCM — the Placement automatically covers it.
  • Managed mode: Each spoke runs its own ArgoCD agent. The principal never needs direct kubeconfig access to spokes; it communicates via agent gRPC.
  • Declarative source of truth: Both the Placement and ApplicationSet are YAML files in the repo (ocm/configs/guestbook/), applied once to the hub.
  • Auto-sync + self-heal: The Application syncPolicy ensures continuous reconciliation. If someone deletes the pod on a spoke, the agent recreates it.

Files

  • ocm/configs/guestbook/placement-guestbook.yaml — OCM Placement
  • ocm/configs/guestbook/appset-guestbook.yaml — ApplicationSet + generator
  • ocm/configs/monitoring/generator-configmap.yaml — Shared ocm-placement-generator ConfigMap
  • ocm/scripts/setup-argocd-ocm-k3d.sh — Applies the above during setup