Skip to main content

KubeZero Architecture Structure

KubeZero follows a modular architecture pattern that separates concerns between different layers of the Kubernetes platform management stack.

Core Architecture​

The KubeZero architecture is built around three main components:

1. Stacks​

Pre-configured collections of modules that provide complete solutions for specific use cases. Stacks define the high-level infrastructure patterns.

2. Modules​

Individual Kubernetes components that can be combined to create custom solutions. Each module is responsible for a specific piece of functionality.

3. Packages​

The underlying infrastructure configurations that define how Kubernetes clusters are provisioned and managed across different cloud providers.

Directory Structure​

kubezero@terminal:~$ tree kubezero/ -a -I '.git|node_modules|*.log|.DS_Store' --dirsfirst
kubezero/
├── 📦 stacks/                    # Complete solution templates
│   ├── eks-cluster/              # AWS EKS cluster stack
│   │   ├── kustomization.yaml
│   │   ├── values.yaml
│   │   └── README.md
│   ├── gke-cluster/              # Google GKE cluster stack
│   │   ├── kustomization.yaml
│   │   ├── values.yaml
│   │   └── README.md
│   ├── k8s-essentials/           # Essential Kubernetes components
│   │   ├── kustomization.yaml
│   │   └── values.yaml
│   └── virtual-cluster/          # Virtual cluster configurations
│       ├── kustomization.yaml
│       └── values.yaml
│
├── 🧩 modules/                   # Individual components
│   ├── argo-cd/                  # GitOps continuous deployment
│   │   ├── Chart.yaml
│   │   ├── values.yaml
│   │   └── templates/
│   ├── cert-manager/             # Certificate management
│   │   ├── Chart.yaml
│   │   └── values.yaml
│   ├── external-dns/             # DNS automation
│   ├── external-secrets/         # Secret management
│   ├── ingress-nginx/            # Ingress controller
│   ├── crossplane/               # Infrastructure as code
│   │   ├── compositions/
│   │   └── providers/
│   ├── aws/                      # AWS-specific modules
│   │   ├── eks/
│   │   ├── vpc/
│   │   └── iam/
│   ├── gcp/                      # GCP-specific modules
│   │   ├── gke/
│   │   ├── network/
│   │   └── iam/
│   └── vcluster/                 # Virtual cluster module
│       ├── Chart.yaml
│       └── values.yaml
│
├── 📋 packages/                  # Infrastructure packages
│   ├── aws-management/           # AWS management cluster
│   │   ├── crossplane/
│   │   │   ├── compositions/
│   │   │   └── providers/
│   │   └── kustomization.yaml
│   ├── aws-worker/               # AWS worker nodes
│   │   ├── nodepool.yaml
│   │   └── kustomization.yaml
│   ├── gcp-management/           # GCP management cluster
│   │   ├── crossplane/
│   │   └── kustomization.yaml
│   ├── gcp-worker/               # GCP worker nodes
│   ├── virtual-management/       # Virtual management plane
│   └── virtual-worker/           # Virtual worker nodes
│
├── ⚙️  controller/               # GitOps controllers
│   ├── argo-cd/                  # ArgoCD application configs
│   │   ├── application.yaml
│   │   └── kustomization.yaml
│   ├── crossplane/               # Crossplane compositions
│   │   ├── application.yaml
│   │   └── kustomization.yaml
│   ├── external-secrets/         # External secrets operators
│   │   ├── application.yaml
│   │   └── secretstore.yaml
│   ├── gitops/                   # GitOps workflow configs
│   │   ├── repository.yaml
│   │   └── sync-policy.yaml
│   └── namespace/                # Namespace configurations
│       ├── namespaces.yaml
│       └── rbac.yaml
│
├── 🗃️  registry/                 # Component registry
│   └── management/               # Management cluster registry
│       ├── catalog.yaml
│       └── metadata/
│
├── 🚀 bootstrap/                 # Bootstrap configurations
│   ├── k3d-bootstrap-cluster.yaml
│   ├── kubezero-bootstrap-manifests.yaml
│   ├── kustomization.yaml
│   └── README.md
│
├── 📚 docs/                      # Documentation
│   ├── README.md
│   ├── getting-started/
│   └── architecture/
│
├── 🔧 scripts/                   # Utility scripts
│   ├── install.sh
│   ├── validate.sh
│   └── cleanup.sh
│
├── ⚡ .github/                   # CI/CD workflows
│   └── workflows/
│       ├── test.yml
│       └── release.yml
│
├── 📄 LICENSE                    # License file
├── 📄 README.md                  # Project documentation
├── 📄 CHANGELOG.md               # Version history
└── 📄 .gitignore                # Git ignore rules

42 directories, 89 files

Component Relationships​

The KubeZero architecture follows a hierarchical composition model:

  • Stacks compose multiple Modules to create complete solutions
  • Modules leverage Packages for infrastructure provisioning
  • Packages define the underlying cloud infrastructure configurations
  • Controller manages the GitOps workflow across all components
  • Registry provides discoverability and metadata for modules

Architecture Flow​

  1. Define: Create or select a stack that matches your requirements
  2. Compose: Stacks automatically include the necessary modules
  3. Provision: Modules use packages to provision infrastructure
  4. Deploy: Controller applies configurations via GitOps
  5. Manage: Monitor and update through the GitOps workflow

Design Principles​

  • Modularity: Each component has a single responsibility and well-defined interfaces
  • Composability: Components can be combined in different ways to create custom solutions
  • Reusability: Common patterns are abstracted into reusable modules across environments
  • GitOps: All configuration is managed through Git workflows with version control
  • Cloud Agnostic: Support for multiple cloud providers with consistent interfaces
  • Security First: Built-in security best practices and policy enforcement

Stack Examples​

EKS Cluster Stack​

stacks/eks-cluster/values.yaml
# Complete AWS EKS cluster with essential components
modules:
  - aws/vpc
  - aws/eks
  - cert-manager
  - external-dns
  - ingress-nginx
  - argo-cd

GKE Cluster Stack​

stacks/gke-cluster/values.yaml
# Complete Google GKE cluster with essential components
modules:
  - gcp/network
  - gcp/gke
  - cert-manager
  - external-dns
  - ingress-nginx
  - argo-cd

Next Steps​