/kubeeye

name: kubeeye
description: Use when deploying KubeEye for cluster inspection, creating InspectRule/InspectPlan resources, or retrieving inspection results. Covers InstallPlan-based deployment, OPA/PromQL/FileChange/Sysctl/Systemd/NodeInfo/FileFilter/ServiceConnect/CustomCommand rule types, and report retrieval. Always consult this skill when the user mentions KubeEye, cluster inspection, InspectRule, InspectPlan, or inspection reports.
compatibility: Requires kubectl and a KubeSphere cluster with the kubeeye extension published in the marketplace.

KubeEye

Overview

KubeEye is a Kubernetes cluster inspection tool for KubeSphere. It detects issues in workloads, nodes, configurations, and components through OPA/Rego policies, PromQL queries, file integrity checks, kernel parameter validation, and systemd health checks. It is installed as a KubeSphere extension.

When to Use

• Installing or configuring the KubeEye cluster inspection extension in KubeSphere
• Writing cluster inspection rules (OPA, PromQL, file checks, etc.)
• Configuring periodic or one-shot inspection tasks
• Viewing or downloading cluster inspection reports

Architecture

Extension Installation Flow

kspublish (push extension to KubeSphere)
    |
    v
Extension available in KubeSphere marketplace
    |
    v
kubectl apply -f installplan.yaml
    |
    v
KubeEye deployed (3 components)

Runtime Architecture

┌─────────────────────────────────────────────────────────────┐
│                     KubeSphere Extension                    │
│                                                             │
│  ┌─────────────────────┐   ┌─────────────────────────────┐  │
│  │   kubeeye-apiserver │   │  kubeeye-controller-manager │  │
│  │   (Gin REST API)    │   │  (4 CRD Controllers)        │  │
│  │   Port 9090         │   │                             │  │
│  └──────────┬──────────┘   └──────────────┬──────────────┘  │
│             │                              │                 │
│             ▼                              ▼                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    CRDs                              │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │   │
│  │  │InspectRule│ │InspectPlan│ │InspectTask│ │Inspect │ │   │
│  │  │          │ │          │ │          │ │Result  │ │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └────────┘ │   │
│  └──────────────────────────────────────────────────────┘   │
│                              │                              │
│                              ▼                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              kubeeye-job (K8s Jobs)                  │   │
│  │  OPA ├─ PromQL ├─ FileChange ├─ Sysctl ├─ Systemd   │   │
│  │  NodeInfo ├─ FileFilter ├─ ServiceConnect ├─ Cmd    │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

> **Note:** `Cmd` in the diagram refers to the `customCommand` rule type.

CRD Overview

| CRD | API Version | Scope | Purpose | |-----|-------------|-------|---------| | **InspectRule** | `kubeeye.kubesphere.io/v1alpha2` | Cluster | Defines inspection rules (OPA, PromQL, file checks, etc.) | | **InspectPlan** | `kubeeye.kubesphere.io/v1alpha2` | Cluster | Schedules inspection execution (cron or one-shot) | | **InspectTask** | `kubeeye.kubesphere.io/v1alpha2` | Cluster | Tracks a single inspection execution (created by InspectPlan) | | **InspectResult** | `kubeeye.kubesphere.io/v1alpha2` | Cluster | Stores inspection results (populated by InspectTask) |

CRD Data Flow

User creates InspectRule ──────┐
                               ├──> InspectPlan references InspectRules
User creates InspectPlan ──────┘         |
                                         | (cron trigger or manual)
                                         v
                               InspectTask created by InspectPlanReconciler
                                         |
                                    InspectTaskReconciler:
                                    1. Fetches referenced InspectRules
                                    2. Merges rules per type
                                    3. Creates K8s Jobs (kubeeye-job)
                                    4. Jobs execute rule checks
                                    5. Results accumulated
                                         |
                                         v
                               InspectResult populated with findings
                                         |
                                         v
                               User views results via:
                               - kubectl get inspectresult
                               - API: HTML report / XLSX download

Before You Start

Check if the KubeEye extension is available:

kubectl get extensionversions | grep kubeeye

Expected output: `kubeeye-{version}` (e.g. `kubeeye-1.0.1`).

If nothing is shown, the extension hasn't been published to KubeSphere yet.

Check if KubeEye is already installed:

kubectl get installplans.kubesphere.io kubeeye --ignore-not-found

If the InstallPlan exists, upgrading is supported — just select a newer version.

Installation

KubeEye is installed as a KubeSphere extension. The extension must first be published to KubeSphere (via `kspublish`, assumed to be already available).

> **Note:** The `./scripts/` paths below assume you are running from the `skills/kubeeye/` directory. Adjust the path if you are running from elsewhere.

Step 1: Detect and Select Version

ALL_VERSIONS=$(kubectl get extensionversions.kubesphere.io \
  -l kubesphere.io/extension-ref=kubeeye \
  -o jsonpath='{range .items[*]}{.spec.version}{"\n"}{end}' | sort -V)

LATEST_STABLE=$(echo "$ALL_VERSIONS" | tail -1)

echo "Available versions