/kubesphere-extension-management

name: kubesphere-extension-management
description: KubeSphere extension management Skill. Use when user requests to install, configure, upgrade, uninstall extensions, or query extension info/troubleshoot issues. Includes extension discovery, dependency management, install configuration, version management.

KubeSphere Extension Management

---

Architecture

┌──────────────────────┐        ┌─────────────────────────────┐        ┌──────────────────────┐        ┌──────────────────────┐
│  Extension Museum    │        │  Extension                  │        │  InstallPlan         │        │  Deployed Extension  │
│  (Local Chart Repo)  │───────▶│  - description              │───────▶│  - extension         │───────▶│                      │
│                      │ (sync) │  - status                   │        │  - config            │        │  Namespace: <target> │
└──────────────────────┘        │  ExtensionVersion           │        │  - clusterScheduling │        │  └── Pods, Services   │
                                │  - version                  │        └──────────────────────┘        └──────────────────────┘
                                │  - chartURL                 │              │ (reconcile)
                                │  - externalDependencies     │              |
                                │  - installationMode         │              |
                                └─────────────────────────────┘              ▼
                                                                    ┌──────────────────────┐
                                                                    │  Job                 │
                                                                    │  helm-upgrade-<name> │
                                                                    │  - helm install/     │
                                                                    │    upgrade/uninstall │
                                                                    └──────────┬───────────┘
                                                                               │
                                                                               ▼
                                                                    ┌──────────────────────┐
                                                                    │  Pod                 │
                                                                    │  (Helm execution)    │
                                                                    └──────────────────────┘

Core Concepts

Extension

Metadata and status for available/installed extensions.

| Field | Description | Example | |-------|-------------|---------| | `metadata.name` | Extension name | `whizard-monitoring` | | `spec.versions[]` | Available versions | `[1.2.0, 1.2.1]` | | `status.state` | Current state | `Installed`/`Upgrading`/`Failed` | | `status.enabled` | Enabled status | `true`/`false` | | `status.installedVersion` | Installed version | `1.2.1` |

---

ExtensionVersion

Version-specific details: Helm chart location, dependencies, requirements.

| Field | Description | Example | |-------|-------------|---------| | `metadata.name` | Version resource name | `whizard-monitoring-1.2.1` | | `spec.version` | Version number | `1.2.1` | | `spec.chartURL` | Helm chart URL | `https://extensions-museum.../whizard-monitoring-1.2.1.tgz` | | `spec.namespace` | Target namespace | `kubesphere-monitoring-system` | | `spec.installationMode` | Install mode | `Multicluster`/`HostOnly` | | `spec.ksVersion` | Required KS version | `>=4.2.0-0` | | `spec.externalDependencies[]` | Required extensions | `[name: whizard-telemetry]` |

---

InstallPlan

Trigger for install/upgrade/uninstall. Creates Helm Job to deploy components.

**Spec**: | Field | Type | Required | Description | |-------|------|----------|-------------| | `metadata.name` | string | ✅ | Must match `spec.extension.name` | | `spec.extension.name` | string | ✅ | Extension name | | `spec.extension.version` | string | ✅ | Exact version to install | | `spec.enabled` | bool | ✅ | Enable extension | | `spec.upgradeStrategy` | string | ✅ | Use `Manual` for production | | `spec.config` | string | ❌ | Custom YAML config | | `spec.clusterScheduling` | object | ❌ | Multi-cluster config (Multicluster mode only) |

**Status**: | Field | Description | |-------|-------------| | `status.state` | `Installed`/`Installing`/`Upgrading`/`Failed` | | `status.jobName` | Helm upgrade Job name | | `status.targetNamespace` | Target namespace | | `status.conditions[]` | Status conditions with messages |

**⚠️ CRITICAL:**

• `metadata.name` = `spec.extension.name`
• Use EXACT version from user request
• Set `enabled: true` and `upgradeStrategy: Manual`

Step-by-Step Workflow

1. List and Inspect Extensions

# List all extensions
kubectl get extensions

# List by category
for c in $(kubectl get categories.kubesphere.io -o jsonpath='{.items[*].metadata.name}'); do
 exts=$(kubectl get extensions.kubesphere.io -l kubesphere.io/category="$c" -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}')
 [ -n "$exts" ] && echo -e "$c:\n$exts"
done

# List extension available versions
kubectl get extensionversions.kubesphere.io -l kubesphere.io/extension-ref=<extension-name>

# View extension details
kubectl describe extension <extension-name>
kubectl describe extensionversion.kubesphere.io <extension-name>-<version>

2. Install Extension

**⚠️ CRITICAL:**

• InstallPlan `metadata.name` MUST match `spec.extension.name`
• Use EXACT version from user request (not `recommendedVersion` or `latest`)

2.1 Verify Version Exists

# Verify the extension and version exist before creating InstallPlan
kubectl get extension <extension-name>
kubectl get extensionversion <extension-name>-<version>

# Get version details (check installationMode, namespace, dependencies, etc.)
kubectl describe extension <extension-name>
kube