---

name: kubesphere-gateway-api description: KubeSphere Gateway API extension management Skill (Traefik based, uses Kubernetes Gateway API + GatewayProxy CRD gatewayapi.kubesphere.io/v1alpha1). This is the newer Kubernetes Gateway API standard. For the older Ingress API based gateway (ingress-nginx + Gateway CRD gateway.kubesphere.io/v2alpha2), see the kubesphere-gateway skill instead. Covers installation, uninstallation, status checks, GatewayProxy status inspection, and troubleshooting.

KubeSphere Gateway API

Overview

Provides external access management using Kubernetes Gateway API with Traefik as the underlying proxy implementation. Supports three-tier gatewayproxy management:

| Tier | Scope | Name Pattern | Namespace | Description | | ------------------- | ------------------------ | -------------------------------------- | ------------------------------ | ----------------------------- | | Cluster | Entire cluster | gatewayproxy-cluster | kubesphere-controls-system | Cluster-scoped GatewayProxy | | Workspace | Single workspace | gatewayproxy-workspace-{workspace} | kubesphere-controls-system | Workspace-scoped GatewayProxy | | Project | Single project/namespace | gatewayproxy-namespace-{namespace} | kubesphere-controls-system | Namespace-scoped GatewayProxy |

Each GatewayProxy (gatewayproxies.gatewayapi.kubesphere.io) deploys a Traefik instance (the proxy implementation). It auto-creates a GatewayClass, and users can then create standard Gateway (gateways.gateway.networking.k8s.io) resources that reference that GatewayClass. The extension consists of three components:

• backend-extension — API server on the host cluster
• backend-agent — API server + controller-manager on every cluster (including the host cluster if selected)
• frontend — React SPA served via Nginx

Key Differentiator from kubesphere-gateway

| Aspect | kubesphere-gateway | kubesphere-gateway-api | | -------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------- | | Underlying proxy | ingress-nginx | Traefik | | API standard | Custom Gateway CRD (gateway.kubesphere.io/v2alpha2) | Kubernetes Gateway API (gateway.networking.k8s.io) + GatewayProxy CRD | | Core resource | Gateway + standard IngressClass/Ingress | GatewayProxy + standard Gateway/GatewayClass/HTTPRoute | | Lifecycle management | Helm release per gateway | Helm release per GatewayProxy |

Core CRDs

• GatewayProxy (gatewayapi.kubesphere.io/v1alpha1) — the proxy implementation (e.g. Traefik). When created, the controller deploys Traefik via Helm SDK and auto-creates a GatewayClass. Key fields:

  • spec.type — proxy type (currently only Traefik)
  • spec.traefik.rawValues — raw Helm values passed to the Traefik chart
  • spec.traefik.deployment.replicas — replica count
  • spec.traefik.service.type — Service type (ClusterIP, NodePort, LoadBalancer)
  • spec.traefik.createDefaultGateway — whether to auto-create a default Gateway
  • spec.paused — pause reconciliation
  • status.conditions — condition types: Ready, Progressing, NewVersionDetected
  • status.service — Service type, ports, external IPs, load balancer status
  • status.entrypoints — exposed entrypoints with ports and protocols
  • status.gatewayClass.name — auto-created GatewayClass name
  • status.helmRelease.name — Helm release name

• GatewayClass (gateway.networking.k8s.io/v1) — standard Kubernetes Gateway API class, auto-created by the GatewayProxy controller

• Gateway (gateway.networking.k8s.io/v1) — standard Kubernetes Gateway API gateway, associated with a GatewayClass

• HTTPRoute / GRPCRoute / TLSRoute / TCPRoute / UDPRoute — standard Kubernetes Gateway API route resources

Multi-Tenant Scoping

GatewayProxy and Gateway are scoped via labels:

• gatewayapi.kubesphere.io/scope-type — cluster, workspace, or namespace
• gatewayapi.kubesphere.io/scope-workspace — workspace name (for workspace scope)
• gatewayapi.kubesphere.io/scope-namespace — namespace name (for namespace scope)

Monitoring Integration

GatewayProxy exposes Traefik metrics via Prometheus. Requires the whizard-monitoring extension (optional dependency). Log search requires the whizard-logging extension.

---

Before You Start

Check if Gateway API extension is already installed:

