Skip to main content

Quick Start

Get KubeZero up and running in your local environment in just a few minutes.

Prerequisites​

Before you begin, ensure you have the following tools installed:

  • Docker - For running K3d clusters
  • K3d - Lightweight Kubernetes distribution
  • kubectl - Kubernetes command-line tool
  • Git - Version control system

Installation Commands​

# Install K3d (macOS)
brew install k3d

# Install K3d (Linux)
wget -q -O - https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

# Install kubectl (macOS)
brew install kubectl

# Install kubectl (Linux)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

Step 1: Clone the Repository​

git clone https://github.com/kubezero/kubezero.git
cd kubezero

Step 2: Bootstrap Your Local Cluster​

KubeZero includes a bootstrap configuration that sets up a local K3d cluster with all necessary components:

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

This command will:

  • Create a local Kubernetes cluster using K3d
  • Install ArgoCD for GitOps management
  • Install Crossplane for infrastructure management
  • Configure ingress and networking

Step 3: Wait for Components to Initialize​

The bootstrap process takes a few minutes. You can monitor the progress:

# Watch ArgoCD pods come online
kubectl get pods -n argocd -w

# Check all system components
kubectl get pods -A

Step 4: Access ArgoCD Dashboard​

Once the cluster is ready, access the ArgoCD dashboard:

# ArgoCD will be available at:
open http://gitops.local.kubezero.io

Default Credentials​

  • Username: admin
  • Password: Get the password with: 
    kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

Step 5: Explore Your Platform​

🎉 Congratulations! You now have a fully functional KubeZero platform running locally.

What's Available​

  • ArgoCD: GitOps continuous delivery at http://gitops.local.kubezero.io
  • Crossplane: Infrastructure management (check with kubectl get compositeresourcedefinitions)
  • Monitoring: Observability stack (if enabled in your configuration)

Next Steps​

  1. Deploy Your First Application - Learn how to deploy applications using GitOps
  2. Understand the Architecture - Deep dive into how KubeZero works
  3. Explore Deployment Patterns - Choose the right pattern for your use case

Troubleshooting​

Cluster Creation Issues​

If cluster creation fails:

# Delete the cluster and try again
k3d cluster delete kubezero-bootstrap

# Recreate with verbose output
k3d cluster create --config bootstrap/k3d-bootstrap-cluster.yaml --verbose

DNS Resolution Issues​

If you can't access gitops.local.kubezero.io:

# Check if ingress is running
kubectl get ingress -A

# Port forward as alternative
kubectl port-forward -n argocd svc/argocd-server 8080:80
# Then access: http://localhost:8080

Need Help?​

Ready to dive deeper? Continue with deploying your first application!