Skip to main content

FAQ - Frequently Asked Questions

Common questions and answers about KubeZero.

General Questions​

What is KubeZero?​

KubeZero is a production-ready, GitOps-native Kubernetes platform engineering framework designed for small to mid-size teams. It provides a complete platform solution with minimal configuration, using only Kubernetes-native tools (no Terraform required).

How is KubeZero different from other Kubernetes platforms?​

  • Kubernetes-native: Uses only Kubernetes tools, no external dependencies like Terraform
  • GitOps-first: Everything managed through Git repositories
  • Modular design: Reusable components that can be mixed and matched
  • Small team focused: Designed for teams that need enterprise features without enterprise complexity
  • Zero-friction: Works out of the box with minimal configuration

Who should use KubeZero?​

  • Small to mid-size development teams (1-50 people)
  • Teams adopting trunk-based development or GitFlow
  • Organizations wanting to reduce cloud infrastructure costs
  • Platform engineers who want to focus on value delivery rather than tool integration
  • Startups and growing companies needing production-ready Kubernetes

Getting Started​

What are the prerequisites for KubeZero?​

Minimum requirements:

  • Docker installed and running
  • 2 CPU cores, 4GB RAM, 10GB storage
  • Basic familiarity with Kubernetes concepts

For production:

  • Kubernetes cluster (EKS, GKE, AKS, or self-managed)
  • 4+ CPU cores, 8GB+ RAM, 20GB+ storage
  • Domain name for ingress (optional but recommended)

How long does it take to set up KubeZero?​

  • Local development: 5-10 minutes
  • Cloud deployment: 30-60 minutes (depending on cloud provider setup)
  • Production-ready: 2-4 hours (including proper configuration and security setup)

Can I try KubeZero without affecting my existing infrastructure?​

Yes! Start with the local K3d setup which runs entirely in Docker containers on your machine. This doesn't affect any existing infrastructure and can be easily removed.

# Quick local setup
git clone https://github.com/kubezero/kubezero.git
cd kubezero
k3d cluster create --config bootstrap/k3d-bootstrap-cluster.yaml

Architecture and Design​

Why doesn't KubeZero use Terraform?​

KubeZero follows the philosophy that "Kubernetes is the platform" and uses Kubernetes-native tools for everything:

  • Crossplane for infrastructure management instead of Terraform
  • ArgoCD for GitOps instead of CI/CD-driven deployments
  • Kubernetes CRDs for configuration instead of HCL

This approach provides:

  • Consistent tooling and APIs
  • Better integration with Kubernetes RBAC and policies
  • Simplified operational model
  • Reduced tool sprawl

How does KubeZero handle secrets management?​

KubeZero uses the External Secrets Operator (ESO) to integrate with external secret management systems:

  • AWS Secrets Manager
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault
  • Generic HTTP APIs

Secrets are never stored in Git repositories and are automatically synced from external systems.

What deployment patterns does KubeZero support?​

  1. Single Cluster (Virtual): All environments as virtual clusters
  2. Single Cluster (Mixed): Production native + virtual non-production
  3. Two Clusters: Separate production and non-production clusters
  4. Multi-Cluster: Management + multiple environment clusters

You can start with one pattern and evolve to others as your needs grow.

Operations and Management​

How do I deploy applications with KubeZero?​

KubeZero follows GitOps principles:

  1. Add your application manifests to a Git repository
  2. Create an ArgoCD Application that points to your manifests
  3. Commit and push - ArgoCD automatically deploys changes
  4. Monitor through the ArgoCD UI

See our Deploy Your First Application guide for detailed steps.

How do I manage different environments (dev, staging, prod)?​

KubeZero supports multiple approaches:

Option 1: Virtual Clusters

# Different vClusters for each environment
vcluster-dev, vcluster-staging, vcluster-prod

Option 2: Namespaces with Kustomize Overlays

apps/
├── base/
└── overlays/
    ├── dev/
    ├── staging/
    └── prod/

Option 3: Separate Clusters

