Ksctl is a unified Kubernetes cluster management tool that simplifies the creation, configuration, and lifecycle management of Kubernetes clusters across multiple cloud providers and deployment types. The system provides a single CLI interface that abstracts cloud-specific operations while incorporating cost optimization and environmental sustainability features into the cluster provisioning process.
This page provides a high-level architectural overview of the ksctl codebase, introducing the major system components and their relationships. For detailed information about specific subsystems:
Sources: README.md15-31
Ksctl addresses three primary objectives:
Unified Multi-Cloud Management: Eliminates the need for cloud-specific CLIs (aws-cli, az, gcloud) by providing a single interface for provisioning Kubernetes infrastructure across AWS, Azure, and local environments.
Cost and Sustainability Optimization: Integrates regional cost analysis and carbon emission metrics into the cluster creation workflow, enabling informed decisions about infrastructure placement based on both financial and environmental impact.
Simplified Cluster Lifecycle: Automates complex tasks including infrastructure provisioning, Kubernetes distribution bootstrap (K3s, Kubeadm), CNI installation, and in-cluster controller deployment through a consistent API.
The system supports both self-managed clusters (where ksctl provisions VMs and bootstraps Kubernetes) and cloud-managed clusters (EKS, AKS, Kind), storing cluster state in pluggable backends (local filesystem, MongoDB, Kubernetes ConfigMaps).
Sources: README.md17-30 go.mod1-40
Architecture Overview: The ksctl system is organized into five primary layers. The CLI layer serves as the user-facing entry point. The Core package implements the KsctlClient which orchestrates operations through specialized controllers. The Provider Abstraction layer implements the Cloud interface for each supported cloud, enabling uniform operations across AWS, Azure, and local environments. The Bootstrap Layer handles Kubernetes distribution installation for self-managed clusters. State Persistence abstracts storage through the Storage interface, supporting multiple backends. External controllers (kcm, ka) extend cluster capabilities post-provisioning.
Sources: README.md32-44 pkg/consts/consts.go1-158
The pkg/core/ package provides KsctlClient, which serves as the main orchestration component. It instantiates specialized controllers based on the operation type:
| Controller | Type | Primary Responsibilities | Key Files |
|---|---|---|---|
CommonController | Query Operations | Cluster listing, context switching, cluster info retrieval | pkg/controllers/common.go |
ManagedClusterController | Managed Clusters | EKS, AKS, Kind cluster provisioning and deletion | pkg/controllers/managed.go |
SelfManagedController | Self-Managed Clusters | VM provisioning, Kubernetes bootstrap, scaling operations | pkg/controllers/selfmanaged.go |
MetadataController | Optimization | Region/instance listing, cost calculation, emission analysis | pkg/controllers/metadata.go |
AddonController | Add-ons | CNI installation, in-cluster controller deployment | pkg/controllers/addon.go |
Each controller implements operations defined in the base Controller interface and maintains references to the StorageDocument for state persistence.
Sources: README.md36-44
The pkg/types/provider.go file defines the Cloud interface, which abstracts cloud-specific operations. Each provider implementation resides in pkg/providers/{cloud}/:
Provider Interface Design: The Cloud interface standardizes operations across cloud providers. Each implementation handles SDK initialization, API authentication, and resource management specific to that cloud. The interface segregates managed cluster operations (NewManagedCluster) from self-managed operations (NewVM, NewNetworkConfiguration), enabling different controller types to invoke appropriate provider methods.
Sources: go.mod5-40 pkg/consts/consts.go99-106
State persistence follows a storage interface pattern defined in pkg/types/storage.go. The StorageDocument structure (in pkg/statefile/) serves as the canonical representation of cluster state:
State Architecture: Every cluster operation reads and writes to a StorageDocument, which encapsulates all infrastructure details, Kubernetes configuration, and addon state. The Storage interface abstracts persistence, enabling the same core logic to work with local files (development), MongoDB (team collaboration), or Kubernetes ConfigMaps (in-cluster operation). Storage selection is controlled via consts.KsctlStore enumeration.
Sources: pkg/consts/consts.go115-119 pkg/consts/consts.go134-148
Ksctl uses Go's context.Context for passing configuration and credentials through the call stack. The pkg/config/context.go file implements validation logic for context keys:
Context System: The system defines context keys in pkg/consts/consts.go using the KsctlContextKeyType enumeration. The IsContextPresent() function validates context values through pattern matching (for paths and module names), JSON unmarshaling (for credential structures), or type assertions. This approach enables safe retrieval of configuration throughout the codebase without global variables.
Sources: pkg/config/context.go26-85 pkg/config/context_test.go26-116 pkg/consts/consts.go134-148
Ksctl supports two fundamental cluster types, defined in the consts package:
| Constant | Value | Description | Controller |
|---|---|---|---|
consts.ClusterTypeMang | "managed" | Cloud-managed Kubernetes services (EKS, AKS, Kind) | ManagedClusterController |
consts.ClusterTypeSelfMang | "selfmanaged" | User-managed infrastructure with ksctl-bootstrapped Kubernetes | SelfManagedController |
The cluster type determines which controller handles operations and which provider methods are invoked. Managed clusters delegate control plane management to cloud providers, while self-managed clusters give ksctl full responsibility for VM provisioning, Kubernetes installation, and cluster configuration.
Within self-managed clusters, the Kubernetes distribution is further specified:
| Distribution Constant | Value | Bootstrap Implementation |
|---|---|---|
consts.K8sK3s | "k3s" | pkg/bootstrap/k3s/ |
consts.K8sKubeadm | "kubeadm" | pkg/bootstrap/kubeadm/ |
Sources: pkg/consts/consts.go129-132 pkg/consts/consts.go106-113
The following diagram illustrates a typical cluster creation flow, showing how components interact:
Creation Flow: This sequence demonstrates state-driven operations. The core client first attempts region optimization through the metadata controller. State transitions are explicitly managed (Creating -> Running) and persisted at each major step. Provider operations are cloud-agnostic through the interface. Bootstrap operations only occur for self-managed clusters. All infrastructure details are captured in the StorageDocument for subsequent operations (scaling, deletion).
Sources: README.md15-30
The ksctl architecture employs several critical abstractions:
Cloud interface (pkg/types/provider.go): Enables uniform cloud operations across AWS, Azure, and local providersStorage interface (pkg/types/storage.go): Abstracts state persistence across local, MongoDB, and Kubernetes backendsBootstrap interface (pkg/bootstrap/): Standardizes Kubernetes distribution installation for K3s and KubeadmController interface (pkg/controllers/controller.go): Defines lifecycle operations (create, delete, scale) implemented by specialized controllersStorageDocument (pkg/statefile/): Canonical state representation shared across all componentspkg/config/context.go): Type-safe configuration and credential passing via context.ContextThese abstractions enable the system to support multiple clouds, storage backends, and Kubernetes distributions through a unified codebase, with most business logic written once and specialized only at the interface implementation layer.
Sources: pkg/consts/consts.go1-158 pkg/config/context.go26-85
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.