KubeCube Documentation

KubeCube follows a distributed architecture consisting of a management cluster and multiple business clusters.

Core Components:

• KubeCube Service: The central management component.
• Warden: An authentication agent deployed in each managed Kubernetes cluster.
• CloudShell: Provides command-line access to clusters.
• AuditLog Server: Handles operation auditing.

Deployment Model:

• The Warden component is the only part deployed within the individual business clusters.
• All other components (KubeCube Service, CloudShell, AuditLog Server) are deployed in the central management cluster.
• The architecture interacts with the Kubernetes API Server, Prometheus for monitoring, and internal log collection components.

KubeCube's architecture is composed of several key components distributed between a management cluster and managed business clusters:

• KubeCube Service, CloudShell, and AuditLog Server: These components are deployed in the management cluster.
• Warden: This component is deployed in each managed Kubernetes cluster, acting as an authentication proxy.

The architecture facilitates interaction between users, the Kubernetes API Server, Prometheus monitoring, and proprietary log collection components.

To get started with KubeCube, follow these steps in order:

1. Check Environment Requirements: Ensure your infrastructure meets the necessary prerequisites.
2. All In One Installation: Use the minimized 'All In One' deployment mode for quick setup.
3. Quick Experience: Follow the guided experience to explore the platform features.

KubeCube loads its configuration from a YAML file named kubecube.yaml. The system searches for this file in the following locations in order:

1. /etc/kubecube/kubecube.yaml
2. The current working directory (./kubecube.yaml)

Configuration is unmarshaled into a structured CubeOptions object which controls various components including the API Server, Controller Manager, Client Manager, Authentication Manager, and Logger.

# Example configuration structure (conceptual)
# The file should be named kubecube.yaml

# Configuration is loaded from:
# /etc/kubecube/kubecube.yaml
# or ./kubecube.yaml

The WardenOptions struct defines the configuration schema for the warden command. It aggregates two primary configuration blocks:

1. GenericWardenOpts: A *warden.Config object containing the core operational settings for the Warden component.
2. CubeLoggerOpts: A *clog.Config object used to configure the clog logging system.

Use NewWardenOptions() to initialize a new options instance with default configurations for both Warden and the logger.

// Initialize default options
opts := NewWardenOptions()

Use NewFakeClientsFor to create a mgrclient.Client by providing a customization function. This pattern is useful when you need fine-grained control over the internal fields of the FakerClient (such as discovery or restMapper) that are not exposed via the standard Options struct.

client := fake.NewFakeClientsFor(func(c *fake.FakerClient) {
    // Customize the FakerClient fields here
    // e.g., c.discovery = myDiscovery
})

Use NewFakeClients to create a mgrclient.Client implementation for testing multi-cluster operations. This function allows you to pre-populate the fake client with specific Kubernetes objects, lists, and runtime objects using an Options struct. This is useful for simulating a cluster state in unit tests without requiring a real Kubernetes API server.

opts := &fake.Options{
    Scheme: myScheme,
    Objs:   []client.Object{myObject},
    Lists:  []client.ObjectList{myList},
    ClientRuntimeObjs: []runtime.Object{obj1},
    ClientSetRuntimeObjs: []runtime.Object{obj2},
    MetricsRuntimeObjs: []runtime.Object{metricObj},
}
client := fake.NewFakeClients(opts)

Use NewClientFor to create a Client instance for managing Kubernetes resources. This function initializes a suite of clients including a direct client, a cache, a metrics client, a standard Kubernetes ClientSet, and discovery clients.

It automatically applies configuration settings (QPS, Burst, Timeout) from the environment via env.GetClusterClientConfig(). If ClusterCacheSyncEnable is true in the cluster configuration, it also starts a background routine to periodically refresh the discovery cache based on ClusterCacheSyncInterval.

import (
	"context"
	"k8s.io/client-go/rest"
	"github.com/kubecube-io/kubecube/pkg/multicluster/client"
)

// Assuming cfg is a valid *rest.Config
ctx := context.Background()
client, err := client.NewClientFor(ctx, cfg)
if err != nil {
	// handle error
}
// Use client.Direct() or client.Cache() to interact with the cluster

Use WrapCache to wrap a sigs.k8s.io/controller-runtime/pkg/cache.Cache. The wrapped cache will use a SingleVersionConverter to automatically convert objects retrieved via Get or List operations into the recommended version.

import (
	"sigs.k8s.io/controller-runtime/pkg/cache"
	"github.com/kubecube-io/kubecube/pkg/conversion"
)

// cac is an existing controller-runtime cache
// converter is a SingleVersionConverter implementation
wrappedCache := conversion.WrapCache(cac, converter)