clusters/
├── management/
├── production/
└── non-production/

How do I update KubeZero components?​

KubeZero components are updated through Git like any other application:

  1. Update module versions in your Git repository
  2. Commit and push changes
  3. ArgoCD automatically syncs the updates
  4. Monitor the update process through ArgoCD UI
# Update a module version
helmCharts:
  - name: argo-cd
    version: 5.46.8  # Update this version
    repo: https://argoproj.github.io/argo-helm

How do I backup and restore KubeZero?​

Backup strategy:

  • Git repositories: Your single source of truth (already versioned)
  • ArgoCD configuration: Managed through Git
  • Application data: Use Velero or cloud-native backup solutions
  • Secrets: Stored in external secret management systems

Disaster recovery:

  1. Recreate cluster using KubeZero bootstrap
  2. Point ArgoCD to your Git repositories
  3. Restore application data from backups
  4. Verify all applications are running

Troubleshooting​

ArgoCD is not accessible after installation​

Common causes and solutions:

  1. DNS resolution issues:

    # Add to /etc/hosts
    echo "127.0.0.1 gitops.local.kubezero.io" >> /etc/hosts

  2. Ingress not ready:

    # Check ingress controller status
    kubectl get pods -n ingress-nginx

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

  3. Certificate issues:

    # Check certificate status
    kubectl get certificates -n argocd
    kubectl describe certificate argocd-tls -n argocd

Applications are stuck in "Progressing" state​

Debugging steps:

  1. Check application health:

    kubectl get applications -n argocd
    kubectl describe application <app-name> -n argocd

  2. Check resource status:

    kubectl get pods -n <app-namespace>
    kubectl describe pod <pod-name> -n <app-namespace>

  3. Check ArgoCD logs:

    kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller

Crossplane providers are not working​

Common issues:

  1. Missing credentials:

    # Check provider configuration
    kubectl get providers
    kubectl describe provider <provider-name>

    # Check provider secrets
    kubectl get secrets -n crossplane-system

  2. RBAC issues:

    # Check service account permissions
    kubectl describe clusterrole crossplane-provider-<provider>

  3. Network connectivity:

    # Check provider pods logs
    kubectl logs -n crossplane-system -l app=<provider-name>

Virtual clusters are not starting​

Debugging vCluster issues:

  1. Check vCluster pods:

    kubectl get pods -n vcluster-<name>
    kubectl logs -n vcluster-<name> -l app=vcluster

  2. Check storage:

    kubectl get pvc -n vcluster-<name>
    kubectl describe pvc -n vcluster-<name>

  3. Connection issues:

    # Test vCluster connectivity
    vcluster connect <name> -n vcluster-<name> --server-url https://localhost:8443

Advanced Topics​

Can I use KubeZero with existing Kubernetes clusters?​

Yes! KubeZero can be installed on any existing Kubernetes cluster:

  1. Apply the bootstrap manifests to your cluster
  2. Configure ArgoCD to point to your Git repositories
  3. Gradually migrate your existing applications to GitOps

How do I integrate KubeZero with my CI/CD pipeline?​

KubeZero works with any CI/CD system:

Option 1: Image-only updates

  • CI builds and pushes images
  • ArgoCD watches for image tag changes
  • Automatic deployment on new images

Option 2: Manifest updates

  • CI updates Kubernetes manifests in Git
  • ArgoCD detects Git changes
  • Automatic deployment on manifest changes

Option 3: Webhook integration

  • CI triggers ArgoCD sync via webhook
  • Immediate deployment after successful build

Can I run KubeZero in air-gapped environments?​

Yes, with some preparation:

  1. Mirror required images to your private registry
  2. Host Helm charts in your private chart repository
  3. Clone Git repositories to your internal Git server
  4. Update configurations to point to internal resources

How do I monitor KubeZero platform health?​

KubeZero can be extended with monitoring:

# Add monitoring stack
resources:
  - ../../../modules/prometheus
  - ../../../modules/grafana
  - ../../../modules/alertmanager

