kubesphere-gateway
KubeSphere Gateway extension management Skill (ingress-nginx based, uses Kubernetes Ingress API + Gateway CRD gateway.kubesphere.io/v2alpha2). For the newer Kubernetes Gateway API (Traefik + GatewayProxy CRD), see the kubesphere-gateway-api skill instead.
Install / Use
npx skills add kubesphere/kubesphere --skill kubesphere-gatewayInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of kubesphere-gateway
kubesphere-gateway scores 92/100 on our quality scale, 206th of 745 Operations skills we index (top 28%).
Its SKILL.md is 11 KB long, well organised into 23 sections with 17 code examples: a thorough specification that gives an agent plenty to work with.
With 17,059 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-09-30 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit β read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-26. Automated pattern scan on 2026-09-26. It catches known dangerous patterns, not every risk β read a skill before letting an agent act on it.
kubesphere-gateway compared with similar skills
All 4 of these similar skills score higher than kubesphere-gateway; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| kubesphere-gateway (this skill)by kubesphere | 92 | 17.1k | 4mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
| crawl4aiby unclecode | 100 | 87.4k | 3d ago | MCP Server |
Frequently asked questions
- How do I install kubesphere-gateway?
- Run
npx skills add kubesphere/kubesphere --skill kubesphere-gateway. The install tabs above show the steps for each supported agent. - Which AI agents does kubesphere-gateway work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is kubesphere-gateway safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is kubesphere-gateway still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: kubesphere-gateway description: KubeSphere Gateway extension management Skill (ingress-nginx based, uses Kubernetes Ingress API + Gateway CRD gateway.kubesphere.io/v2alpha2). For the newer Kubernetes Gateway API (Traefik + GatewayProxy CRD), see the kubesphere-gateway-api skill instead. Covers installation, uninstallation, status checks, gateway status inspection, and troubleshooting (gateway stuck states, Helm failures, pod issues).
KubeSphere Gateway
Overview
Provides external access management (ingress) for KubeSphere using ingress-nginx. Supports three-tier gateway management:
| Tier | Scope | Name Pattern | Namespace | Label |
|---|---|---|---|
| Cluster | Entire cluster | kubesphere-router-cluster | kubesphere-controls-system | kubesphere.io/gateway-type=cluster |
| Workspace | Single workspace | kubesphere-router-workspace-{workspace} | kubesphere-controls-system | kubesphere.io/gateway-type=workspace |
| Project | Single project/namespace | kubesphere-router-{namespace} | kubesphere-controls-system | kubesphere.io/gateway-type=project |
Each gateway is a standalone Helm release of ingress-nginx. The gateway-controller-manager manages the lifecycle (install/upgrade/uninstall) via Helm.
Core CRDs
-
Gateway(gateway.kubesphere.io/v2alpha2) β represents a single ingress-nginx deployment. Key fields:spec.appVersionβ the Helm chart version (e.g.kubesphere-nginx-ingress-<version>)spec.valuesβ Helm values for ingress-nginx (controller config, service type, resources, etc.)status.stateβCreating,Updating,Running,Faulted,Stoppedstatus.conditions[].type=GatewayReadyβ True when fully operationalstatus.loadBalancerβ LB ingress IPs/hostnamesstatus.serviceβ Service type, ports, external IPs
-
UpgradePlan(gateway.kubesphere.io/v2alpha2) β batch gateway upgrade job. Key fields:spec.gatewayReferencesβ list of{name, namespace}to upgradespec.targetAppVersionβ target versionstatus.stateβPending,Running,Succeeded,Failed
Monitoring Integration
Gateway exposes NGINX metrics (requests, 4xx/5xx, latency P50/P90/P99) via Prometheus. Requires the whizard-monitoring extension (optional dependency).
Before You Start
Check if Gateway extension is already installed:
kubectl get installplans.kubesphere.io gateway --ignore-not-found
If found, upgrading is supported β just select a newer version in Step 1.
Installation
Step 1: Detect and Select Version
ALL_VERSIONS=$(kubectl get extensionversions.kubesphere.io \
-l kubesphere.io/extension-ref=gateway \
-o jsonpath='{range .items[*]}{.spec.version}{"\n"}{end}' | sort -V)
LATEST_STABLE=$(echo "$ALL_VERSIONS" | grep -v -E 'alpha|beta|rc' | tail -1)
if [ -z "$LATEST_STABLE" ]; then
LATEST_STABLE=$(echo "$ALL_VERSIONS" | tail -1)
fi
echo "Available versions:"
echo "$ALL_VERSIONS"
echo ""
echo "Latest stable: $LATEST_STABLE"
This sets ALL_VERSIONS and LATEST_STABLE. Use SELECTED_VERSION for the version chosen.
Use the question tool:
$LATEST_STABLE (Recommended)β accept the auto-detected version- (custom) β type a specific version; validate it against the printed list
Step 2: Detect and Select Clusters
CLUSTER_DATA=$(kubectl get clusters.cluster.kubesphere.io \
-o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}')
READY_CLUSTERS=$(echo "$CLUSTER_DATA" | awk -F'\t' '$2 == "True" {print $1}')
CLUSTER_COUNT=$(echo "$READY_CLUSTERS" | wc -l)
HOST_CLUSTER=$(kubectl get clusters.cluster.kubesphere.io \
-l 'cluster-role.kubesphere.io/host' \
-o jsonpath='{.items[0].metadata.name}' || echo "")
echo "Ready clusters:"
echo "$READY_CLUSTERS"
echo ""
echo "Cluster count: $CLUSTER_COUNT"
echo "Host cluster: $HOST_CLUSTER"
This sets READY_CLUSTERS, CLUSTER_COUNT, HOST_CLUSTER.
- 1 cluster β skip selection, auto-use it. Set
TARGET_CLUSTERS="$HOST_CLUSTER" - Multiple clusters β use
questionwithmultiple: true:- All clusters β
TARGET_CLUSTERS="$READY_CLUSTERS" - Host cluster only β
TARGET_CLUSTERS="$HOST_CLUSTER" - (custom) β validate each name against
$READY_CLUSTERS
- All clusters β
Step 3: Generate and Apply InstallPlan
./scripts/generate-installplan.sh "$SELECTED_VERSION" "$TARGET_CLUSTERS"
This generates the YAML to /tmp/gateway-installplan.yaml, runs --dry-run=server, then prints the apply command.
For configurable extension values (ingress-nginx default settings, image registry, upgrade tool config, etc.), see references/extension-values.md.
Apply it:
kubectl apply -f /tmp/gateway-installplan.yaml
Tell the user "Installing". Then ask if they want to check status. If yes:
./scripts/check-status.sh poll
Status Checking
| Purpose | Command |
|---|---|
| Single snapshot | ./scripts/check-status.sh quick |
| Wait until complete (5min timeout) | ./scripts/check-status.sh poll |
Logic:
- All
Installedβ β success - Any
Failedβ β prints full status - Timeout (300s) β β prints current status
- In progress β prints every 10s
Uninstallation
β Always confirm with the user before proceeding.
Uninstall from all clusters
if ! kubectl get installplans.kubesphere.io gateway &>/dev/null; then
echo "Gateway is not installed."
exit 0
fi
Confirm with the user, then delete:
kubectl delete installplans.kubesphere.io gateway --ignore-not-found
Verify cleanup:
./scripts/verify-uninstall.sh
Success criteria:
- InstallPlan is deleted
- No active pods remain in
extension-gatewaynamespace
Uninstall from specific clusters
WARNING: Do NOT delete the InstallPlan. Only remove target clusters from the placement list.
Confirm which clusters to remove, compute remaining clusters, then patch:
kubectl patch installplans.kubesphere.io gateway --type='json' \
-p='[{"op": "replace", "path": "/spec/clusterScheduling/placement/clusters", "value": ["<REMAINING_CLUSTER_1>", "<REMAINING_CLUSTER_2>"]}]'
Success: patch returns OK + removed clusters no longer in .status.clusterSchedulingStatuses.
Gateway Operations
List Gateways
Gateways are organized by tier (see Overview), with each tier identified by the label kubesphere.io/gateway-type. List them grouped by tier:
echo "=== Cluster Gateway ==="
kubectl get gateways.gateway.kubesphere.io -n kubesphere-controls-system \
-l kubesphere.io/gateway-type=cluster
echo -e "\n=== Workspace Gateways ==="
kubectl get gateways.gateway.kubesphere.io -n kubesphere-controls-system \
-l kubesphere.io/gateway-type=workspace
echo -e "\n=== Project Gateways ==="
kubectl get gateways.gateway.kubesphere.io -n kubesphere-controls-system \
-l kubesphere.io/gateway-type=project
Check Gateway Status
Pick a gateway name from the List Gateways output and run:
GW_NS="kubesphere-controls-system"
GW_NAME="<gateway-name-from-list>"
# app.kubernetes.io/instance uses the Helm release name if available, otherwise the Gateway name
GW_INSTANCE=$(kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o jsonpath='{.status.helmRelease.name}' 2>/dev/null)
if [ -z "$GW_INSTANCE" ]; then
GW_INSTANCE="$GW_NAME"
fi
kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o wide
kubectl describe gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME
kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o yaml
kubectl get pods -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE"
Gateway states:
| State | Meaning |
|---|---|
| Creating | First-time Helm install in progress |
| Updating | Helm upgrade in progress (spec changed) |
| Running | Fully operational (all replicas available) |
| Faulted | Deployment missing, stopped unexpectedly, or health probe timeout |
| Stopped | Scaled to zero replicas intentionally |
Troubleshooting
Set
$GW_NAMEaccording to the gateway tier being troubleshot (see naming rules in Overview):
- Cluster β
GW_NAME=kubesphere-router-cluster- Workspace β
GW_NAME=kubesphere-router-workspace-${WORKSPACE}- Project β
GW_NAME=kubesphere-router-${NAMESPACE}Common namespace:
GW_NS=kubesphere-controls-system
$GW_INSTANCEis auto-resolved fromstatus.helmRelease.name(falls back to$GW_NAME). If not yet set, run:GW_INSTANCE=$(kubectl get gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME -o jsonpath='{.status.helmRelease.name}' 2>/dev/null) if [ -z "$GW_INSTANCE" ]; then GW_INSTANCE="$GW_NAME" fi
Gateway stuck in Creating or Updating state
kubectl describe gateways.gateway.kubesphere.io -n $GW_NS $GW_NAME
kubectl logs -n extension-gateway -l app=gateway-controller-manager --tail=200 | grep -iE "(error|helm|install|upgrade|reconcile)"
kubectl get deployment -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE,app.kubernetes.io/component=controller"
kubectl get configmap -n $GW_NS $GW_NAME -o yaml
Common causes: Chart ConfigMap missing/corrupted, Helm wrapper timeout, invalid spec.values.
Gateway shows Faulted state
kubectl get deployment -n $GW_NS $GW_NAME -o wide
kubectl describe deployment -n $GW_NS $GW_NAME
kubectl get pods -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE" -o wide
POD_NAME=$(kubectl get pods -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE" -o jsonpath='{.items[0].metadata.name}')
kubectl describe pod -n $GW_NS $POD_NAME
kubectl logs -n $GW_NS $POD_NAME --tail=100
Common causes: Image pull failure, resource constraints, port conflicts, missing ConfigMap/Secret.
Gateway pod crash-looping / CrashLoopBackOff
kubectl logs -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE" --tail=100 --previous
kubectl get events -n $GW_NS --sort-by='.lastTimestamp' | tail -20
kubectl exec -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE" -- cat /etc/nginx/nginx.conf 2>/dev/null | head -50
kubectl get configmap -n $GW_NS -l "app.kubernetes.io/instance=$GW_INSTANCE" -o yaml
Common causes: Misconfigured nginx config, port conflicts, resource limits (OOMKilled), missing dependencies (ConfigMap/Secret).
Log search not working
Gateway log search proxies to whizard-telemetry-apiserver:
kubectl get configmap -n extension-gateway gateway-agent-backend-config -o yaml
kubectl get pods -n extension-whizard-telemetry
kubectl get svc -n extension-whizard-telemetry whizard-telemetry-apiserver
kubectl logs -n extension-gateway -l app=gateway-apiserver --tail=100 | grep -iE "(log|search|whizard|proxy)"
Common causes: Whizard-telemetry not installed or not running, misconfigured gateway-agent-backend-config, network policy blocking cross-namespace traffic.
Gateway controller not reconciling
kubectl get pods -n extension-gateway -l app=gateway-controller-manager
kubectl logs -n extension-gateway -l app=gateway-controller-manager --tail=200
kubectl get validatingwebhookconfiguration -l "app.kubernetes.io/managed-by=Helm,kubesphere.io/extension-ref=gateway"
kubectl get deployment -n extension-gateway -l app=gateway-controller-manager -o yaml
Common causes: Controller pod not running, webhook configuration blocking updates, Helm release state mismatch, RBAC permission issues.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu β one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6kπ·οΈ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
crawl4ai
87.4kOfficial Crawl4AI Cloud: a hosted web scraping, extraction, and search API for AI agents. Free API key, 1,000 credits a month, no card. Fully open source: this repo is the Apache-2.0 crawler that powers it, and you can self-host it.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit β see the Safety scan above for what the skill file itself contains.
