Mastering Kubernetes Federation: Step‑by‑Step Installation and Multi‑Cluster Management

Background

Kubernetes Federation v2 (kubefed) provides a single control plane to manage resources such as Deployments, Services, ConfigMaps, and other API objects across multiple Kubernetes clusters. It enables cross‑cluster workload distribution, unified service discovery, and multi‑cloud or hybrid‑cloud deployments.

Installation

Helm

Install Helm (v2 or later) following the official documentation.

Federation controller plane

Add the kubefed chart repository and install the controller into the kube-federation-system namespace.

$ helm repo add kubefed-charts https://raw.githubusercontent.com/kubernetes-sigs/kubefed/master/charts
$ helm search repo kubefed
$ helm --namespace kube-federation-system upgrade -i kubefed kubefed-charts/kubefed --version=0.6.1 --create-namespace

kubefedctl binary

Download the latest kubefedctl release, extract it, and place it in /usr/local/bin (or another directory in $PATH).

$ wget https://github.com/kubernetes-sigs/kubefed/releases/download/v0.6.1/kubefedctl-0.6.1-linux-amd64.tgz
$ tar -zxvf kubefedctl-0.6.1-linux-amd64.tgz
$ mv kubefedctl /usr/local/bin/

Cluster registration

Configure kubeconfig contexts

List available contexts and switch to the primary (host) cluster before joining members.

$ kubectl config get-contexts
$ kubectl config use-context <strong>host-context</strong>

Join member clusters

Register each member cluster with the host cluster. The command creates a KubeFedCluster custom resource in the kube-federation-system namespace.

$ kubefedctl join <em>CLUSTER_NAME</em> \
    --cluster-context <em>MEMBER_CONTEXT</em> \
    --host-cluster-context <em>HOST_CONTEXT</em> \
    --v=2

Example:

$ kubefedctl join n1 --cluster-context n1 --host-cluster-context context-cluster1-admin --v=2
$ kubefedctl join n2 --cluster-context n2 --host-cluster-context context-cluster1-admin --v=2

Unjoin a cluster

$ kubefedctl unjoin n2 --cluster-context n2 --host-cluster-context context-cluster1-admin --v=2

List federated clusters

After joining, verify the stored cluster objects.

$ kubectl -n kube-federation-system get kubefedclusters
$ kubectl -n kube-federation-system get kubefedclusters -o yaml n1

Enable federated resource types

Before a resource can be federated, its API type must be enabled. kubefedctl enable accepts several identifiers:

Kind name (e.g., Deployment)

Plural name (e.g., deployments)

Group‑qualified plural (e.g., deployments.apps)

Short alias (e.g., deploy)

Enable a type:

$ kubefedctl enable Deployment
$ kubefedctl enable Service
$ kubefedctl enable ConfigMap

Enabling creates a corresponding Federated<Kind> CRD (e.g., FederatedDeployment) in the host cluster. Verify with:

$ kubectl get crd | grep federated

Federated namespace

Only resources inside a FederatedNamespace are propagated across clusters. Create the namespace objects before applying federated resources.

$ kubectl apply -f example/sample1/namespace.yaml -f example/sample1/federatednamespace.yaml

Deploy a sample application

Use the official demo repository (

github.com/kubernetes-sigs/kubefed/tree/master/example/sample1

) to test federation. $ kubectl apply -R -f example/sample1 If the command fails with an error such as “no matches for kind ‘Federated<type>’”, enable the missing type and retry. For the sample, ClusterRoleBinding must be enabled:

$ kubefedctl enable ClusterRoleBinding
$ kubectl apply -R -f example/sample1

Verification

After successful deployment, the federated resources appear in each member cluster. List them with standard kubectl commands, for example:

$ kubectl -n test get deployments
$ kubectl -n test get services

Confirm that the replica counts and other specifications match the desired state defined in the host cluster.

Common command reference

# Helm
helm list --all-namespaces
helm --namespace kube-federation-system upgrade -i kubefed kubefed-charts/kubefed --version=0.6.1 --create-namespace

# Cluster registration
kubefedctl join <em>CLUSTER</em> --cluster-context <em>CTX</em> --host-cluster-context <em>HOST_CTX</em> --v=2
kubefedctl unjoin <em>CLUSTER</em> --cluster-context <em>CTX</em> --host-cluster-context <em>HOST_CTX</em> --v=2

# Context handling
kubectl config get-contexts
kubectl config use-context <em>CTX</em>

# Inspect federated clusters
kubectl -n kube-federation-system get kubefedclusters
kubectl -n kube-federation-system get kubefedclusters -o yaml

# Enable resource types
kubefedctl enable Deployment
kubefedctl enable Service
kubefedctl enable ConfigMap
kubefedctl enable ClusterRoleBinding

# View federation API resources
kubectl api-resources | grep kubefed

# Uninstall federation controller
helm --namespace kube-federation-system uninstall kubefed
kubectl -n kube-federation-system delete FederatedTypeConfig --all