Loading
KubeSphere OpenPitrix application management Skill. Use when users ask about KubeSphere App Store, OpenPitrix, Helm/YAML application templates, application repositories, app versions, app releases, ca
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add kubesphere/kubesphere --skill openpitrix -a cursor -y
KubeSphere OpenPitrix application management Skill. Use when users ask about KubeSphere App Store, OpenPitrix, Helm/YAML application templates, application repositories, app versions, app releases, categories, review states, repository sync, or troubleshooting application installation and upgrade issues.
KubeSphere OpenPitrix application management Skill. Use when users ask about KubeSphere App Store, OpenPitrix, Helm/YAML application templates, application repositories, app versions, app releases, categories, review states, repository sync, or troubleshooting application installation and upgrade issues.
OpenPitrix is KubeSphere's application management capability for app repositories, app templates, versions, reviews, and app releases. In KubeSphere 4.x the runtime API group is application.kubesphere.io/v2; older OpenPitrix extension code used openpitrix.io/v2 CRUD APIs and openpitrix.io/v2alpha1 read/list wrappers over application.kubesphere.io/v1alpha1 resources.
Use the v2 objects and APIs first:
| Concept | KubeSphere 4.x object | Older OpenPitrix object |
|---|---|---|
| Repository | Repo | HelmRepo |
| App template | Application | HelmApplication |
| App template version | ApplicationVersion | HelmApplicationVersion |
| App release / installed app | ApplicationRelease | HelmRelease |
| Category | Category | HelmCategory |
Core namespace and labels:
| Item | Value |
|---|---|
| Application data namespace | extension-openpitrix |
| Repository label | application.kubesphere.io/repo-name |
| App label | application.kubesphere.io/app-id |
| App version label | application.kubesphere.io/appversion-id |
| App type label | application.kubesphere.io/app-type |
| Cluster label | kubesphere.io/cluster |
| Namespace label | kubesphere.io/namespace |
| Workspace label | kubesphere.io/workspace |
Helm repo index or uploaded package
|
v
Repo sync / upload API
|
v
Application -> ApplicationVersion -> ApplicationRelease
|
v
Helm executor Job or YAML installer
|
v
Workloads in target cluster/namespace
Important controllers:
| Controller | Watches | Purpose |
|---|---|---|
helmrepo-controller | Repo | Loads Helm repository indexes, creates/deletes Application and ApplicationVersion, updates repository sync state. |
appversion-controller | ApplicationVersion | Cleans stored chart/YAML data after version deletion when it is no longer used. |
apprelease-helminstaller | ApplicationRelease | Creates, upgrades, verifies, and uninstalls app releases through Helm executor Jobs or YAML installer logic. |
appcategory-controller | Category | Maintains category counts and prevents deleting categories that still own apps. |
When the user says "应用商店", first identify whether they mean the enterprise-space app management pages or the global component-dock App Store management extension. They share the same OpenPitrix/KSE v2 resources, but the intent and scope differ.
Enterprise-space application management under a workspace:
| Console area | Typical route | User intent | Main resource/API |
|---|---|---|---|
| 应用管理 / 应用 | /workspaces/{workspace}/deploy | List, create, edit, upgrade, or delete installed apps in projects. | ApplicationRelease; /workspaces/{workspace}/applications, /namespaces/{namespace}/applications |
| 应用管理 / 自制应用 | workspace custom app area | Work with user-created/custom applications before or outside App Store publication. | Usually app template/upload flows; verify against Application and ApplicationVersion before assuming release APIs. |
| 应用管理 / 应用模板 | /workspaces/{workspace}/app-templates | Create/upload Helm or YAML app templates, edit template metadata, submit versions for review, manage versions. | Application, ApplicationVersion; /workspaces/{workspace}/apps, /workspaces/{workspace}/apps/{app}/versions |
| 应用管理 / 应用仓库 | /workspaces/{workspace}/app-repos | Add, sync, inspect, or delete Helm repos available to the workspace. | Repo; /workspaces/{workspace}/repos |
Component-dock App Store management:
| Console area | Typical route | User intent | Main resource/API |
|---|---|---|---|
| 组件坞 / 应用商店管理 / 应用 | /apps-manage/store | Platform-level App Store template list, publish/unpublish, edit metadata, delete, open detail pages. | Application, ApplicationVersion; /workspaces/{workspace}/apps, /apps/{app}/action |
| 组件坞 / 应用商店管理 / 应用分类 | /apps-manage/categories | Create, edit, delete categories and assign applications to categories. | Category; /categories, /workspaces/{workspace}/apps/{app} |
| 组件坞 / 应用商店管理 / 应用审核 | /apps-manage/reviews | Review uploaded app versions submitted from enterprise spaces. | ApplicationVersion; /reviews, /workspaces/{workspace}/apps/{app}/versions/{version}/action |
| 组件坞 / 应用商店管理 / 应用仓库 | /apps-manage/repo | Manage global/platform view of App Store repositories. | Repo; /workspaces/{workspace}/repos |
| 组件坞 / 应用商店管理 / 部署管理 | /apps-manage/deploy | Manage installed app releases across workspace/cluster/namespace scope. | ApplicationRelease; /workspaces/{workspace}/applications, /namespaces/{namespace}/applications |
Resource selection rules:
Application and ApplicationVersion for app templates, App Store listings, uploaded packages, version review, screenshots, metadata, and categories.Repo for app repositories and repository sync.Category for App Store category management.ApplicationRelease only for installed/deployed apps, including workspace "应用" pages and platform "部署管理" pages.ApplicationRelease.application.kubesphere.io/repo-name=upload. Do not write uploaded.{"state":"..."} with optional message, not legacy {"action":"..."}. Legacy openpitrix.io/v2 action APIs use action.kubectl get/describe of OpenPitrix application CRDs, do not add -n extension-openpitrix by default. These resources are queried by resource kind and labels; use labels such as kubesphere.io/workspace, application.kubesphere.io/repo-name, application.kubesphere.io/app-id, or application.kubesphere.io/app-release-name. Use extension-openpitrix only when inspecting extension component Pods or storage fallback objects.Choose the tool by task. Prefer the first matching option:
| Tool | Use for | Authentication |
|---|---|---|
kubectl | Inspect CRDs/resources, events, controller state, executor Jobs/Pods/logs, and cluster-side troubleshooting. | Uses the current kubeconfig. |
ks_api.py | KubeSphere JSON KAPIs under /kapis/...; recommended for create/update/list/action calls that send JSON. | Run login once; token is cached in ~/.kubesphere_token. |
curl | Multipart uploads, package/file downloads, custom headers, reproducing exact HTTP requests, or when the user explicitly asks for curl. | Requires Authorization: Bearer $TOKEN; get the token with ks_api.py --login or set it manually. |
Set up ks_api.py first when using KubeSphere KAPIs:
cd skills/kubesphere-core/scripts
export KUBESPHERE_HOST="http://<kubesphere-host>"
python ks_api.py --login --username admin --password <password>
For curl, reuse the token cached by ks_api.py:
export KUBESPHERE_HOST="http://<kubesphere-host>"
export TOKEN=$(python -c 'import json, os; print(json.load(open(os.path.expanduser("~/.kubesphere_token")))["token"])')
If ks_api.py is unavailable, obtain an OAuth token directly:
export KUBESPHERE_HOST="http://<kubesphere-host>"
export TOKEN=$(curl -sS -X POST "$KUBESPHERE_HOST/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "username=<username>" \
-d "password=<password>" \
-d "client_id=kubesphere" \
-d "client_secret=kubesphere" | jq -r '.access_token')
Then pass -H "Authorization: Bearer $TOKEN" on every curl request to /kapis/....
Start with cluster resources before calling KAPIs:
kubectl get repos.application.kubesphere.io
kubectl get applications.application.kubesphere.io
kubectl get applicationversions.application.kubesphere.io
kubectl get applicationreleases.application.kubesphere.io
kubectl get categories.application.kubesphere.io
For workspace-scoped views, filter by workspace label:
kubectl get repos.application.kubesphere.io \
-l kubesphere.io/workspace=<workspace>
kubectl get applications.application.kubesphere.io \
-l kubesphere.io/workspace=<workspace>
For an installed app:
kubectl get applicationreleases.application.kubesphere.io \
-l kubesphere.io/cluster=<cluster>,kubesphere.io/namespace=<namespace>
kubectl describe applicationrelease.application.kubesphere.io <release-name>
Use /kapis/application.kubesphere.io/v2 in KubeSphere 4.x.
Repository routes:
| Operation | Route |
|---|---|
| List repositories | GET /workspaces/{workspace}/repos |
| Create repository | POST /workspaces/{workspace}/repos |
| Update repository | PATCH /workspaces/{workspace}/repos/{repo} |
| Delete repository | DELETE /workspaces/{workspace}/repos/{repo} |
| Manual sync | POST /workspaces/{workspace}/repos/{repo}/action |
| Repository events | GET /workspaces/{workspace}/repos/{repo}/events |
App template routes:
| Operation | Route |
|---|---|
| List apps | GET /workspaces/{workspace}/apps |
| Create uploaded app | POST /workspaces/{workspace}/apps |
| Describe app | GET /workspaces/{workspace}/apps/{app} |
| Create/update app metadata | POST /workspaces/{workspace}/apps/{app} |
| Patch metadata | PATCH /workspaces/{workspace}/apps/{app} |
| Delete app | DELETE /workspaces/{workspace}/apps/{app} |
| Review/action app | POST /apps/{app}/action |
Version and release routes:
| Operation | Route |
|---|---|
| List versions | GET /workspaces/{workspace}/apps/{app}/versions |
| Create version | POST /workspaces/{workspace}/apps/{app}/versions |
| Describe version | GET /workspaces/{workspace}/apps/{app}/versions/{version} |
| Download package | GET /workspaces/{workspace}/apps/{app}/versions/{version}/package |
| List chart/YAML files | GET /workspaces/{workspace}/apps/{app}/versions/{version}/files |
| Review/action version | POST /workspaces/{workspace}/apps/{app}/versions/{version}/action |
| List releases by workspace | GET /workspaces/{workspace}/applications |
| List releases by namespace | GET /namespaces/{namespace}/applications |
| Create release | POST /namespaces/{namespace}/applications |
| Describe release | GET /namespaces/{namespace}/applications/{application} |
| Delete release | DELETE /namespaces/{namespace}/applications/{application} |
App Store management routes:
| Operation | Route |
|---|---|
| List categories | GET /categories |
| Create category | POST /categories |
| Update category | POST /categories/{category} |
| Describe category | GET /categories/{category} |
| Delete category | DELETE /categories/{category} |
| List app reviews | GET /reviews |
| Upload attachment | POST /workspaces/{workspace}/attachments |
| Describe attachment | GET /workspaces/{workspace}/attachments/{attachment} |
| Delete attachments | DELETE /workspaces/{workspace}/attachments/{attachment} |
Older OpenPitrix extension routes use /kapis/openpitrix.io/v2alpha1, primarily as read/list wrappers around HelmRepo, HelmApplication, HelmApplicationVersion, HelmRelease, and HelmCategory.
Assume KUBESPHERE_HOST, ks_api.py login, and TOKEN have already been set up from Tool Selection before using the examples below.
Use these examples for KubeSphere 4.x application.kubesphere.io/v2.
# Create or update repository.
python ks_api.py POST /kapis/application.kubesphere.io/v2/workspaces/<workspace>/repos '{
"metadata": {
"name": "<repo-name>",
"labels": {
"kubesphere.io/workspace": "<workspace>"
},
"annotations": {
"kubesphere.io/display-name": "<display-name>"
}
},
"spec": {
"url": "https://example.com/charts",
"description": "<description>",
"syncPeriod": 0
}
}'
# Manually trigger repository sync.
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/repos/<repo-name>/action
# List apps in a workspace.
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps
# Describe an app and list versions.
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>/versions
# Review or publish an app version.
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>/versions/<version>/action \
'{"state":"active","message":"publish"}'
# App-level publish/suspend/recover actions also use state, not legacy action.
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/apps/<app>/action \
'{"state":"suspended","message":"suspend from App Store"}'
# Create or update an application release.
# Important:
# - Use /namespaces/<namespace>/applications, not /workspaces/<workspace>/namespaces/<namespace>/applications.
# - Required release references are spec.appID, spec.appVersionID, spec.appType, and labels.
# - Do not invent spec.name or spec.namespace; release name and namespace are metadata/path concerns.
# - spec.values is a JSON []byte field: use "" for empty values, or base64-encoded YAML bytes for non-empty values. Do not use {}.
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/namespaces/<namespace>/applications '{
"metadata": {
"name": "<release-name>",
"labels": {
"application.kubesphere.io/app-id": "<app-id>",
"application.kubesphere.io/appversion-id": "<app-version-id>",
"application.kubesphere.io/app-type": "helm",
"kubesphere.io/cluster": "<cluster>",
"kubesphere.io/namespace": "<namespace>",
"kubesphere.io/workspace": "<workspace>"
},
"annotations": {
"kubesphere.io/creator": "<username>"
}
},
"spec": {
"appID": "<app-id>",
"appVersionID": "<app-version-id>",
"appType": "helm",
"values": ""
}
}'
# List or describe releases in a namespace.
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/namespaces/<namespace>/applications
# Or list releases by workspace.
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/applications
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/namespaces/<namespace>/applications/<release-name>
# Categories and reviews.
python ks_api.py GET /kapis/application.kubesphere.io/v2/categories
python ks_api.py GET /kapis/application.kubesphere.io/v2/reviews
Use curl only when the API needs multipart upload, streaming download, or custom headers that ks_api.py does not support.
Curl equivalents for JSON KAPIs:
export KUBESPHERE_HOST="http://<kubesphere-host>"
export TOKEN="<kubesphere-access-token>"
# Create or update repository.
curl -sS -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/repos" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"name": "<repo-name>",
"labels": {
"kubesphere.io/workspace": "<workspace>"
},
"annotations": {
"kubesphere.io/display-name": "<display-name>"
}
},
"spec": {
"url": "https://example.com/charts",
"description": "<description>",
"syncPeriod": 0
}
}'
# Manually trigger repository sync.
curl -sS -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/repos/<repo-name>/action" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
# For KSE v2 repository sync, use an empty JSON body or omit the body.
# Do not send legacy {"action":"sync"} or {"action":"index"} unless using openpitrix.io/v2.
# List apps in a workspace.
curl -sS \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps" \
-H "Authorization: Bearer $TOKEN"
# Publish or review an app version.
curl -sS -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>/versions/<version>/action" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"state":"active","message":"publish"}'
# Create or update an application release.
# Keep the body shape aligned with ApplicationReleaseSpec. Do not add spec.name/spec.namespace.
# Use values: "" for empty values; do not use values: {}.
curl -sS -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/namespaces/<namespace>/applications" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"name": "<release-name>",
"labels": {
"application.kubesphere.io/app-id": "<app-id>",
"application.kubesphere.io/appversion-id": "<app-version-id>",
"application.kubesphere.io/app-type": "helm",
"kubesphere.io/cluster": "<cluster>",
"kubesphere.io/namespace": "<namespace>",
"kubesphere.io/workspace": "<workspace>"
}
},
"spec": {
"appID": "<app-id>",
"appVersionID": "<app-version-id>",
"appType": "helm",
"values": ""
}
}'
Use these only when the installed OpenPitrix extension exposes the old openpitrix.io KAPIs. Prefer application.kubesphere.io/v2 for KubeSphere 4.x. The legacy request/response fields use OpenPitrix-style snake_case names such as repo_id, version_id, sync_period, and app_default_status.
Read/list wrappers from /kapis/openpitrix.io/v2alpha1:
# Repositories.
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/repos
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/repos/<repo-id>
# App templates and versions.
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/apps
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/apps/<app-id>
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/apps/<app-id>/versions
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/apps/<app-id>/versions/<version-id>
# Installed applications.
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/clusters/<cluster>/namespaces/<namespace>/applications
python ks_api.py GET \
/kapis/openpitrix.io/v2alpha1/workspaces/<workspace>/clusters/<cluster>/namespaces/<namespace>/applications/<application-id>
# Categories.
python ks_api.py GET /kapis/openpitrix.io/v2alpha1/categories
python ks_api.py GET /kapis/openpitrix.io/v2alpha1/categories/<category-id>
Older CRUD-style APIs from /kapis/openpitrix.io/v2:
# Create repository. Use validate=true to validate without persisting.
python ks_api.py POST \
/kapis/openpitrix.io/v2/workspaces/<workspace>/repos?validate=true '{
"name": "<repo-name>",
"url": "https://example.com/charts",
"type": "helm",
"visibility": "public",
"providers": ["kubernetes"],
"sync_period": "0s",
"app_default_status": "active",
"credential": ""
}'
# Trigger repository indexing/sync.
python ks_api.py POST \
/kapis/openpitrix.io/v2/workspaces/<workspace>/repos/<repo-id>/action \
'{"action":"index","workspace":"<workspace>"}'
# Create an app template from a base64-encoded chart package.
python ks_api.py POST \
/kapis/openpitrix.io/v2/workspaces/<workspace>/apps '{
"name": "<app-name>",
"version_name": "0.1.0",
"version_type": "helm",
"version_package": "<base64-chart-tgz>"
}'
# Create another version for an existing app.
python ks_api.py POST \
/kapis/openpitrix.io/v2/workspaces/<workspace>/apps/<app-id>/versions '{
"app_id": "<app-id>",
"name": "0.2.0",
"type": "helm",
"package": "<base64-chart-tgz>"
}'
# Submit, pass, reject, suspend, recover, or activate an app version.
python ks_api.py POST \
/kapis/openpitrix.io/v2/workspaces/<workspace>/apps/<app-id>/versions/<version-id>/action \
'{"action":"submit","message":"submit for review"}'
# Deploy an app release.
python ks_api.py POST \
/kapis/openpitrix.io/v2/workspaces/<workspace>/clusters/<cluster>/namespaces/<namespace>/applications '{
"name": "<release-name>",
"app_id": "<app-id>",
"version_id": "<version-id>",
"runtime_id": "<cluster>",
"conf": "{}",
"advanced_param": []
}'
KubeSphere's OpenPitrix extension serves both enterprise-space application management and component-dock App Store management. Map the console area to the KSE v2 APIs before choosing commands:
| UI area | Main purpose | Primary APIs |
|---|---|---|
/workspaces/{workspace}/deploy | Enterprise-space installed apps. | /workspaces/{workspace}/applications, /namespaces/{namespace}/applications |
/workspaces/{workspace}/app-templates | Enterprise-space app templates created from Helm/YAML packages. | /workspaces/{workspace}/apps, /workspaces/{workspace}/apps/{app}/versions, /workspaces/{workspace}/attachments |
/workspaces/{workspace}/app-repos | Enterprise-space app repositories. | /workspaces/{workspace}/repos |
/apps-manage/store | Manage application templates in the App Store: list, create/upload, edit metadata, delete, open detail pages. | /workspaces/{workspace}/apps, /workspaces/{workspace}/apps/{app}, /workspaces/{workspace}/attachments |
/apps-manage/store/{app} | Inspect template details, versions, audit records, and deployed instances. | /workspaces/{workspace}/apps/{app}, /workspaces/{workspace}/apps/{app}/versions, /workspaces/{workspace}/applications |
/apps-manage/categories | Manage categories and assign apps to categories. | /categories, /categories/{category}, /workspaces/{workspace}/apps/{app} |
/apps-manage/reviews | Review uploaded app versions. | /reviews, /workspaces/{workspace}/apps/{app}/versions/{version}/action |
/apps-manage/repo | Manage Helm repositories that feed App Store templates. | /workspaces/{workspace}/repos |
/apps-manage/deploy | Manage installed app releases. | /namespaces/{namespace}/applications, /workspaces/{workspace}/applications |
List and filter behavior:
Application templates, not installed ApplicationRelease objects.ApplicationRelease objects.conditions, status, order, limit, and workspace query scope.active|suspended apps; management views include draft, passed, active, and suspended states.application.kubesphere.io/repo-name=upload.Inspect app templates:
python ks_api.py GET \
"/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps?conditions=status=draft|active|suspended|passed&sortBy=create_time"
kubectl get applications.application.kubesphere.io \
-l kubesphere.io/workspace=<workspace>
Inspect installed apps/releases:
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/applications
python ks_api.py GET \
/kapis/application.kubesphere.io/v2/namespaces/<namespace>/applications
kubectl get applicationreleases.application.kubesphere.io \
-l kubesphere.io/workspace=<workspace>
Patch app template metadata. This is how the enterprise-space template page and App Store management page edit alias, description, icon, category, screenshots/attachments, abstraction, and home URL:
python ks_api.py PATCH \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app> '{
"aliasName": "<display-name>",
"description": "<description>",
"categoryName": "<category>",
"icon": "<base64-icon-or-url>",
"attachments": ["<attachment-id>"],
"abstraction": "<short-summary>",
"appHome": "https://example.com"
}'
The patch handler writes these fields to:
| Request field | Stored as |
|---|---|
categoryName | metadata.labels["application.kubesphere.io/app-category-name"] |
aliasName | metadata.annotations["kubesphere.io/display-name"] |
description | metadata.annotations["kubesphere.io/description"] |
icon | spec.icon |
attachments | spec.attachments |
abstraction | spec.abstraction |
appHome | spec.appHome |
Manage attachments for App Store screenshots and other assets. This API is multipart, so prefer curl with the bearer token:
curl -sS -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/attachments" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@./screenshot.png"
curl -sS \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/attachments/<attachment-id>" \
-H "Authorization: Bearer $TOKEN"
curl -sS -X DELETE \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/attachments/<attachment-id>" \
-H "Authorization: Bearer $TOKEN"
Manage categories:
python ks_api.py GET /kapis/application.kubesphere.io/v2/categories
python ks_api.py POST /kapis/application.kubesphere.io/v2/categories '{
"metadata": {
"name": "<category>",
"annotations": {
"kubesphere.io/display-name": "<display-name>",
"kubesphere.io/description": "<description>"
}
},
"spec": {
"icon": "database"
}
}'
python ks_api.py POST /kapis/application.kubesphere.io/v2/categories/<category> '{
"metadata": {
"name": "<category>",
"annotations": {
"kubesphere.io/display-name": "<display-name>",
"kubesphere.io/description": "<description>"
}
},
"spec": {
"icon": "database"
}
}'
python ks_api.py DELETE /kapis/application.kubesphere.io/v2/categories/<category>
Do not delete kubesphere-app-uncategorized, and do not delete a category whose status.total is greater than zero. To move apps between categories, patch each app's categoryName through /workspaces/{workspace}/apps/{app}.
Review uploaded app versions:
python ks_api.py GET \
"/kapis/application.kubesphere.io/v2/reviews?conditions=status=submitted"
python ks_api.py GET \
"/kapis/application.kubesphere.io/v2/reviews?conditions=status=active|rejected|passed|submitted|suspended"
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>/versions/<version>/action \
'{"state":"passed","message":"approve"}'
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>/versions/<version>/action \
'{"state":"rejected","message":"reject reason"}'
/reviews lists uploaded app versions only; the handler selects versions whose repo label is application.kubesphere.io/repo-name=upload. If a review item is missing, first verify that the ApplicationVersion belongs to the upload repo and is in a review state such as submitted.
Important KSE v2 App Store API shapes:
# Correct uploaded/self-made template label.
kubectl get applicationversions.application.kubesphere.io \
-l application.kubesphere.io/repo-name=upload
# Correct category create/update body is a Category object.
python ks_api.py POST /kapis/application.kubesphere.io/v2/categories '{
"metadata": {
"name": "<category>",
"annotations": {
"kubesphere.io/display-name": "<display-name>",
"kubesphere.io/description": "<description>"
}
},
"spec": {
"icon": "database"
}
}'
# Correct repository create/update body is a Repo object shape.
python ks_api.py POST /kapis/application.kubesphere.io/v2/workspaces/<workspace>/repos '{
"metadata": {
"name": "<repo-name>",
"labels": {
"kubesphere.io/workspace": "<workspace>"
},
"annotations": {
"kubesphere.io/display-name": "<display-name>"
}
},
"spec": {
"url": "https://example.com/charts",
"description": "<description>",
"syncPeriod": 0
}
}'
# Correct KSE v2 review/action body uses state.
python ks_api.py POST \
/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps/<app>/versions/<version>/action \
'{"state":"passed","message":"approve"}'
Avoid these common mistakes for application.kubesphere.io/v2:
application.kubesphere.io/repo-name=uploaded; the built-in upload repo key is upload.{"name":"...","displayName":"..."}; send a Category object with metadata and spec.{"name":"...","url":"..."}; send a Repo object with metadata and spec.{"action":"approve"}, {"action":"reject"}, or {"action":"sync"} to KSE v2 action routes; use state for app/version actions and an empty body for repository manual sync.Create or update a repository with a valid Helm repository URL. The API validates the URL by loading the repository index before persisting it. User info embedded in the URL is copied into spec.credential.
apiVersion: application.kubesphere.io/v2
kind: Repo
metadata:
name: <repo-name>
labels:
kubesphere.io/workspace: <workspace>
annotations:
kubesphere.io/display-name: <display-name>
spec:
url: https://example.com/charts
description: <description>
syncPeriod: 0
Sync behavior:
spec.syncPeriod: 0 means no periodic sync.status.state to manualTrigger.status.state to successful.<repo-name>-<short-hash-of-chart-name>.Troubleshoot repository sync:
kubectl describe repo.application.kubesphere.io <repo-name>
kubectl get events --field-selector involvedObject.name=<repo-name>
kubectl logs -n kubesphere-system deploy/ks-controller-manager \
| grep -E "helmrepo-controller|<repo-name>"
Common checks:
.spec.url has a reachable index.yaml.insecureSkipTLSVerify when using private HTTPS repositories.WorkspaceTemplate; the controller deletes workspace repos for deleted workspaces.Uploaded apps are stored as Repo=upload and start in review state draft. Helm charts and YAML packages share the same API path; appType distinguishes helm and yaml.
Validation-only upload:
Authenticate through KubeSphere first. Prefer the kubesphere-core ks_api.py helper for JSON KAPIs because it handles login and cached tokens consistently with other KubeSphere skills. File uploads are multipart requests, so use ks_api.py to login and then curl with the cached token:
cd skills/kubesphere-core/scripts
export KUBESPHERE_HOST="http://<kubesphere-host>"
python ks_api.py --login --username admin --password <password>
TOKEN=$(python -c 'import json, os; print(json.load(open(os.path.expanduser("~/.kubesphere_token")))["token"])')
curl -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps?validate=true" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: multipart/form-data" \
-F 'jsonData={"appType":"helm","workspace":"<workspace>"}' \
-F "file=@./chart.tgz"
If the helper is unavailable, use curl with an explicit bearer token:
TOKEN=<kubesphere-access-token>
curl -X POST \
"$KUBESPHERE_HOST/kapis/application.kubesphere.io/v2/workspaces/<workspace>/apps?validate=true" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: multipart/form-data" \
-F 'jsonData={"appType":"helm","workspace":"<workspace>"}' \
-F "file=@./chart.tgz"
After upload:
kubectl get applications.application.kubesphere.io \
-l application.kubesphere.io/repo-name=upload,kubesphere.io/workspace=<workspace>
kubectl get applicationversions.application.kubesphere.io \
-l application.kubesphere.io/repo-name=upload,application.kubesphere.io/app-id=<app>
Review states:
| State | Meaning |
|---|---|
draft | Uploaded but not published. |
submitted | Submitted for review. |
passed | Review passed. |
active | Published/visible. |
rejected | Review rejected. |
suspended | Temporarily hidden. |
Use app or version action routes to move review state. App activation requires at least one active or passed version.
An ApplicationRelease installs a selected ApplicationVersion into a target cluster and namespace.
Minimal Helm release object:
apiVersion: application.kubesphere.io/v2
kind: ApplicationRelease
metadata:
name: <release-name>
labels:
application.kubesphere.io/app-id: <app-id>
application.kubesphere.io/appversion-id: <app-version-id>
application.kubesphere.io/app-type: helm
kubesphere.io/cluster: <cluster>
kubesphere.io/namespace: <namespace>
kubesphere.io/workspace: <workspace>
annotations:
kubesphere.io/creator: <username>
spec:
appID: <app-id>
appVersionID: <app-version-id>
appType: helm
values: <base64-or-api-provided-bytes>
Release states:
| State | Meaning |
|---|---|
creating | First reconciliation started. |
created | Helm/YAML executor Job was created. |
upgrading | Spec changed and upgrade started. |
upgraded | Upgrade Job was created. |
active | Helm release deployed or YAML install completed. |
timeout | Helm reported timeout; controller performs limited rechecks. |
deployFailed | Executor Job failed or disappeared. |
failed | Helm/YAML install, upgrade, or status verification failed. |
deleting | Uninstall started. |
clusterDeleted | Target cluster was deleted. |
Troubleshoot releases:
kubectl describe applicationrelease.application.kubesphere.io <release-name>
TARGET_NS=$(kubectl get applicationrelease.application.kubesphere.io <release-name> \
-o jsonpath="{.metadata.labels['kubesphere.io/namespace']}")
kubectl -n "$TARGET_NS" get jobs \
-l application.kubesphere.io/app-release-name=<release-name>
kubectl -n "$TARGET_NS" get pods \
-l application.kubesphere.io/app-release-name=<release-name>
Always prefer the application.kubesphere.io/app-release-name=<release-name> label selector for executor Jobs and Pods. Do not use broad kubectl get jobs -A | grep <release-name> or kubectl get pods -A | grep <release-name> as the primary path; use grep only as a fallback when labels are missing or suspected to be wrong.
Then inspect the executor Job pod logs:
POD=$(kubectl -n "$TARGET_NS" get pods \
-l application.kubesphere.io/app-release-name=<release-name> \
-o jsonpath='{.items[0].metadata.name}')
kubectl -n "$TARGET_NS" logs "$POD" --all-containers
Common checks:
spec.appVersionID exists and points to an ApplicationVersion.default, missing cluster defaults to host.spec.values contains valid YAML documents and the target cluster RESTMapper recognizes every GVR..status.specHash with the current .spec; spec changes drive upgrades.application.kubesphere.io/timeout-recheck; the controller only performs limited timeout rechecks.Categories are cluster-scoped resources. Application category is carried by application.kubesphere.io/app-category-name; uncategorized apps use kubesphere-app-uncategorized.
kubectl get categories.application.kubesphere.io
kubectl get applications.application.kubesphere.io \
-l application.kubesphere.io/app-category-name=<category>
Do not delete a category until no applications reference it.
When changing implementation:
application.kubesphere.io/v2 CRDs and KAPIs for new KubeSphere code./kapis/openpitrix.io/v2 and /kapis/openpitrix.io/v2alpha1.Repo owns synced apps, Application owns versions, and releases reference app/version through labels and spec fields.extension-openpitrix.