A CLI and GUI tool to analyze Cluster API and Metal3 cluster components, check their conditions, build dependency trees, and provide clear advice on how to resolve any issues found.
- Graphical User Interface: Interactive GUI for visualizing cluster state and dependencies (NEW!)
- Comprehensive Component Discovery: Automatically discovers all Cluster API and Metal3 components in your cluster
- Condition Analysis: Analyzes all component conditions and identifies issues
- Dependency Tree Building: Builds hierarchical dependency relationships between components
- Intelligent Advisory System: Provides specific recommendations for resolving issues
- Multiple Output Formats: Supports human-readable reports, JSON, and YAML output
- Focused Health Diagnostics: Dedicated doctor mode for quick health checks
- Cluster API Core: Clusters, Machines, MachineSets, MachineDeployments
- Control Plane: KubeadmControlPlane, KubeadmConfig
- Metal3 Infrastructure: Metal3Cluster, Metal3Machine, BareMetalHost
go build -o capi-advisor .For the GUI, you'll need system dependencies. See GUI.md for detailed installation instructions.
Quick start for Linux (Ubuntu/Debian):
sudo apt-get install -y pkg-config libgl1-mesa-dev xorg-dev
go build -o capi-advisor .Launch the GUI for interactive visualization:
# Launch GUI for all clusters
./capi-advisor gui
# Launch GUI for specific namespace
./capi-advisor gui -n cluster-system
# Launch GUI for specific cluster
./capi-advisor gui -c my-clusterThe GUI provides three interactive tabs:
- Overview: Cluster health statistics, status breakdown, and component list
- Component Tree: Interactive dependency tree with detailed component information
- Issues & Recommendations: Categorized issues with resolution steps
For more details, see GUI.md.
Get a full analysis with recommendations for all components:
# Analyze all components across all namespaces
./capi-advisor analyze
# Analyze components in a specific namespace
./capi-advisor analyze -n cluster-system
# Analyze a specific CAPI cluster
./capi-advisor analyze -c my-cluster
# Show dependency tree along with analysis
./capi-advisor analyze --tree
# Get results in JSON format
./capi-advisor analyze -o jsonFocus on health issues and their solutions:
# Run health diagnostics
./capi-advisor doctor
# Check specific namespace
./capi-advisor doctor -n cluster-system
# Check specific CAPI cluster
./capi-advisor doctor -c my-clusterVisualize component relationships:
# Show component dependency tree
./capi-advisor tree
# Focus on specific namespace
./capi-advisor tree -n cluster-system
# Show tree for specific CAPI cluster
./capi-advisor tree -c my-cluster🏥 CLUSTER HEALTH REPORT
==================================================
Overall Health: âś… Healthy
đź“Š COMPONENT SUMMARY
Total Components: 12
Status Distribution:
âś… Healthy: 10
⚠️ Degraded: 2
❌ Failed: 0
🚨 ISSUES FOUND
------------------------------
1. 🟡 Machine InfrastructureReady is False
Component: Machine/worker-1
Cause: Metal3Machine is not ready
đź’ˇ Resolution: Check BareMetalHost status and provisioning
đź”— Check these dependencies:
⏳ Metal3Machine/worker-1-metal3
❌ BareMetalHost/worker-1-bmh
2. 🟡 BareMetalHost Available is False
Component: BareMetalHost/worker-1-bmh
Cause: Host is not available for provisioning
đź’ˇ Resolution: Check if host is powered on and BMC is accessible
🌳 COMPONENT DEPENDENCY TREE
============================
âś… Cluster/test-cluster (Healthy)
âś“ Ready: Cluster is ready
âś“ InfrastructureReady: Infrastructure is ready
âś… Metal3Cluster/test-cluster-metal3 (Healthy)
âś“ Ready: Metal3Cluster is ready
âś… KubeadmControlPlane/test-cluster-control-plane (Healthy)
âś“ Ready: Control plane is ready
âś… Machine/test-cluster-control-plane-abc123 (Healthy)
âś“ Ready: Machine is ready
âś… Metal3Machine/test-cluster-control-plane-abc123-metal3 (Healthy)
âś“ Ready: Metal3Machine is ready
âś… BareMetalHost/master-0 (Healthy)
âś“ Ready: Host is ready and provisioned
The tool is structured into several key packages:
pkg/client: Kubernetes client configuration and managementpkg/analyzer: Component discovery and condition analysispkg/tree: Dependency tree building and relationship mappingpkg/advisor: Knowledge base and issue resolution recommendationscmd: CLI commands and user interface
The tool uses your existing Kubernetes configuration:
- In-cluster configuration (when running as a pod)
~/.kube/configfile$KUBECONFIGenvironment variable
This tool is designed to be extensible. To add support for new component types:
- Add the component type to
SupportedGVKsinpkg/analyzer/discovery.go - Add relationship logic in
pkg/tree/builder.go - Add condition knowledge to the advisor in
pkg/advisor/advisor.go
from Git Repo
example:
Details
$ clusterctl describe cluster my-cluster-1 -n metal3-my-infra --show-conditions all
NAME READY SEVERITY REASON SINCE MESSAGE
Cluster/my-cluster-1 True 31s
│ ├─ControlPlaneInitialized True 15m
│ ├─ControlPlaneReady True 31s
│ └─InfrastructureReady True 31m
├─ClusterInfrastructure - Metal3Cluster/my-cluster-1 True 31m
│ └─BaremetalInfrastructureReady True 31m
├─ControlPlane - KubeadmControlPlane/my-cluster-1 True 31s
│ │ ├─Available True 15m
│ │ ├─CertificatesAvailable True 31m
│ │ ├─ControlPlaneComponentsHealthy True 66s
│ │ ├─EtcdClusterHealthy True 72s
│ │ ├─MachinesCreated True 65s
│ │ ├─MachinesReady True 31s
│ │ └─Resized True 64s
│ └─3 Machines... True 15m See my-cluster-1-ftxxh, my-cluster-1-tdh8j, ...
└─Workers
├─MachineDeployment/my-cluster-1-default-v3 False Warning WaitingForAvailableMachines 31m Minimum availability requires 2 replicas, current 0 available
│ │ ├─Available False Warning WaitingForAvailableMachines 31m Minimum availability requires 2 replicas, current 0 available
│ │ └─MachineSetReady False Error AssociateBMHFailed @ Machine/my-cluster-1-default-v3-b8qqb-67w5p 41s 0 of 2 completed
│ ├─Machine/my-cluster-1-default-v3-b8qqb-67w5p False Error AssociateBMHFailed 15m 1 of 2 completed
│ │ ├─BootstrapReady True 15m
│ │ ├─InfrastructureReady False Error AssociateBMHFailed 15m No available host found. Requeuing.. Object will be requeued after 30s
│ │ └─NodeHealthy False Info WaitingForNodeRef 31m
│ └─Machine/my-cluster-1-default-v3-b8qqb-x79q4 False Error SettingProviderIDOnNodeFailed 41s 1 of 2 completed
│ ├─BootstrapReady True 15m
│ ├─InfrastructureReady False Error SettingProviderIDOnNodeFailed 41s Some target nodes do not have spec.providerID field set yet, requeuing. Object will be requeued afte ...
│ └─NodeHealthy False Info WaitingForNodeRef 31m
└─MachineDeployment/my-cluster-1-sriov False Warning WaitingForAvailableMachines 31m Minimum availability requires 2 replicas, current 0 available
│ ├─Available False Warning WaitingForAvailableMachines 31m Minimum availability requires 2 replicas, current 0 available
│ └─MachineSetReady False Warning ScalingUp 13s Scaling up MachineSet to 2 replicas (actual 0)
└─2 Machines... from Git Repo
example:
Details
$ kubectl tree -n metal3-my-infra cluster my-cluster-1
NAMESPACE NAME READY REASON AGE
metal3-my-infra Cluster/my-cluster-1 True 34m
metal3-my-infra ├─KubeadmConfigTemplate/my-cluster-1-default-v3-2 - 34m
metal3-my-infra ├─KubeadmConfigTemplate/my-cluster-1-sriov-7 - 34m
metal3-my-infra ├─KubeadmControlPlane/my-cluster-1 True 34m
metal3-my-infra │ ├─Machine/my-cluster-1-ftxxh
...This project is licensed under the MIT License.