Installation & Setup

Comprehensive guide for installing and configuring KubeZero in different environments.

System Requirements

Minimum Requirements

CPU: 2 cores
Memory: 4GB RAM
Storage: 10GB free space
OS: Linux, macOS, or Windows with WSL2

Recommended Requirements

CPU: 4+ cores
Memory: 8GB+ RAM
Storage: 20GB+ free space
Network: Stable internet connection for pulling images

Installation Methods

Method 1: Local Development (K3d)

Perfect for development, testing, and learning KubeZero.

Prerequisites

# macOS
brew install docker k3d kubectl helm

# Linux (Ubuntu/Debian)
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
wget -q -O - https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

# Windows (PowerShell as Administrator)
choco install docker-desktop k3d kubernetes-cli kubernetes-helm

Setup

# Clone repository
git clone https://github.com/kubezero/kubezero.git
cd kubezero

# Create cluster
k3d cluster create --config bootstrap/k3d-bootstrap-cluster.yaml

# Verify installation
kubectl get nodes
kubectl get pods -A

Method 2: Cloud Provider Setup

Deploy KubeZero on managed Kubernetes services.

AWS EKS

# Prerequisites
aws configure  # Configure AWS CLI
eksctl version  # Install eksctl if needed

# Create EKS cluster
eksctl create cluster \
  --name kubezero-management \
  --region us-west-2 \
  --nodegroup-name standard-workers \
  --node-type m5.large \
  --nodes 3 \
  --nodes-min 1 \
  --nodes-max 4 \
  --managed

# Apply KubeZero bootstrap
kubectl apply -k bootstrap/

Google GKE

# Prerequisites
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# Create GKE cluster
gcloud container clusters create kubezero-management \
  --zone us-central1-a \
  --num-nodes 3 \
  --machine-type n1-standard-2 \
  --enable-autoscaling \
  --min-nodes 1 \
  --max-nodes 5

# Get credentials
gcloud container clusters get-credentials kubezero-management --zone us-central1-a

# Apply KubeZero bootstrap
kubectl apply -k bootstrap/

Method 3: Production Setup

For production environments with high availability.

Multi-Node Cluster

# Use tools like kubeadm, kops, or managed services
# Ensure you have:
# - Multiple master nodes (3+ for HA)
# - Multiple worker nodes (3+ recommended)
# - Load balancer for API server
# - Persistent storage class
# - Network policies support

# Apply KubeZero with production configuration
kubectl apply -k packages/production/

Configuration Options

Basic Configuration

Edit bootstrap/k3d-bootstrap-cluster.yaml for local development:

apiVersion: k3d.io/v1alpha4
kind: Simple
metadata:
  name: kubezero-bootstrap
servers: 1
agents: 2
image: rancher/k3s:v1.28.2-k3s1
ports:
  - port: 80:80
    nodeFilters:
      - loadbalancer
  - port: 443:443
    nodeFilters:
      - loadbalancer
options:
  k3d:
    wait: true
    timeout: "300s"
  k3s:
    extraArgs:
      - arg: --disable=traefik
        nodeFilters:
          - server:*

Advanced Configuration

Environment Variables

# Set these before cluster creation
export KUBEZERO_DOMAIN="local.kubezero.io"
export KUBEZERO_CLOUD_PROVIDER="aws"  # aws, gcp, azure, local
export KUBEZERO_MONITORING_ENABLED="true"
export KUBEZERO_BACKUP_ENABLED="true"

Cluster Specifications

# config/cluster-spec.yaml
apiVersion: kubezero.io/v1alpha1
kind: ClusterSpec
metadata:
  name: kubezero-config
spec:
  cloudProvider: aws
  region: us-west-2
  networking:
    cni: cilium
    serviceCIDR: 10.43.0.0/16
    podCIDR: 10.42.0.0/16
  storage:
    defaultClass: gp3
    backupEnabled: true
  monitoring:
    enabled: true
    prometheus: true
    grafana: true
  security:
    policyEngine: opa-gatekeeper
    imageScanningEnabled: true

Post-Installation Setup

