/whizard-telemetry-ruler

name: whizard-telemetry-ruler
description: Use when working with WizTelemetry Ruler extension for KubeSphere, including installation, configuration, alerting rules management

WizTelemetry Ruler

Overview

WizTelemetry Ruler is an extension component in the KubeSphere Observability Platform that provides event alerting and log alerting capabilities. It can define alerting rules for K8s native events, K8s/KubeSphere auditing events, and K8s logs, evaluate incoming event data and log data, and send alerts to specified receivers such as alertmanager, etc.

When to Use

• Installing or configuring the WizTelemetry Ruler extension
• Creating, updating, or deleting alerting rules (RuleGroup/ClusterRuleGroup)
• Managing alerting configurations
• Using the ruler API to manage alerting rules

Components

| Component | Description | Default Enabled | |-----------|-------------|-----------------| | whizard-telemetry-ruler | Core ruler component for alerting | true |

Dependencies

• **WizTelemetry Platform Service** (whizard-telemetry): Required
• **WizTelemetry Events** (whizard-events): Required if event alerting is enabled
• **WizTelemetry Auditing** (whizard-auditing): Required if auditing alerting is enabled
• **WizTelemetry Logging** (whizard-logging): Required if logging alerting is enabled
• **WizTelemetry Notification** (whizard-notification): Optional (for alert notification)
• **WizTelemetry Data Pipeline** (vector): Required if alerting persistence is enabled
• **OpenSearch** (opensearch): Required if alerting persistence is enabled

-

Installation

Prerequisites

**REQUIRED: Complete all steps in order before generating InstallPlan.**

Step 1: Get Available Clusters and Confirm Target

**⚠️ CRITICAL: DO NOT proceed until target clusters are determined.**

**Step 1.1: Get available clusters**

kubectl get clusters -o jsonpath='{.items[*].metadata.name}'

**Step 1.2: Determine target clusters**

• If user **explicitly specified** target clusters in the request → Use those clusters directly, proceed to Step 2
• If user **did NOT specify** target clusters → Ask user to confirm which clusters to deploy to, then proceed to Step 2

**Ask user (if not specified):**

Available clusters: host, dev
Which clusters do you want to deploy WizTelemetry Ruler to?

Step 2: Get Latest Version (if not provided by user)

**MUST do this to get the latest version:**

kubectl get extensionversions -n kubesphere-system -l kubesphere.io/extension-ref=whizard-telemetry-ruler -o jsonpath='{range .items[*]}{.spec.version}{"\n"}{end}' | sort -V | tail -1

This outputs the latest version (e.g., `1.5.0`). Note this down - you'll use it in the InstallPlan.

Step 3: Get AlertManager Host (if configuring sink)

**Only perform this step if you need to configure sink for alert notifications.**

The AlertManager proxy service (`alertmanager-proxy`) is deployed in the host cluster and exposed via NodePort (default port: 31093).

**Step 3.1: Get a host node IP**

kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}'

**Step 3.2: Confirm with user**

Ask user to confirm the AlertManager host IP:

Detected AlertManager host: <NODE_IP>
Detected AlertManager port: 31093
Alert URL: http://<NODE_IP>:31093/api/v1/alerts

Do you want to use this URL for alert notifications?

• If user **confirms** → Use `http://<NODE_IP>:31093/api/v1/alerts` as the sink URL
• If user **provides different URL** → Use the user-specified URL

**Note:** If using WizTelemetry Notification extension, ensure it is installed before installing WizTelemetry Ruler.

Install WizTelemetry Ruler

**⚠️ IMPORTANT: Complete prerequisite steps BEFORE this step.**

Based on your selections:

• **Target clusters**: User-confirmed cluster names
• **AlertManager URL**: From Step 3 (if configuring sink)

**⚠️ CRITICAL: InstallPlan `metadata.name` MUST be `whizard-telemetry-ruler`. DO NOT use any other name.**

**⚠️ CRITICAL: `config` field is YAML format. You MUST:**

• Use the config structure exactly as shown in the template
• **DO NOT** add configuration fields that are not shown in the template
• **DO NOT** modify the structure or hierarchy

**⚠️ CRITICAL: All placeholders MUST be replaced with actual values. DO NOT leave them as placeholders.**

Basic Installation Template (with AlertManager)

apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: whizard-telemetry-ruler
  namespace: kubesphere-system
spec:
  extension:
    name: whizard-telemetry-ruler
    version: <VERSION>  # From Step 2
  enabled: true
  upgradeStrategy: Manual
  config: |
    whizard-telemetry-ruler:
      config:
        sinks:
          - name: alertmanager
            type: webhook
            config:
              url: http://<ALERT_MANAGER_HOST>:31093/api/v1/alerts  # From Step 3
  clusterScheduling:
    placement:
      clusters:
        - <TARGET_CLUSTERS>

Installation with Custom Configuration Template (with all alerting types)

apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: whizard-telemetry-ruler
  namespace: kubesphere-system
spec:
  extension:
    name: whizard-telemetry-ruler
    version: <VERSION>  # From Step 2
  enabled: true
  upgradeStrategy: Manual
  config: |
    whizard-telemetry-ruler:
      auditingAlerting:
        enabled: true
      eventsAlerting:
        enabled: true
      loggingAlerting:
        enabled: false
      config:
        sinks:
        - name: alertmanager
          type: webhook
          config:
            url: http://<ALERT_MANAGER_HOST>:31093/api/v1/alerts  # From Step 3
  clusterScheduling:
    placement:
      clusters:
        - <TARGET_CLUSTERS>

**Replace placeholders:**

• `<VERSION>`: From Step 2 (e.g., `1.5.0`)
• `<TARGET_CLUSTERS>`: User-confirmed cluster names
• `<ALERT_MANAGER_HOST>`: From Step 3 (auto-detected or user-confirmed nod