helm-add-gwapi-route

Files (1)

• SKILL.md

SKILL.md (first lines)

# helm-add-gwapi-route

Add or modernize Gateway API *Route resources inside a Helm chart. The skill only edits files — git operations (branch, commit, push, PR) are left to the caller.

## When to invoke

Invoke proactively (without an explicit user command) when any of these hold:

- cwd is a Helm chart (Chart.yaml with `apiVersion: v2`) that has `templates/ingress.yaml` but no `templates/*route.yaml` — candidate for add-mode.
- cwd has `templates/httproute.yaml` / `grpcroute.yaml` / `tlsroute.yaml` declaring `gateway.networking.k8s.io/v1beta1` or `v1alpha2` for resources that are now GA at `v1` — candidate for update-mode.
- cwd has `*Route` templates whose rules lack the `name` field (named rules are best practice since Gateway API v1.4).
- The user mentions migrating a chart from Ingress to Gateway API, adding HTTPRoute/GRPCRoute/TLSRoute support, "gwapi", or modernizing existing routes.

Do not invoke when:

- The chart already has current-spec routes with nothing to modernize.
- cwd is not a Helm chart (no `Chart.yaml` with `apiVersion: v2`).
- The scope is a standalone Kubernetes manifest, not a Helm chart.
- The user is working on an unrelated task — do not interrupt.

## Arguments

Parse `$ARGUMENTS`:

- First positional = `chart-path`. Default: `cwd`.
- `--type=<list>` — comma-separated subset of `httproute,grpcroute,tlsroute,tcproute,udproute`, or `auto` (default). Controls which route kinds to add (add-mode) or update (update-mode).
- `--mode=add|update|auto` — default `auto`. See Phase 3.
- `--with-backend-tls` — also generate `BackendTLSPolicy` for the chart's Service (useful when the backend Service terminates TLS itself).

## Phase 1 — Locate and validate the chart

1. Resolve `chart-path`. If not provided, walk upward from cwd looking for a directory that contains `Chart.yaml`. If multiple `Chart.yaml` files exist under `charts/*` (umbrella chart), ask the user via AskUserQuestion which chart to operate on; multi-select is allowed — process each selected chart independently.
2. Read `Chart.yaml`. Require `apiVersion: v2`. Capture chart `name` and `version`.
3. Inventory `templates/`:
   - note which of these exist: `ingress.yaml`, `service.yaml`, `deployment.yaml`, `statefulset.yaml`, `_helpers.tpl`
   - note which route templates already exist: `httproute.yaml`, `grpcroute.yaml`, `tlsroute.yaml`, `tcproute.yaml`, `udproute.yaml`, `backendtlspolicy.yaml`
4. Note whether `tests/` exists (used in Phase 8 to decide whether to add helm-unittest tests).
5. Parse `values.yaml`:
   - extract the `ingress:` block — record its indent style (2 vs 4 spaces), field naming (`host` vs `hostname`, `path` vs `paths`, `className` style), whether helm-docs `# -- description` comments are used, and the values of any CORS/auth/rate-limit annotations (these are migration targets in update-mode)
   - extract the `service:` block — port number, port name, `protocol`, `appProtocol`, type
   - detect any existing `httpRoute:`, `grpcRoute:`, `tlsRoute:`, `tcpRoute:`, `udpRoute:` top-level blocks (flat style is canonical; if a chart already uses a nested `gateway:` block, preserve its structure in update-mode rather than flattening)
6. Read `_helpers.tpl`. Extract the exact helper template names the chart defines — typically `<chart>.fullname`, `<chart>.labels`, `<chart>.selectorLabels`, `<chart>.serviceAccountName`. Use the actual names in generated templates; do not assume the prefix matches the directory name.

## Phase 2 — Verify current Gateway API spec

Training data is frequently outdated on API maturity. Before generating any template, fetch fresh data via WebFetch — do not rely on memory or prior conversation.

Fetch:

- <https://gateway-api.sigs.k8s.io/concepts/versioning/> — canonical maturity table.
- <https://kubernetes.io/blog/> — search for the latest Gateway API release post.

Build a fresh status table covering every resource this skill generates: HTTPRoute, GRPCRoute, TLSRoute, TCPRoute, UDPRoute, BackendTLSPolicy, ReferenceGrant. Record the current apiVersion and channel (Standard / Experimental) for each.

