Go Report Card

GitHub release

CI

Vulnerabilities

Security Rating

Ask DeepWiki

KubeFlex

A flexible and scalable platform for running Kubernetes control plane APIs with multi-tenancy support.

Overview

KubeFlex is a CNCF sandbox project under the KubeStellar umbrella that enables “control-plane-as-a-service” multi-tenancy for Kubernetes. It provides a new approach to multi-tenancy by offering each tenant their own dedicated Kubernetes control plane and data-plane nodes in a cost-effective manner.

Architecture

KubeFlex implements a sophisticated multi-tenant architecture that separates control plane management from workload execution:

KubeFlex Architecture
KubeFlex Architecture

Core Components

  1. KubeFlex Controller: Orchestrates the lifecycle of tenant control planes through the ControlPlane CRD
  2. Tenant Control Planes: Isolated API server and controller manager instances per tenant
  3. Flexible Data Plane: Choose between shared host nodes, vCluster virtual nodes, or dedicated KubeVirt VMs
  4. Unified CLI (kflex): Single binary for initializing, managing, and switching between control planes
  5. Storage Abstraction: Configurable backends from shared Postgres to dedicated etcd

Supported Control Plane Types

  • k8s: Lightweight Kubernetes API server (~350MB) with essential controllers, using shared Postgres via Kine
  • vcluster: Full virtual clusters based on the vCluster project, sharing host cluster worker nodes
  • host: The hosting cluster itself exposed as a control plane for management scenarios
  • ocm: Open Cluster Management control plane for multi-cluster federation scenarios
  • external: Import existing external clusters under KubeFlex management (roadmap)

For detailed architecture information, see the Architecture Guide.

Multi-Tenancy Approach

KubeFlex addresses the fundamental challenge of Kubernetes multi-tenancy by providing each tenant with a dedicated control plane while maintaining cost efficiency through shared infrastructure. This approach delivers strong isolation at both control and data plane levels.

For a comprehensive analysis of multi-tenancy approaches and KubeFlex’s solution, see the Multi-Tenancy Guide.

Installation

kind and kubectl are required. A kind hosting cluster is created automatically by the kubeflex CLI. You may also install KubeFlex on other Kube distros, as long as they support an nginx ingress with SSL passthru, or on OpenShift. See the User’s Guide for more details.

Download the latest kubeflex CLI binary release for your OS/Architecture from the release page and copy it to /usr/local/bin using the following command:

sudo su <<EOF
bash <(curl -s https://raw.githubusercontent.com/kubestellar/kubeflex/main/scripts/install-kubeflex.sh) --ensure-folder /usr/local/bin --strip-bin
EOF

If you have Homebrew, use the following commands to install kubeflex:

brew tap kubestellar/kubeflex https://github.com/kubestellar/kubeflex
brew install kflex

To upgrade the kubeflex CLI to the latest release, you may run:

brew upgrade kflex

Quick Start

Get started with KubeFlex quickly by following our Quick Start Guide. The guide includes:

  • Basic multi-tenant setup with step-by-step commands
  • Advanced development team scenarios with complete isolation
  • Context switching and control plane management
  • Cleanup and best practices

Goals and Features

Core Capabilities

  • Lightweight API Servers: Provide dedicated Kubernetes API servers with minimal resource footprint
  • Flexible Storage Architecture: Support shared databases, dedicated storage, or external systems
  • Custom API Server Builds: Use upstream Kubernetes or specialized builds like multicluster-controlplane
  • Unified Management: Single CLI for all control plane lifecycle operations

Architecture Flexibility

  • Storage Options: Shared Postgres, dedicated etcd, or Kine+Postgres configurations
  • API Server Variants: Standard kubernetes API servers or trimmed-down specialized builds
  • Integration Ready: Designed to work with existing Kubernetes ecosystem tools

Operational Excellence

  • Zero-Touch Provisioning: Automated control plane creation and configuration
  • Context Management: Seamless switching between tenant environments
  • Lifecycle Management: Complete control plane creation, update, and deletion workflows

Documentation

Community and Support

License

KubeFlex is licensed under the Apache 2.0 License. See LICENSE for the full license text.

KubeFlex is part of the KubeStellar project, a CNCF sandbox initiative focused on multi-cluster configuration management for edge, multi-cloud, and hybrid cloud environments.