# Kubesphere Gateway

KubeSphere Gateway extension management Skill (ingress-nginx based, uses Kubernetes...

- Repository: https://github.com/kubesphere/kubesphere (17074 stars)
- Category: DevOps
- License: see repository
- Last updated: 2026-07-15
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add kubesphere/kubesphere --skill kubesphere-gateway -g -a claude-code -y`
Codex: `npx skills add kubesphere/kubesphere --skill kubesphere-gateway -g -a codex -y`
Cursor: `npx skills add kubesphere/kubesphere --skill kubesphere-gateway -g -a cursor -y`
Gemini CLI: `npx skills add kubesphere/kubesphere --skill kubesphere-gateway -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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`, `Stopped`
  - `status.conditions[].type=GatewayReady`, True when fully operational
  - `status.loadBalancer`, LB ingress IPs/hostnames
  - `status.service`, Service type, ports, external IPs

- **`UpgradePlan`** (`gateway.kubesphere.io/v2alpha2`), batch gateway upgrade job. Key fields:
  - `spec.gatewayReferences`, list of `{name, namespace}` to upgrade
  - `spec.targetAppVersion`, target version
  - `status.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:

The rest: https://github.com/kubesphere/kubesphere/blob/HEAD/skills/kubesphere-gateway/SKILL.md