{"id":"a24a338c-e0ab-4d20-b1ec-a69022e2595a","shortId":"HZEJGC","kind":"skill","title":"kubesphere-extension-management","tagline":"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.","description":"# KubeSphere Extension Management\n\n\n---\n\n## Architecture\n\n\n```\n┌──────────────────────┐        ┌─────────────────────────────┐        ┌──────────────────────┐        ┌──────────────────────┐\n│  Extension Museum    │        │  Extension                  │        │  InstallPlan         │        │  Deployed Extension  │\n│  (Local Chart Repo)  │───────▶│  - description              │───────▶│  - extension         │───────▶│                      │\n│                      │ (sync) │  - status                   │        │  - config            │        │  Namespace: <target> │\n└──────────────────────┘        │  ExtensionVersion           │        │  - clusterScheduling │        │  └── Pods, Services   │\n                                │  - version                  │        └──────────────────────┘        └──────────────────────┘\n                                │  - chartURL                 │              │ (reconcile)\n                                │  - externalDependencies     │              |\n                                │  - installationMode         │              |\n                                └─────────────────────────────┘              ▼\n                                                                    ┌──────────────────────┐\n                                                                    │  Job                 │\n                                                                    │  helm-upgrade-<name> │\n                                                                    │  - helm install/     │\n                                                                    │    upgrade/uninstall │\n                                                                    └──────────┬───────────┘\n                                                                               │\n                                                                               ▼\n                                                                    ┌──────────────────────┐\n                                                                    │  Pod                 │\n                                                                    │  (Helm execution)    │\n                                                                    └──────────────────────┘\n```\n\n## Core Concepts\n\n### Extension\nMetadata and status for available/installed extensions.\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `metadata.name` | Extension name | `whizard-monitoring` |\n| `spec.versions[]` | Available versions | `[1.2.0, 1.2.1]` |\n| `status.state` | Current state | `Installed`/`Upgrading`/`Failed` |\n| `status.enabled` | Enabled status | `true`/`false` |\n| `status.installedVersion` | Installed version | `1.2.1` |\n\n---\n\n### ExtensionVersion\nVersion-specific details: Helm chart location, dependencies, requirements.\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `metadata.name` | Version resource name | `whizard-monitoring-1.2.1` |\n| `spec.version` | Version number | `1.2.1` |\n| `spec.chartURL` | Helm chart URL | `https://extensions-museum.../whizard-monitoring-1.2.1.tgz` |\n| `spec.namespace` | Target namespace | `kubesphere-monitoring-system` |\n| `spec.installationMode` | Install mode | `Multicluster`/`HostOnly` |\n| `spec.ksVersion` | Required KS version | `>=4.2.0-0` |\n| `spec.externalDependencies[]` | Required extensions | `[name: whizard-telemetry]` |\n\n---\n\n### InstallPlan\nTrigger for install/upgrade/uninstall. Creates Helm Job to deploy components.\n\n**Spec**:\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `metadata.name` | string | ✅ | Must match `spec.extension.name` |\n| `spec.extension.name` | string | ✅ | Extension name |\n| `spec.extension.version` | string | ✅ | Exact version to install |\n| `spec.enabled` | bool | ✅ | Enable extension |\n| `spec.upgradeStrategy` | string | ✅ | Use `Manual` for production |\n| `spec.config` | string | ❌ | Custom YAML config |\n| `spec.clusterScheduling` | object | ❌ | Multi-cluster config (Multicluster mode only) |\n\n**Status**:\n| Field | Description |\n|-------|-------------|\n| `status.state` | `Installed`/`Installing`/`Upgrading`/`Failed` |\n| `status.jobName` | Helm upgrade Job name |\n| `status.targetNamespace` | Target namespace |\n| `status.conditions[]` | Status conditions with messages |\n\n**⚠️ CRITICAL:**\n- `metadata.name` = `spec.extension.name`\n- Use EXACT version from user request\n- Set `enabled: true` and `upgradeStrategy: Manual`\n\n\n\n## Step-by-Step Workflow\n\n### 1. List and Inspect Extensions\n\n```bash\n# List all extensions\nkubectl get extensions\n\n# List by category\nfor c in $(kubectl get categories.kubesphere.io -o jsonpath='{.items[*].metadata.name}'); do\n exts=$(kubectl get extensions.kubesphere.io -l kubesphere.io/category=\"$c\" -o jsonpath='{range .items[*]}{.metadata.name}{\"\\n\"}{end}')\n [ -n \"$exts\" ] && echo -e \"$c:\\n$exts\"\ndone\n\n# List extension available versions\nkubectl get extensionversions.kubesphere.io -l kubesphere.io/extension-ref=<extension-name>\n\n# View extension details\nkubectl describe extension <extension-name>\nkubectl describe extensionversion.kubesphere.io <extension-name>-<version>\n```\n\n### 2. Install Extension\n\n**⚠️ CRITICAL:**\n- InstallPlan `metadata.name` MUST match `spec.extension.name`\n- Use EXACT version from user request (not `recommendedVersion` or `latest`)\n\n#### 2.1 Verify Version Exists\n\n```bash\n# Verify the extension and version exist before creating InstallPlan\nkubectl get extension <extension-name>\nkubectl get extensionversion <extension-name>-<version>\n\n# Get version details (check installationMode, namespace, dependencies, etc.)\nkubectl describe extension <extension-name>\nkubectl describe extensionversion <extension-name>-<version>\n```\n\n#### 2.2 Create InstallPlan\n\nBased on the extension details above:\n- **config**: Omit if user didn't request custom configuration\n- **clusterScheduling**: Only include if `installationMode=Multicluster`, specify clusters in `placement.clusters`\n\n\n```yaml\napiVersion: kubesphere.io/v1alpha1\nkind: InstallPlan\nmetadata:\n  name: <extension-name>\nspec:\n  # clusterScheduling:    # Only for Multicluster extensions.\n  #   placement:\n  #     clusters:\n  #     - <cluster-name>\n  #   overrides:\n  #     host: |-\n  #       # Extension agent configuration: custom settings for the extension agent in the current cluster, with higher priority than the global extension configuration.\n  # \n  #       custom:\n  #         key: override-value\n  # config: |  ## Omit if user didn't request custom config\n  #   # Custom configuration for the extension, serving as a global extension configuration that can override default settings.\n  # \n  #   custom:\n  #     key: override-value\n  enabled: true\n  extension:\n    name: <extension-name>     # CRITICAL: MUST match metadata.name\n    version: <version>         # CRITICAL: Use EXACT version requested\n  upgradeStrategy: Manual\n```\n\n```bash\nkubectl apply -f installplan-<extension-name>.yaml\n```\n\n### 3. Track & Verify Installation\n\n```bash\n# Watch status\nkubectl get installplan <extension-name> -w\n\n# Get details\nkubectl describe installplan <extension-name>\n\n# Verify extension status\nkubectl describe extension <extension-name>\n\n# Check deployed resources\nNAMESPACE=$(kubectl get installplan <extension-name> -o jsonpath='{.status.targetNamespace}')\nkubectl get pods,svc -n $NAMESPACE\n```\n\n### 4. Update & Upgrade Extension\n\n**⚠️ CRITICAL: InstallPlan `metadata.name` MUST match `spec.extension.name`**\n\n- **Update**: Modify `spec.config` or `spec.clusterScheduling` (version unchanged)\n- **Upgrade**: Modify `spec.extension.version` to new version\n\n```bash\n# Get current InstallPlan as template\nkubectl get installplan <extension-name> -o yaml > installplan-<extension-name>.yaml\n\n# Edit and apply:\n# - For Update: modify spec.config or spec.clusterScheduling\n# - For Upgrade: change spec.extension.version to target version\nkubectl apply -f installplan-<extension-name>.yaml\nkubectl get installplan <extension-name> -w\n```\n\n### 5. Uninstall Extension\n\n```bash\nkubectl delete installplan <extension-name>\n```\n\n## Best Practices\n\n- Use default config (omit `spec.config`) unless custom values are needed\n- Always use `upgradeStrategy: Manual` for production\n- Use exact version (not `recommendedVersion` or `latest`)\n- Test in staging before production\n- Review changelogs before upgrades\n- Document custom configurations\n\n## Troubleshooting\n\n### Issue 1: InstallPlan Failed (Job Execution Failed)\n\n**Symptoms:** InstallPlan stuck in \"Installing\"/\"Upgrading\", Job pod shows Error/Failed\n\n**Diagnosis:**\n\n```bash\n# Step 1: Check InstallPlan status\nkubectl describe installplan <extension-name>\n# Check status.state and status.conditions\n\n# Step 2: Check Job pod logs\nNAMESPACE=$(kubectl get installplan <extension-name> -o jsonpath='{.status.targetNamespace}')\nJOB_NAME=$(kubectl get installplan <extension-name> -o jsonpath='{.status.jobName}')\nkubectl logs -n $NAMESPACE -l job-name=$JOB_NAME --tail=100\n\n# Step 3: For Multicluster - check cluster scheduling status\nkubectl get installplan <extension-name> -o jsonpath='{.status.clusterSchedulingStatuses}' | jq .\n# Check each cluster's state and conditions, then get job name and logs\n```\n\n**Solutions:**\n- Verify extension version exists\n- Check dependencies are installed\n- Check config syntax\n\n---\n\n### Issue 2: InstallPlan Status Not Updated (Job Completed)\n\n**Symptoms:** Job pod completed successfully, but InstallPlan stays in \"Installing\"/\"Upgrading\"\n\n**Diagnosis:**\n\n```bash\n# Check if job completed\nNAMESPACE=$(kubectl get installplan <extension-name> -o jsonpath='{.status.targetNamespace}')\nJOB_NAME=$(kubectl get installplan <extension-name> -o jsonpath='{.status.jobName}')\nkubectl get pods -n $NAMESPACE -l job-name=$JOB_NAME\n\n# Check job completion time vs current time\nkubectl get job $JOB_NAME -n $NAMESPACE -o jsonpath='{.status.completionTime}'\n```\n\n**Cause:** Clock skew between nodes (NTP not synchronized)\n\n**Solution:** Check and synchronize NTP across all cluster nodes\n\n## Quick Reference\n\n| Action | Command |\n|--------|---------|\n| List all extensions | `kubectl get extensions` |\n| List extension versions | `kubectl get extensionversions.kubesphere.io -l kubesphere.io/extension-ref=<name>` |\n| View extension details | `kubectl describe extension <name>` |\n| View version details | `kubectl describe extensionversion <name>-<version>` |\n| Install extension | `kubectl apply -f installplan-<name>.yaml` |\n| Track installation | `kubectl get installplan <name> -w` |\n| Upgrade extension | Modify version in InstallPlan, then `kubectl apply` |\n| Uninstall extension | `kubectl delete installplan <name>` |\n\n## References\n\n- [KubeSphere Extensions Documentation](https://docs.kubesphere.com.cn/v4.2.1/06-extension-management/)\n- [KubeSphere Extensions Marketplace](https://kubesphere.com.cn/marketplace/)\n\n## Related Skills\n\n- `kubesphere-core` - Core platform architecture\n- `kubesphere-cluster-management` - Cluster operations","tags":["kubesphere","extension","management","agent-skills","cloud-native","cncf","devops","ebpf","hacktoberfest","kubernetes","llm","multi-cluster"],"capabilities":["skill","source-kubesphere","skill-kubesphere-extension-management","topic-agent-skills","topic-cloud-native","topic-cncf","topic-devops","topic-ebpf","topic-hacktoberfest","topic-kubernetes","topic-kubesphere","topic-llm","topic-multi-cluster","topic-multi-tenancy","topic-observability"],"categories":["kubesphere"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/kubesphere/kubesphere/kubesphere-extension-management","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add kubesphere/kubesphere","source_repo":"https://github.com/kubesphere/kubesphere","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 16920 github stars · SKILL.md body (10,986 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-03T00:52:30.074Z","embedding":null,"createdAt":"2026-04-18T21:53:16.998Z","updatedAt":"2026-05-03T00:52:30.074Z","lastSeenAt":"2026-05-03T00:52:30.074Z","tsv":"'-0':159 '/category=':295 '/extension-ref=':322,862 '/marketplace/)':914 '/v1alpha1':417 '/v4.2.1/06-extension-management/)':908 '/whizard-monitoring-1.2.1.tgz':141 '1':262,655,674 '1.2.0':92 '1.2.1':93,108,129,133 '100':717 '2':332,686,759 '2.1':351 '2.2':385 '3':510,719 '4':548 '4.2.0':158 '5':609 'across':839 'action':845 'agent':433,440 'alway':628 'apivers':414 'appli':506,586,601,878,896 'architectur':36,922 'avail':90,314 'available/installed':78 'base':388 'bash':267,355,504,514,571,612,672,778 'best':616 'bool':198 'c':278,296,308 'categori':276 'categories.kubesphere.io':282 'caus':826 'chang':595 'changelog':647 'chart':44,115,136 'charturl':57 'check':374,532,675,681,687,722,733,751,755,779,809,835 'clock':827 'cluster':216,410,429,444,723,735,841,925,927 'clusterschedul':53,403,423 'command':846 'complet':765,769,782,811 'compon':176 'concept':72 'condit':239,739 'config':50,211,217,394,458,466,620,756 'configur':15,30,402,434,452,468,477,652 'core':71,919,920 'creat':171,363,386 'critic':242,335,492,497,552 'current':95,443,573,814 'custom':209,401,435,453,465,467,483,624,651 'default':481,619 'delet':614,900 'depend':27,117,377,752 'deploy':41,175,533 'describ':327,330,380,383,524,530,679,867,873 'descript':46,81,120,181,223 'detail':113,325,373,392,522,865,871 'diagnosi':671,777 'didn':398,462 'discoveri':26 'docs.kubesphere.com.cn':907 'docs.kubesphere.com.cn/v4.2.1/06-extension-management/)':906 'document':650,905 'done':311 'e':307 'echo':306 'edit':584 'enabl':101,199,252,488 'end':303 'error/failed':670 'etc':378 'exact':193,246,342,499,635 'exampl':82,121 'execut':70,659 'exist':354,361,750 'ext':288,305,310 'extens':3,6,18,21,25,34,37,39,42,47,73,79,84,139,162,189,200,266,270,273,313,324,328,334,358,367,381,391,427,432,439,451,471,476,490,527,531,551,611,748,849,852,854,864,868,876,889,898,904,910 'extensions-museum':138 'extensions.kubesphere.io':291 'extensionvers':52,109,370,384,874 'extensionversion.kubesphere.io':331 'extensionversions.kubesphere.io':318,858 'externaldepend':59 'f':507,602,879 'fail':99,228,657,660 'fals':104 'field':80,119,178,222 'get':272,281,290,317,366,369,371,518,521,537,543,572,578,606,693,701,727,741,785,793,799,817,851,857,885 'global':450,475 'helm':63,65,69,114,135,172,230 'helm-upgrad':62 'higher':446 'host':431 'hoston':153 'includ':24,405 'info/troubleshoot':22 'inspect':265 'instal':14,29,66,97,106,150,196,225,226,333,513,665,754,775,875,883 'install/upgrade/uninstall':170 'installationmod':60,375,407 'installplan':40,167,336,364,387,419,508,519,525,538,553,574,579,582,603,607,615,656,662,676,680,694,702,728,760,772,786,794,880,886,893,901 'issu':23,654,758 'item':285,300 'job':61,173,232,658,667,688,698,712,714,742,764,767,781,790,805,807,810,818,819 'job-nam':711,804 'jq':732 'jsonpath':284,298,540,696,704,730,788,796,824 'key':454,484 'kind':418 'ks':156 'kubectl':271,280,289,316,326,329,365,368,379,382,505,517,523,529,536,542,577,600,605,613,678,692,700,706,726,784,792,798,816,850,856,866,872,877,884,895,899 'kubespher':2,5,33,146,903,909,918,924 'kubesphere-cluster-manag':923 'kubesphere-cor':917 'kubesphere-extension-manag':1 'kubesphere-monitoring-system':145 'kubesphere.com.cn':913 'kubesphere.com.cn/marketplace/)':912 'kubesphere.io':294,321,416,861 'kubesphere.io/category=':293 'kubesphere.io/extension-ref=':320,860 'kubesphere.io/v1alpha1':415 'l':292,319,710,803,859 'latest':350,640 'list':263,268,274,312,847,853 'local':43 'locat':116 'log':690,707,745 'manag':4,7,28,32,35,926 'manual':204,256,503,631 'marketplac':911 'match':185,339,494,556 'messag':241 'metadata':74,420 'metadata.name':83,122,182,243,286,301,337,495,554 'mode':151,219 'modifi':559,566,589,890 'monitor':88,128,147 'multi':215 'multi-clust':214 'multiclust':152,218,408,426,721 'museum':38,140 'must':184,338,493,555 'n':302,304,309,546,708,801,821 'name':85,125,163,190,233,421,491,699,713,715,743,791,806,808,820 'namespac':51,144,236,376,535,547,691,709,783,802,822 'need':627 'new':569 'node':830,842 'ntp':831,838 'number':132 'o':283,297,539,580,695,703,729,787,795,823 'object':213 'omit':395,459,621 'oper':928 'overrid':430,456,480,486 'override-valu':455,485 'placement':428 'placement.clusters':412 'platform':921 'pod':54,68,544,668,689,768,800 'practic':617 'prioriti':447 'product':206,633,645 'queri':20 'quick':843 'rang':299 'recommendedvers':348,638 'reconcil':58 'refer':844,902 'relat':915 'repo':45 'request':12,250,346,400,464,501 'requir':118,155,161,180 'resourc':124,534 'review':646 'schedul':724 'serv':472 'servic':55 'set':251,436,482 'show':669 'skew':828 'skill':8,916 'skill-kubesphere-extension-management' 'solut':746,834 'source-kubesphere' 'spec':177,422 'spec.charturl':134 'spec.clusterscheduling':212,562,592 'spec.config':207,560,590,622 'spec.enabled':197 'spec.extension.name':186,187,244,340,557 'spec.extension.version':191,567,596 'spec.externaldependencies':160 'spec.installationmode':149 'spec.ksversion':154 'spec.namespace':142 'spec.upgradestrategy':201 'spec.version':130 'spec.versions':89 'specif':112 'specifi':409 'stage':643 'state':96,737 'status':49,76,102,221,238,516,528,677,725,761 'status.clusterschedulingstatuses':731 'status.completiontime':825 'status.conditions':237,684 'status.enabled':100 'status.installedversion':105 'status.jobname':229,705,797 'status.state':94,224,682 'status.targetnamespace':234,541,697,789 'stay':773 'step':258,260,673,685,718 'step-by-step':257 'string':183,188,192,202,208 'stuck':663 'success':770 'svc':545 'symptom':661,766 'sync':48 'synchron':833,837 'syntax':757 'system':148 'tail':716 'target':143,235,598 'telemetri':166 'templat':576 'test':641 'time':812,815 'topic-agent-skills' 'topic-cloud-native' 'topic-cncf' 'topic-devops' 'topic-ebpf' 'topic-hacktoberfest' 'topic-kubernetes' 'topic-kubesphere' 'topic-llm' 'topic-multi-cluster' 'topic-multi-tenancy' 'topic-observability' 'track':511,882 'trigger':168 'troubleshoot':653 'true':103,253,489 'type':179 'unchang':564 'uninstal':17,610,897 'unless':623 'updat':549,558,588,763 'upgrad':16,64,98,227,231,550,565,594,649,666,776,888 'upgrade/uninstall':67 'upgradestrategi':255,502,630 'url':137 'use':9,203,245,341,498,618,629,634 'user':11,249,345,397,461 'valu':457,487,625 'verifi':352,356,512,526,747 'version':31,56,91,107,111,123,131,157,194,247,315,343,353,360,372,496,500,563,570,599,636,749,855,870,891 'version-specif':110 'view':323,863,869 'vs':813 'w':520,608,887 'watch':515 'whizard':87,127,165 'whizard-monitor':86,126 'whizard-telemetri':164 'workflow':261 'yaml':210,413,509,581,583,604,881","prices":[{"id":"6e4bdd42-5221-4d37-81b7-2c17b0fef797","listingId":"a24a338c-e0ab-4d20-b1ec-a69022e2595a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"kubesphere","category":"kubesphere","install_from":"skills.sh"},"createdAt":"2026-04-18T21:53:16.998Z"}],"sources":[{"listingId":"a24a338c-e0ab-4d20-b1ec-a69022e2595a","source":"github","sourceId":"kubesphere/kubesphere/kubesphere-extension-management","sourceUrl":"https://github.com/kubesphere/kubesphere/tree/master/skills/kubesphere-extension-management","isPrimary":false,"firstSeenAt":"2026-04-18T21:53:16.998Z","lastSeenAt":"2026-05-03T00:52:30.074Z"}],"details":{"listingId":"a24a338c-e0ab-4d20-b1ec-a69022e2595a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"kubesphere","slug":"kubesphere-extension-management","github":{"repo":"kubesphere/kubesphere","stars":16920,"topics":["agent-skills","ai","cloud-native","cncf","devops","ebpf","hacktoberfest","kubernetes","kubesphere","llm","multi-cluster","multi-tenancy","observability","servicemesh","skills","skills-sh","skillsmp"],"license":"other","html_url":"https://github.com/kubesphere/kubesphere","pushed_at":"2026-04-27T06:10:27Z","description":"The container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ 🖥 ☁️","skill_md_sha":"9dc8af1323fa3ba2410fb43c7e35e1e1fa9a3f78","skill_md_path":"skills/kubesphere-extension-management/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/kubesphere/kubesphere/tree/master/skills/kubesphere-extension-management"},"layout":"multi","source":"github","category":"kubesphere","frontmatter":{"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."},"skills_sh_url":"https://skills.sh/kubesphere/kubesphere/kubesphere-extension-management"},"updatedAt":"2026-05-03T00:52:30.074Z"}}