clusteradm is the command-line tool for Open Cluster Management (OCM), providing a unified interface to manage multi-cluster Kubernetes environments from the command line.
Open Cluster Management (OCM) is a CNCF sandbox project that enables end-to-end visibility and control across your Kubernetes clusters using a powerful hub-agent architecture. OCM provides:
- Cluster Lifecycle Management: Register, manage, and monitor multiple Kubernetes clusters
- Application Distribution: Deploy and manage applications across multiple clusters
- Policy & Governance: Enforce security policies and compliance across your fleet
- Add-on Extensibility: Extend functionality with a rich ecosystem of add-ons
clusteradm serves as the primary CLI tool for interacting with OCM, enabling administrators to:
- Initialize hub clusters and register managed clusters
- Deploy and manage multi-cluster applications
- Configure policies and governance
- Manage cluster sets and placements
- Install and configure add-ons
curl -L https://raw.githubusercontent.com/open-cluster-management-io/clusteradm/main/install.sh | bash
go install open-cluster-management.io/clusteradm/cmd/clusteradm@latest
Download the latest binary from GitHub Releases and add it to your $PATH
.
Go 1.24+ is required to build from source.
git clone https://github.com/open-cluster-management-io/clusteradm.git
cd clusteradm
make build
./bin/clusteradm
Set up a multi-cluster environment in three steps:
# 1. Initialize the hub cluster
kubectl config use-context <hub-cluster-context>
clusteradm init
# 2. Join a managed cluster to the hub
kubectl config use-context <managed-cluster-context>
clusteradm join --hub-token <token> --hub-apiserver <hub-api-url> --cluster-name <cluster-name>
# 3. Accept the managed cluster on the hub
kubectl config use-context <hub-cluster-context>
clusteradm accept --clusters <cluster-name>
After each command, clusteradm provides the next command to execute, making the process seamless.
clusteradm organizes commands into logical groups for different aspects of cluster management.
Command | Description |
---|---|
create |
Create OCM resources (placements, cluster sets, sample apps, work) |
delete |
Delete OCM resources (cluster sets, tokens, work) |
get |
Display OCM resources (clusters, hub info, tokens, placements, work, add-ons) |
install |
Install hub add-ons |
uninstall |
Uninstall hub add-ons |
upgrade |
Upgrade cluster manager or klusterlet |
version |
Display clusteradm and cluster version information |
Command | Description |
---|---|
init |
Initialize a hub cluster |
join |
Join a cluster to the hub as a managed cluster |
accept |
Accept cluster join requests on the hub |
unjoin |
Remove a cluster from the hub |
clean |
Clean up OCM components from the hub cluster |
Command | Description |
---|---|
addon |
Manage add-ons (enable, disable, create) |
clusterset |
Manage cluster sets (bind, unbind, set) |
proxy |
Access managed clusters through the cluster proxy |
Get detailed logs by setting the klog flag:
# Basic logging
clusteradm <command> -v 2 > logfile.log
# Verbose logging to file
clusteradm <command> -v 99 --logtostderr=false --log-file=debug.log
clusteradm init [--use-bootstrap-token]
Deploys OCM hub components and returns the join command for managed clusters.
Note: Do not run
init
against a multicluster-controlplane instance. Useclusteradm get token --use-bootstrap-token
instead.
clusteradm get token [--use-bootstrap-token]
Retrieves the latest token for joining managed clusters.
clusteradm join --hub-token <token> --hub-apiserver <hub-url> --cluster-name <name> \
[--ca-file <ca-file>] [--force-internal-endpoint-lookup]
Installs the klusterlet agent on a managed cluster.
Options:
--ca-file
: Provide a custom CA file for hub verification--force-internal-endpoint-lookup
: Required for clusters behind NAT (e.g., kind clusters)
clusteradm accept --clusters <cluster1>,<cluster2>,...
Approves cluster join requests on the hub.
clusteradm unjoin --cluster-name <cluster-name>
Removes klusterlet components from a managed cluster.
# Install specific add-ons
clusteradm install hub-addon --names argocd
clusteradm install hub-addon --names governance-policy-framework
clusteradm addon enable --names <addon-name> --namespace <namespace> --clusters <clusters>
# Examples
clusteradm addon enable --names argocd --namespace argocd --clusters cluster1,cluster2
clusteradm addon enable --names governance-policy-framework --namespace open-cluster-management-agent-addon --clusters cluster1
clusteradm create clusterset <clusterset-name>
clusteradm clusterset bind <clusterset-name> --clusters <cluster1>,<cluster2>
clusteradm create placement <placement-name> --clusters <cluster1>,<cluster2>
clusteradm create sampleapp <app-name>
Creates and deploys sample applications using Argo CD ApplicationSets.
Access managed clusters through the cluster proxy:
clusteradm proxy health --cluster-name <cluster-name>
clusteradm proxy kubectl --cluster-name <cluster-name> -- <kubectl-args>
clusteradm uses version bundles to ensure compatibility between OCM components. You can:
- Use the default bundle:
clusteradm init
- Specify a version:
clusteradm init --bundle-version v0.16.0
- Override component versions:
clusteradm init --bundle-version-overrides /path/to/overrides.json
Example override file:
{
"ocm": "v0.16.1",
"app_addon": "v0.16.0",
"policy_addon": "v0.16.0",
"multicluster_controlplane": "v0.7.0"
}
# 1. Create a cluster set
clusteradm create clusterset production
# 2. Bind clusters to the set
clusteradm clusterset bind production --clusters web-cluster,api-cluster
# 3. Create a placement for the application
clusteradm create placement web-app-placement --clusterset production
# 4. Deploy using ManifestWork or Argo CD
clusteradm create work my-web-app --clusters web-cluster,api-cluster
# 1. Install policy framework
clusteradm install hub-addon --names governance-policy-framework
# 2. Enable on managed clusters
clusteradm addon enable --names governance-policy-framework \
--namespace open-cluster-management-agent-addon \
--clusters cluster1,cluster2
# 3. Enable config policy controller
clusteradm addon enable --names config-policy-controller \
--namespace open-cluster-management-agent-addon \
--clusters cluster1,cluster2
We welcome contributions! Please see our Contributing Guide for details on:
- Code contribution process
- Development environment setup
- Testing guidelines
- Community guidelines
- Website: open-cluster-management.io
- Slack: #open-cluster-mgmt on Kubernetes Slack
- Mailing List: [email protected]
- YouTube: OCM Community
- Community Meetings: Calendar
This project is licensed under the Apache License 2.0.
Built by the Open Cluster Management community