Key metrics to monitor:

  • ArgoCD sync status and health
  • Crossplane provider health
  • Certificate expiration
  • Resource utilization
  • Application health checks

How do I scale KubeZero for larger teams?​

Scaling strategies:

  1. Multi-cluster setup: Separate clusters per team/environment
  2. RBAC configuration: Fine-grained access control
  3. GitOps repository structure: Separate repos per team/application
  4. Virtual clusters: Isolated environments for teams
  5. Resource quotas: Prevent resource contention

Security​

Is KubeZero secure by default?​

KubeZero follows security best practices:

  • RBAC: Role-based access control for all components
  • TLS everywhere: Automatic certificate management
  • Secret management: Integration with external secret stores
  • Network policies: Optional network isolation
  • Security contexts: Non-root containers by default

How do I implement security policies?​

KubeZero can be extended with policy engines:

# Add policy enforcement
resources:
  - ../../../modules/opa-gatekeeper
  - ../../../modules/falco
  - ../../../modules/network-policies

How do I audit KubeZero activities?​

Audit trail sources:

  • Git commits: All changes tracked in version control
  • ArgoCD events: Deployment history and status
  • Kubernetes audit logs: API server access logs
  • Application logs: Centralized logging with Fluentd/Fluent Bit

Cost and Licensing​

How much does KubeZero cost?​

KubeZero itself is completely free and open source. You only pay for:

  • Cloud infrastructure (compute, storage, networking)
  • Managed services (if using EKS, GKE, AKS)
  • Third-party tools (if using commercial secret management, monitoring, etc.)

What's the licensing model?​

KubeZero is released under the Apache 2.0 License, which means:

  • ✅ Commercial use allowed
  • ✅ Modification allowed
  • ✅ Distribution allowed
  • ✅ Private use allowed
  • ✅ Patent use allowed

How does KubeZero help reduce costs?​

  • Virtual clusters: Multiple environments on shared infrastructure
  • Efficient resource utilization: Right-sized deployments
  • Automated scaling: HPA and VPA for cost optimization
  • Cloud-agnostic: Avoid vendor lock-in
  • Reduced operational overhead: Less time managing tools

Support and Community​

Where can I get help?​

  • Documentation: Comprehensive guides and references
  • GitHub Issues: Bug reports and feature requests
  • Community Forums: General discussions and Q&A
  • Discord/Slack: Real-time community support

How do I contribute to KubeZero?​

  1. Star the repository on GitHub
  2. Report bugs or request features via GitHub Issues
  3. Submit pull requests for improvements
  4. Share your experience in the community
  5. Write blog posts or tutorials

Is commercial support available?​

While KubeZero is open source, the maintainers may offer:

  • Consulting services for implementation
  • Training and workshops for teams
  • Custom development for specific needs
  • Priority support for critical issues

Contact the maintainers through GitHub for commercial inquiries.

Migration and Compatibility​

Can I migrate from other Kubernetes platforms?​

Yes! KubeZero is designed to coexist with and gradually replace other solutions:

From Terraform + Kubernetes:

  1. Migrate infrastructure management to Crossplane
  2. Set up GitOps with ArgoCD
  3. Gradually move applications to KubeZero patterns

From other GitOps tools:

  1. Export existing application definitions
  2. Adapt to KubeZero module structure
  3. Configure ArgoCD to manage applications

From imperative deployments:

  1. Document current state as Kubernetes manifests
  2. Organize into KubeZero modules and stacks
  3. Set up GitOps workflow

What Kubernetes versions are supported?​

KubeZero supports:

  • Minimum: Kubernetes 1.20+
  • Recommended: Kubernetes 1.24+
  • Tested: Latest 3 minor versions

Cloud provider managed services (EKS, GKE, AKS) are fully supported.

Still have questions?​

If you didn't find your question here:

  1. Search the documentation for related topics
  2. Check GitHub Issues for similar questions
  3. Join our community for real-time help
  4. Create a new issue if you found a bug or need a feature

We're here to help you succeed with KubeZero! 🚀