kubectl get installplans.kubesphere.io gateway-api --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-api \
  -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 question with multiple: true:
  • All clusters → TARGET_CLUSTERS="$READY_CLUSTERS"
  • Host cluster only → TARGET_CLUSTERS="$HOST_CLUSTER"
  • (custom) — validate each name against $READY_CLUSTERS

Step 3: Generate and Apply InstallPlan

./scripts/generate-installplan.sh "$SELECTED_VERSION" "$TARGET_CLUSTERS"

This generates the YAML to /tmp/gateway-api-installplan.yaml, runs --dry-run=server, then prints the apply command.

Apply it:

kubectl apply -f /tmp/gateway-api-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-api &>/dev/null; then
  echo "Gateway API is not installed."
  exit 0
fi

Confirm with the user, then delete:

kubectl delete installplans.kubesphere.io gateway-api --ignore-not-found

Verify cleanup:

./scripts/verify-uninstall.sh

Success criteria:

1. InstallPlan is deleted
2. No active pods remain in extension-gateway-api namespace

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

---

GatewayProxy Operations

List GatewayProxies

GatewayProxies are organized by scope type. List them:

echo "=== Cluster GatewayProxies ==="
kubectl get gatewayproxies.gatewayapi.kubesphere.io -A \
  -l gatewayapi.kubesphere.io/scope-type=cluster

echo -e "\n=== Workspace GatewayProxies ==="
kubectl get gatewayproxies.gatewayapi.kubesphere.io -A \
  -l gatewayapi.kubesphere.io/scope-type=workspace

echo -e "\n=== Namespace GatewayProxies ==="
kubectl get gatewayproxies.gatewayapi.kubesphere.io -A \
  -l gatewayapi.kubesphere.io/scope-type=namespace

Check GatewayProxy Status

Pick a gateway proxy name from the list above and run:

GWP_NS="kubesphere-controls-system"
GWP_NAME="<gatewayproxy-name-from-list>"

# app.kubernetes.io/instance uses the Helm release name if available, otherwise the GatewayProxy name
GWP_INSTANCE=$(kubectl get gatewayproxies.gatewayapi.kubesphere.io -n $GWP_NS $GWP_NAME -o jsonpath='{.status.helmRelease.name}' 2>/dev/null)
if [ -z "$GWP_INSTANCE" ]; then
  GWP_INSTANCE="$GWP_NAME"
fi

kubectl get gatewayproxies.gatewayapi.kubesphere.io -n $GWP_NS $GWP_NAME -o wide
kubectl describe gatewayproxies.gatewayapi.kubesphere.io -n $GWP_NS $GWP_NAME
kubectl get gatewayproxies.gatewayapi.kubesphere.io -n $GWP_NS $GWP_NAME -o yaml
kubectl get pods -n $GWP_NS -l "app.kubernetes.io/instance=$GWP_INSTANCE"

GatewayProxy conditions:

| Condition Type | Status True | Meaning | | ---------------------- | ----------- | --------------------------- | | Ready | True | Fully operational | | Progressing | True | Being created or updated | | NewVersionDetected | True | New chart version available |

List Associated Gateways

Each GatewayProxy may have associated standard Gateways and GatewayClasses. The GatewayProxy creates GatewayClasses with the label gatewayapi.kubesphere.io/gateway-class-name, and auto-created Gateways carry scope labels:

# List GatewayClasses created by any GatewayProxy
kubectl get gatewayclass -l "gatewayapi.kubesphere.io/gateway-class-name"

# List Gateways associated with a specific GatewayProxy (by scope label)
kubectl get gateways.gateway.networking.k8s.io -n $GWP_NS \
  -l "gatewayapi.kubesphere.io/scope-type"

# Alternatively, list Gateways by the GatewayClass name they reference
GW_CLASS=$(kubectl get gatewayproxies.gatewayapi.kubesphere.io -n $GWP_NS $GWP_NAME \
  -o jsonpath='{.status.gatewayClass.name}')
kubectl get gateways.gateway.networking.k8s.io -A \
  -o jsonpath='{range .items[?(@.spec.gatewayClassName=="'"$GW_CLASS"'")]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{.spec.gatewayClassName}{"\n"}{end}'

View GatewayProxy Pods and Logs

kubectl get pods -n $GWP_NS -l "app.kubernetes.io/instance=$GWP_INSTANCE"
kubectl logs -n $GWP_NS -l "app.kubernetes.io/instance=$GWP_INSTANCE" --tail=100

---

Troubleshooting

Set $GWP_NAME and $GWP_NS to the target GatewayProxy name a