Carry that table into Phase 10 (Report). Every run must include a line like:

```text
Verified via WebFetch at <ISO8601 timestamp>: HTTPRoute=v1 (Standard), GRPCRoute=v1 (Standard), ...
```

This forces the model to actually perform the fetch rather than reuse cached claims.

**Minimum cluster Gateway API version required per route kind** — this is a separate question from current apiVersion and changes much less often. As a reference (still verify via the versioning page in case of controller-specific caveats; dates are omitted because they date-drift and the version number alone is enough to gate on):

| Route kind / feature | Min Gateway API version |
| --- | --- |
| HTTPRoute | v1.0 |
| GRPCRoute | v1.1 |
| HTTPRoute timeouts | v1.2 |
| BackendTLSPolicy | v1.4 |
| Named rules on HTTPRoute/GRPCRoute | v1.4 |
| CORS filter in Standard channel | v1.5 |
| TLSRoute | v1.5 |
| TCPRoute / UDPRoute | Experimental (no GA yet) |

Surface the relevant minimum version(s) in Phase 10's PR body so users can gate on controller support.

## Phase 3 — Determine mode (add vs update)

If `--mode` is given, use it and apply it to every selected route kind uniformly.

Otherwise, `--mode=auto` is resolved **per route kind**, not per chart:

- For each route kind selected in Phase 4, check whether the corresponding `templates/<kind>.yaml` exists.
- If it does not exist → that kind is in **add-mode**.
- If it exists → that kind is in **update-mode**.

This handles the common mixed case where a chart already has `httproute.yaml` and the user wants to add a brand-new `grpcroute.yaml` at the same time: HTTPRoute gets update-mode review, GRPCRoute gets add-mode generation.

In the rest of this document, references to "add-mode" and "update-mode" are per-kind decisions.

In **update-mode**, for each existing `*route.yaml`:

1. Render it with `helm template <chart-path>` using default values (and, if the route is gated by `enabled`, with `--set <route>.enabled=true` plus minimal required fields) to get the effective YAML.
2. Compare against the current-spec checklist:
   - apiVersion — per-kind judgement, not a blanket rule:
     - HTTPRoute `v1beta1` still coexists with `v1` in the Standard channel (v1beta1 was not removed at v1 GA). Bumping it silently breaks compatibility with controllers that only serve v1beta1. **Do not auto-bump HTTPRoute v1beta1 → v1; ask the user.**
     - GRPCRoute `v1alpha2` / `v1beta1` → `v1` is a safe bump where v1 is available (graduated v1.1). Treat as safe.
     - TLSRoute `v1alpha2` → `v1` is **not always safe**: v1 tightens `rules` to `MaxItems=1` and makes `hostnames` `+required`. Before proposing the bump, parse the existing template: if it produces more than one rule or no hostnames, mark the bump as **unsafe** and require interactive confirmation. Otherwise safe.
     - TCPRoute / UDPRoute — still `v1alpha2`; no bump to propose.
   - does each `rules[]` entry have a `name` field? (v1.4+ best practice)
   - are CORS/auth/rate-limit headers implemented via ingress-style annotations rather than typed `filters`?
   - is there an HTTPS backend port (443, `appProtocol: https`, `name: https`) but no `BackendTLSPolicy`?
3. Build a list of discrepancies.

Show the discrepancy list to the user via AskUserQuestion (multiSelect, all pre-selected) and apply the selected ones.

Classify discrepancies into **safe** (applied silently in proactive runs) and **unsafe** (require interactive confirmation):

- safe: bump apiVersion for GA resources; add `name: default` to unnamed rules; add obvious helm-docs comment fixes.
- unsafe: migrate CORS from annotations to filters (changes the chart's public surface); add a new `BackendTLSPolicy` template (introduces a new resource with external dependencies like CA ConfigMaps); remove deprecated fields.

If the skill was invoked proactively (Claude's own decision, not the user's explicit command), only apply safe discrepancies. For unsafe ones, stop and report: "found unsafe migrations — run this skill interactively to review them".

In **add-mode**, skip the discrepancy analysis.

## Phase 4 — Determine route type(s) (add-mode only)

If `--type` is explicit, use it. Otherwise infer from Service ports captured in Phase 1:

From lexfrei/ccc, BSD-3-Clause.

More from lexfrei/ccc