---

name: openpitrix description: 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 Application Management

Overview

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 |

Architecture

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. |

Navigation and Feature Coverage

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:

• Use Application and ApplicationVersion for app templates, App Store listings, uploaded packages, version review, screenshots, metadata, and categories.
• Use Repo for app repositories and repository sync.
• Use Category for App Store category management.
• Use ApplicationRelease only for installed/deployed apps, including workspace "应用" pages and platform "部署管理" pages.
• Do not troubleshoot an App Store template with release Job/Pod commands unless the user is installing or upgrading an ApplicationRelease.
• Uploaded/self-made app templates use the repository label value application.kubesphere.io/repo-name=upload. Do not write uploaded.
• KSE v2 app and version action examples use {"state":"..."} with optional message, not legacy {"action":"..."}. Legacy openpitrix.io/v2 action APIs use action.
• For 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.

Tool Selection

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/....

Quick Inspection

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>

KAPI Routes

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.

KSE Application API ex