/kubesphere-gateway-api

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