Skip to content

Installation Issues📜

This guide helps you diagnose and resolve issues during Big Bang installation. Installation problems typically involve Flux deployment failures, configuration errors, or infrastructure prerequisites.

Quick Installation Diagnostics📜

1. Check Installation Status📜

Verify the overall installation progress:

# Check Big Bang HelmRelease status
kubectl get helmrelease bigbang -n bigbang

# Check all package installations
kubectl get helmreleases -A

# Check Flux system health
kubectl get pods -n flux-system

2. Common Installation Failures📜

Flux Controller Issues: 

# Check Flux controllers are running
kubectl get pods -n flux-system

# Check controller logs for errors
kubectl logs -n flux-system deployment/helm-controller
kubectl logs -n flux-system deployment/source-controller

Git Repository Access: 

# Check GitRepository status
kubectl get gitrepository -n flux-system
kubectl describe gitrepository <repo-name> -n flux-system

# Check for authentication or network issues
kubectl get events -n flux-system --sort-by='.lastTimestamp'

Installation-Specific Issues📜

1. Schema Validation Errors📜

Check for configuration problems:

# Look for schema validation failures
kubectl get helmrelease bigbang -n bigbang -o yaml | grep -A 10 "conditions:"

# Common issues:
# - Invalid Big Bang values
# - Missing required configuration
# - Type mismatches in values.yaml

2. Resource Prerequisites📜

Verify cluster meets requirements:

# Check node resources
kubectl get nodes
kubectl describe nodes

# Check storage classes
kubectl get storageclass

# Verify cluster networking
kubectl get pods -n kube-system

3. Package Dependencies📜

Some packages require specific prerequisites:

# Check for dependency issues in events
kubectl get events --all-namespaces | grep -i "failed\|error"

# Verify prerequisite packages are installed first
kubectl get helmreleases -A | grep -E "cert-manager|istio"

Troubleshooting by Component📜

For detailed troubleshooting of specific issues:

Quick Reference Commands📜

# Check overall Big Bang status
kubectl describe helmrelease bigbang -n bigbang

# Force reconciliation if stuck
flux reconcile helmrelease bigbang -n bigbang

# Check for drift from desired state
flux diff helmrelease bigbang -n bigbang

# Review installation events
kubectl get events -n bigbang --sort-by='.lastTimestamp'

Recovery Steps📜

1. Reset Installation📜

If installation is completely broken:

# DANGER: This will delete your Big Bang installation! Ensure you have backups.
# Delete and recreate Big Bang HelmRelease
kubectl delete helmrelease bigbang -n bigbang
# Flux will recreate from Git source

# Force source reconciliation
flux reconcile source git <source-name> -n flux-system

2. Partial Installation Recovery📜

For partially failed installations:

# Identify failed packages
kubectl get helmreleases -A | grep -v "True.*True"

# Force reconciliation of specific packages
flux reconcile helmrelease <package-name> -n bigbang

Common Installation Patterns📜

1. Prerequisites Not Met📜

Ensure the following before installation: - Kubernetes cluster version compatibility - Sufficient node resources - Required storage classes - Network connectivity to registries

2. Configuration Issues📜

Validate your values before installation: - Check Big Bang values syntax - Verify package-specific configurations - Test with minimal configuration first

3. Infrastructure Dependencies📜

Some environments require additional setup: - Load balancer provisioning - DNS configuration - Certificate management - External secret management

Next Steps📜

Once basic installation issues are resolved:

  1. Review Monitoring to set up observability
  2. Configure Backup & Restore procedures
  3. Plan Upgrade strategies

For persistent installation issues, gather logs and events as described in the Package Troubleshooting guide and engage with the Big Bang community.