Skip to content

Open Cluster Manager (OCM)

Open Cluster Manager is a Kubernetes extension that enables multi-cluster management — hub clusters orchestrate workloads to spoke clusters using the clusteradm CLI.

Two approaches are available for spinning up a 3-cluster OCM lab (1 hub + 2 spokes):

Approach Runtime Directory Quick Start
KinD (via Containerlab) kindest/node:v1.31.0 ocm/ make demo
k3d rancher/k3s:v1.33.6-k3s1 root make ocm-demo

How OCM Works

Hub Initialization

clusteradm init installs the OCM cluster-manager operator on the hub. The hub kubeconfig is patched with the correct container IP before initialization so the generated join command uses the real address instead of 0.0.0.0.

Spoke Registration

Each spoke runs clusteradm join with:

  • A bootstrap token from the hub (via clusteradm get token)
  • The hub API server address
  • The spoke's cluster name
  • The hub CA certificate (extracted from the hub kubeconfig)

Cluster Acceptance

On the hub, clusteradm accept --clusters <name> approves CSRs and sets hubAcceptsClient: true on the ManagedCluster resource.

ArgoCD Integration (Manual)

ArgoCD can be layered on top of the OCM hub for GitOps-driven application delivery to managed spoke clusters using the argocd-agent-addon.

This is a manual extension — not included in make demo or make ocm-demo.

Prerequisites

Tool Purpose
helm 3.14+ — installs the agent addon

Setup

# After OCM is deployed and spokes are accepted (KinD — from ocm/):
make install-argocd       # Install argocd-agent-addon on hub
make setup-argocd-ocm     # Register spokes + create ApplicationSet + GitOpsCluster

# After OCM is deployed and spokes are accepted (k3d — from root):
make ocm-install-argocd       # Install argocd-agent-addon on hub
make ocm-setup-argocd-ocm     # Register spokes + create ApplicationSet + GitOpsCluster

ArgoCD Architecture

graph TB
  subgraph Hub["Hub Cluster"]
    OCM["OCM Hub<br/>cluster-manager"]
    ArgoCD["ArgoCD<br/>(managed by operator)"]
    AgentPrincipal["argocd-agent-principal"]
    GitOpsCluster["GitOpsCluster<br/>ocm-argo-integration"]
    Placement["Placement<br/>namespace: argocd"]
    AppSet["ApplicationSet<br/>ocm-demo-appset"]

    OCM --- Placement
    Placement --- GitOpsCluster
    GitOpsCluster --- AgentPrincipal
    AgentPrincipal --- ArgoCD
    ArgoCD --- AppSet
  end

  subgraph Spokes["Spoke Clusters"]
    S1["spoke1<br/>klusterlet + agent"]
    S2["spoke2<br/>klusterlet + agent"]
  end

  AgentPrincipal --- S1
  AgentPrincipal --- S2
  AppSet --- S1
  AppSet --- S2

  classDef hub fill:#1b5e20,color:#fff,stroke:#2e7d32
  classDef spoke fill:#0d47a1,color:#fff,stroke:#1565c0
  classDef agent fill:#e65100,color:#fff,stroke:#ef6c00
  class Hub hub
  class S1,S2 spoke
  class AgentPrincipal agent

GitOpsCluster Workflow

sequenceDiagram
  participant User as kubectl apply
  participant GitOps as GitOpsCluster CR
  participant Agent as agent-principal
  participant OCM as OCM Hub
  participant Spoke as Spoke Cluster

  User->>GitOps: Create GitOpsCluster<br/>(references Placement)
  GitOps->>Agent: Watch event
  Agent->>OCM: Query Placement decisions
  OCM-->>Agent: Return selected clusters (spoke1, spoke2)
  Agent->>Spoke: Deploy agent resources<br/>(argocd operator + CR)
  Note over Agent,Spoke: Agent manages lifecycle based on<br/>Placement membership

What the scripts do

KinD — make install-argocd (uses the argocd-agent-addon Helm chart):

  1. Adds the OCM Helm repo and installs ocm/argocd-agent-addon.
  2. The chart deploys the ArgoCD Operator, creates an ArgoCD custom resource, and runs the principal agent server.
  3. A default Placement (named placement in namespace argocd) is created.

k3d — make ocm-install-argocd (uses clusteradm install hub-addon):

  1. Runs clusteradm install hub-addon --names argocd-agent --namespace argocd.
  2. Same chart as KinD but installed via the official OCM addon interface.
  3. Patches the principal service type to NodePort (k3d has no load balancer).

make setup-argocd-ocm (KinD) — Registers spokes via argocd cluster add:

  1. Rewrites spoke kubeconfig server addresses to use internal container DNS names (spoke1-control-plane:6443).
  2. Installs the argocd CLI inside the hub container if missing.
  3. Runs argocd cluster add from inside the hub container.
  4. Creates a GitOpsCluster and sample ApplicationSet.

make ocm-setup-argocd-ocm (k3d) — Uses OCM addon framework (no argocd cluster add):

  1. Waits for ManagedClusterAddOn to become available — OCM addon framework auto-deploys the agent pod to each spoke via ManifestWork.
  2. Creates the default AppProject and guestbook Application resources in each managed cluster's namespace.