1. Verify Installation

# Check cluster health
kubectl get nodes
kubectl get pods -A
kubectl get crd | grep -E "(crossplane|argo)"

# Verify ArgoCD
kubectl get applications -n argocd
kubectl get pods -n argocd

2. Access ArgoCD

# Get admin password
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

# Access dashboard
# Local: http://gitops.local.kubezero.io
# Or port-forward: kubectl port-forward -n argocd svc/argocd-server 8080:80

3. Configure DNS (for local development)

Add to /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows):

127.0.0.1 gitops.local.kubezero.io
127.0.0.1 apps.local.kubezero.io

4. Initial Security Setup

# Change default ArgoCD password
kubectl -n argocd patch secret argocd-secret \
  -p '{"stringData": {"admin.password": "$2a$10$rRyBsGSHK6.uc8fntPwVKOLn9/j9S.BpFg1eqbhfqMJ0PnqgbVEDi"}}'

# Enable RBAC
kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    p, role:admin, applications, *, */*, allow
    p, role:admin, clusters, *, *, allow
    p, role:admin, repositories, *, *, allow
    g, admin, role:admin
EOF

Environment-Specific Configurations

Development Environment

# Lightweight setup
k3d cluster create --config bootstrap/k3d-bootstrap-cluster.yaml

# Enable development features
kubectl apply -k packages/development/

Staging Environment

# Production-like setup with monitoring
kubectl apply -k packages/staging/

Production Environment

# Full production setup
kubectl apply -k packages/production/

# Enable enterprise features
kubectl apply -k packages/enterprise/

Customization Options

1. Custom Modules

# Create custom module
mkdir -p modules/my-custom-module
cd modules/my-custom-module

# Add your Kubernetes manifests
# Reference in stacks/*/kustomization.yaml

2. Custom Stacks

# Create environment-specific stack
mkdir -p stacks/my-environment/manifests
cd stacks/my-environment/manifests

# Add kustomization.yaml referencing modules

3. Custom Packages

# Create package for specific use case
mkdir -p packages/my-package
cd packages/my-package

# Reference stacks and add package-level configuration

Troubleshooting Installation

Common Issues

1. Cluster Creation Fails

# Check Docker is running
docker ps

# Clean up and retry
k3d cluster delete kubezero-bootstrap
k3d cluster create --config bootstrap/k3d-bootstrap-cluster.yaml --verbose

2. ArgoCD Not Accessible

# Check ingress
kubectl get ingress -n argocd

# Check services
kubectl get svc -n argocd

# Port forward as fallback
kubectl port-forward -n argocd svc/argocd-server 8080:80

3. Pods Stuck in Pending

# Check node resources
kubectl describe nodes

# Check pod events
kubectl describe pod <pod-name> -n <namespace>

# Check storage classes
kubectl get storageclass

Logs and Diagnostics

# ArgoCD logs
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server

# Crossplane logs
kubectl logs -n crossplane-system -l app=crossplane

# System events
kubectl get events --sort-by=.metadata.creationTimestamp

Next Steps

After successful installation:

Need help? Check our troubleshooting guide or FAQ.

System Requirements​

Minimum Requirements​

Recommended Requirements​

Installation Methods​

Method 1: Local Development (K3d)​

Prerequisites​

Setup​

Method 2: Cloud Provider Setup​

AWS EKS​

Google GKE​

Method 3: Production Setup​

Multi-Node Cluster​

Configuration Options​

Basic Configuration​

Advanced Configuration​

Environment Variables​

Cluster Specifications​

Post-Installation Setup​

1. Verify Installation​

2. Access ArgoCD​

3. Configure DNS (for local development)​

4. Initial Security Setup​

Environment-Specific Configurations​

Development Environment​

Staging Environment​

Production Environment​

Customization Options​

1. Custom Modules​

2. Custom Stacks​

3. Custom Packages​

Troubleshooting Installation​

Common Issues​

1. Cluster Creation Fails​

2. ArgoCD Not Accessible​

3. Pods Stuck in Pending​

Logs and Diagnostics​

Next Steps​