AI agent skill · by @kubesphere

Whizard Telemetry

Use when installing or configuring the WizTelemetry Platform Service extension for KubeSphere, which provides the common APIServer backend services for all WizTelemetry observability extensions

Archived 2026-10-23 · Source updated 2026-07-15. Check the original repository for the latest version.

SKILL.md instructions

# WizTelemetry Platform Service

## Overview

WizTelemetry Platform Service is a common service for all observability extensions of KubeSphere's WizTelemetry Observability Platform. It provides a common APIServer for all observability extensions, offering backend platform services for Logging, Auditing, Events, Notifications, Tracing, and more.

## When to Use

- Installing or configuring the WizTelemetry Platform Service extension
- Managing API services for observability extensions
- Configuring OpenSearch connections for various data types
- Enabling Global Observability monitoring

## Architecture

### Components

| Component | Description | Default |
|-----------|-------------|---------|
| whizard-telemetry-apiserver | Common APIServer for all observability extensions | 1 replica |
| wiz-telemetry-console | Web console for WizTelemetry | 1 replica |

### Dependencies

The WizTelemetry Platform Service does not have hard dependencies on other components. All APIs can be enabled/disabled based on the deployed extensions:

- **Optional**: OpenSearch - Required only when enabling logging, auditing, events, notification history, or traffic APIs
- **Optional**: Prometheus - Required only when enabling monitoring API
- **Optional**: Notification Manager - Required only when enabling notification API
- **Optional**: KubeSphere Observability (Whizard) - Required only when enabling global observability

Configuration should be added incrementally as you deploy additional observability extensions (e.g., WhizardLogging, WhizardAuditing, WhizardEvents, WhizardNotification).

## Installation

### Prerequisites

**Step 1: Get latest version**

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

**Step 2: Generate config**

Run the helper script in the skill's scripts directory:

```bash
cd whizard-telemetry && ./scripts/generate-config.sh
```

This script will:
1. Check which observability extensions are installed (whizard-logging, whizard-auditing, whizard-events, whizard-notification, whizard-monitoring, whizard-alerting)
2. Check if vector extension is installed
3. Output the config section only (between ---CONFIG_START--- and ---CONFIG_END---)

**Step 3: Create InstallPlan**

Use the generated config to create the InstallPlan:

```yaml
apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: whizard-telemetry
spec:
  extension:
    name: whizard-telemetry
    version: <VERSION>  # From Step 1
  enabled: true
  upgradeStrategy: Manual
  config: |
    <CONFIG_FROM_STEP_2>
```

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

### Configuration from Other Extensions

The whizard-telemetry configuration is **automatically generated** based on which observability extensions are installed. You do NOT need to manually configure it - it will be generated when you install the corresponding extensions.

**How it works:**
- When you install whizard-logging, whizard-auditing, whizard-events, etc., the system automatically generates the corresponding whizard-telemetry config
- OpenSearch endpoint and credentials are obtained from the **vector extension's secret**

## Configuration Parameters

The `whizard-telemetry.config` section is automatically generated by the helper script based on installed extensions. You do not need to manually configure it.

### Image Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `whizard-telemetry.apiserver.image.repository` | string | kubesphere/whizard-telemetry-apiserver | API server image |
| `whizard-telemetry.apiserver.image.tag` | string | latest | API server image tag |
| `wiz-telemetry-console.image.repository` | string | kubesphere/wiz-telemetry-console | Console image |
| `wiz-telemetry-console.image.tag` | string | 2.1.0 | Console image tag |

### Scheduling Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `whizard-telemetry.apiserver.nodeSelector` | object | {} | Node selector |
| `whizard-telemetry.apiserver.tolerations` | list | [] | Tolerations |
| `whizard-telemetry.apiserver.affinity` | object | {} | Affinity |
| `wiz-telemetry-console.nodeSelector` | object | {} | Node selector |
| `wiz-telemetry-console.tolerations` | list | [] | Tolerations |
| `wiz-telemetry-console.affinity` | object | {} | Affinity |

## Extension Operations

### Check Extension Status

```bash
# View extension installation status
kubectl get installplan whizard-telemetry

# View extension version
kubectl get extensionversions -l kubesphere.io/extension-ref=whizard-telemetry
```

### Check Pod Status

```bash
# View API server pods
kubectl get pods -n extension-whizard-telemetry -l app=whizard-telemetry-apiserver

# View console pods
kubectl get pods -n extension-whizard-telemetry -l app=wiz-telemetry-console
```

### View Logs

```bash
# View API server logs
kubectl logs -n extension-whizard-telemetry -l app=whizard-telemetry-apiserver --tail=100

# View console logs
kubectl logs -n extension-whizard-telemetry -l app=wiz-telemetry-console --tail=100
```

### Uninstall Extension

```bash
# Delete the InstallPlan to uninstall
kubectl delete installplan whizard-telemetry
```

### Update Configuration

When new observability extensions are installed or uninstalled (e.g., whizard-logging, whizard-events, whizard-auditing), you need to update the whizard-telemetry config.

**Step 1: Generate new config**

```bash
cd whizard-telemetry && ./scripts/generate-config.sh
```

This script will check installed extensions and generate the complete config.

**Step 2: Update InstallPlan**

```bash
# Get the generated config (between ---CONFIG_START--- and ---CONFIG_END---)
# Then patch the InstallPlan:
kubectl get installplan whizard-telemetry -n kubesphere-system -o yaml > /tmp/whizard-telemetry.yaml

# Edit the file and update the config section, then apply:
kubectl apply -f /tmp/whizard-telemetry.yaml
```

**Note:** The config is automatically generated based on installed extensions. After installing new extensions (logging, events, auditing, notification, etc.), always regenerate and apply the config.

## Troubleshooting

### Check API Server Health

```bash
# Check API server endpoints
kubectl get endpoints -n extension-whizard-telemetry whizard-telemetry-apiserver

# Check API server service
kubectl get svc -n extension-whizard-telemetry whizard-telemetry-apiserver
```


### View Configuration

```bash
# View current configuration
kubectl get installplan whizard-telemetry -o yaml

# View configmap
kubectl get configmap -n extension-whizard-telemetry whizard-telemetry-config -o yaml
```