Add Generic CRD Analyzer for Custom Resources

[Copilot]

📑 Description

Enables K8sGPT to analyze custom resources from any installed CRD without code changes. Discovers CRDs via apiextensions API and applies configurable health checks.

Implementation

Core Analyzer (pkg/analyzer/crd.go, 330 lines)

• Discovers CRDs using k8s.io/apiextensions-apiserver
• Analyzes resources via dynamic client (namespace and cluster-scoped)
• Generic health detection:
  • status.conditions → flags Ready≠True, Failed=True
  • status.phase → detects Failed/Error
  • status.health.status → ArgoCD pattern
  • status.state → state-based failures
  • Stuck deletions → deletionTimestamp + finalizers
• Per-CRD custom checks via YAML config

Configuration (pkg/common/types.go)

type CRDAnalyzerConfig struct {
    Enabled bool
    Include []CRDIncludeConfig  // Custom checks per CRD
    Exclude []CRDExcludeConfig  // Skip noisy CRDs
}

type CRDIncludeConfig struct {
    Name            string              // e.g., "certificates.cert-manager.io"
    StatusPath      string              // e.g., ".status.health.status"
    ReadyCondition  *CRDReadyCondition  // Expected condition
    ExpectedValue   string              // Expected value at path
}

Usage

# ~/.config/k8sgpt/k8sgpt.yaml
crd_analyzer:
  enabled: true
  include:
    - name: certificates.cert-manager.io
      readyCondition:
        type: "Ready"
        expectedStatus: "True"
    - name: applications.argoproj.io
      statusPath: ".status.health.status"
      expectedValue: "Healthy"
  exclude:
    - name: kafkatopics.kafka.strimzi.io

k8sgpt filters add CustomResource
k8sgpt analyze --explain --filter=CustomResource

Testing

14 unit tests covering:

• Generic health checks (conditions, phase, health status, state)
• Custom configuration (readyCondition, expectedValue, statusPath)
• Include/exclude logic
• Error handling and edge cases

Documentation

• docs/CRD_ANALYZER.md: Configuration reference, use cases (cert-manager, ArgoCD, Kafka, Prometheus), troubleshooting
• examples/crd_analyzer_config.yaml: Ready-to-use template
• README.md: Added CustomResource to analyzer list

✅ Checks

• My pull request adheres to the code style of this project
• My code requires changes to the documentation
• I have updated the documentation as required
• All the tests have passed

ℹ Additional Information

Benefits:

• Works with any CRD (operators, custom controllers)
• Zero code changes for new CRD types
• Production-ready error handling
• Performance-conscious (configurable exclusions)

No breaking changes. Analyzer is opt-in via filter.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: Add Generic CRD Analyzer Support for Custom Resources</issue_title>
<issue_description>### Checklist

• I've searched for similar issues and couldn't find anything matching
• I've discussed this feature request in the K8sGPT Slack and got positive feedback

Is this feature request related to a problem?

Yes

Problem Description

K8sGPT currently supports:

• Built-in analyzers for core Kubernetes resources (e.g., Pod, Service, Deployment, Node)
• A few optional analyzers, including:
  • HorizontalPodAutoscaler (HPA)
  • PodDisruptionBudget (PDB)
  • NetworkPolicy
  • GatewayClass / Gateway / HTTPRoute
  • Storage
  • Security
  • Logs

However, there is no analyzer for arbitrary Custom Resource Definitions (CRDs) and their associated custom resources — a gap that limits observability and AI diagnostics for modern Kubernetes clusters relying heavily on CRDs (e.g., cert-manager, ArgoCD, Kafka, PrometheusOperator, etc.).

Solution Description

Introduce a generic CRD analyzer that:

• Uses the Kubernetes discovery API to list all installed CRDs.
• Reads each CRD definition (apiextensions.k8s.io/v1) and inspects its OpenAPI v3 schema under .spec.versions[].schema.openAPIV3Schema.
• Dynamically determines which diagnostic fields exist, such as:
  • .status.conditions
  • .status.phase
  • .status.health.status
  • .metadata.deletionTimestamp + .metadata.finalizers
• Applies appropriate health checks based on what's available per CRD.
• Surfaces unhealthy or anomalous states in K8sGPT analysis.

🧩 Additionally, make the analyzer configurable via YAML/JSON, like:

crdAnalyzer:
  enabled: true
  include:
    - name: certificates.cert-manager.io
      statusPath: ".status.conditions"
      readyCondition:
        type: "Ready"
        expectedStatus: "True"
    - name: applications.argoproj.io
      statusPath: ".status.health.status"
      expectedValue: "Healthy"
  exclude:
    - name: kafkatopics.kafka.strimzi.io

Benefits

• Expanded Diagnostic Coverage
  Enables K8sGPT to analyze custom workloads built on CRDs (e.g., ArgoCD, cert-manager, Kafka) that are otherwise invisible to default analyzers.

• Configurable and Extensible
  Users can define how health should be checked for each CRD via YAML/JSON — no need to write Go code for every custom resource type.

• Schema-Aware Logic
  Avoids brittle assumptions by reading and interpreting each CRD’s OpenAPI schema to determine if fields like .status.conditions or .status.health.status exist.

• Foundation for Future Per-CRD Enhancements
  Creates a pluggable framework that can be extended to support more specific behaviors later (e.g., ArgoCD sync failures, cert-manager renewal issues).

• Works Out-of-the-Box for Common Patterns
  Supports common Kubernetes conventions (e.g., .status.conditions, .phase, .state) with safe fallbacks.

• Faster Insights Without Waiting for Maintainer Support
  Users gain immediate visibility into their CRDs without waiting for built-in analyzers to be developed or released.

• Easier Collaboration with Users
  Since CRD behavior can be customized via config, users can share setups, iterate quickly, and tune without needing to understand the codebase.

• Supports Operator and GitOps-Heavy Workloads
  Especially valuable for clusters using Flux, ArgoCD, Prometheus, Kafka, and other CRD-heavy platforms.

Potential Drawbacks

• Inconsistent CRD Patterns
  Not all CRDs follow standard conventions like .status.conditions, which can lead to diagnostic gaps. However, this can be addressed through user-supplied config specifying expected status paths and health fields.

• Risk of False Positives or Negatives
  Generic checks may not align with CRD-specific logic, but the proposed config layer allows users to define expected conditions or values to minimize noise.

• Performance Overhead in Large Clusters
  CRD enumeration and analysis may increase runtime in clusters with many custom resources. Users can mitigate this by excluding CRDs via config.

Additional Information

I'm interested in contributing this analyzer and can help with:

• Implementing the CRD discovery and schema-parsing logic.
• Designing and wiring up the YAML/JSON-based configuration loader.
• Creating test cases using mock CRDs and sample configurations.
• Following existing analyzer patterns within pkg/analyzer.

If there's a preferred abstraction, interface, or naming convention I should align with, please let me know.

Also, I wasn’t able to join the K8sGPT Slack workspace — the invite link in the README/docs appears to be expired. Is there an updated link or alternate way to connect with the community or maintainers? Sorry that I have to click both the check boxes to be able to submit...

• Fixes [Feature]: Add Generic CRD Analyzer Support for Custom Resources #1528

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.