TAK-OS Ingress Gateway API guide

The optional Gateway controller translates GatewayClass, Gateway, and HTTPRoute v1 resources into the same proxy used for Ingress. Administrators own the GatewayClass and shared Gateway; application owners attach HTTPRoutes to the listeners they are permitted to use.

Enable Gateway API support

Install CRDs serving gateway.networking.k8s.io/v1 for GatewayClass, Gateway, and HTTPRoute. The process enables Gateway support by default when all three are discovered at startup. If they were absent, restart the controller after installing them. Use --enable-gateway-api=false to disable support explicitly.

The GatewayClass controller name must equal --gateway-controller-id, whose default is k8s.tak-os.com/gateway-controller. The shipped RBAC includes Gateway watch and status permissions and Namespace watches for listener admission.

Create an HTTP Gateway and route

This example assumes the apps namespace and the my-app Service on port 80 from the user guide. Save it as app-gateway.yaml:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: tak-os
spec:
  controllerName: k8s.tak-os.com/gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: app-gateway
  namespace: apps
spec:
  gatewayClassName: tak-os
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      hostname: app.example.com
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: apps
spec:
  parentRefs:
    - name: app-gateway
      sectionName: http
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: my-app
          port: 80

kubectl apply -f app-gateway.yaml
curl --resolve app.example.com:80:192.0.2.10 http://app.example.com/

Replace the test address with the ingress address. Creating a Gateway does not create another proxy, Service, load balancer, or external IP; it configures the existing controller's shared listeners. An HTTPRoute backend port is a numeric Service port.

HTTPS and redirects

Create a TLS Secret such as app-tls in the Gateway namespace, then add this listener to the Gateway:

spec:
  listeners:
    # Retain the HTTP listener if HTTP access or redirects are needed.
    - name: https
      port: 443
      protocol: HTTPS
      hostname: app.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: app-tls

An HTTPS listener requires exactly one same-namespace Secret reference with a valid tls.crt/tls.key pair. Provision it separately or use a cert-manager Certificate. TAK-OS does not issue a Certificate from Gateway annotations. Secret creation, update, and deletion refresh the affected routes. An invalid certificate reference prevents installation of that listener's routes.

To serve the application over HTTPS, change the application HTTPRoute's parentRefs[].sectionName to https. HTTP and HTTPS attachments are isolated. An HTTPS-only HTTPRoute does not automatically serve or redirect HTTP.

For an explicit HTTP-to-HTTPS redirect, keep the HTTP listener and create a separate HTTPRoute attached to sectionName: http, with the same hostname and this rule:

spec:
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

A redirect rule has no backendRefs. Alternatively, the ssl-redirect annotation is honored as an override for Gateway routes attached to HTTP. Its default for Gateway routes is off.

Control route attachment

Listener hostname and HTTPRoute hostnames must intersect. Parent references can select a listener by sectionName and/or port. Allowed route kinds must admit HTTPRoute. Listener namespace admission defaults to Same and supports All and Selector; namespace label changes trigger reevaluation.

For a route in another namespace, set parentRefs[].namespace to the Gateway namespace and configure the Gateway listener to admit that route namespace. Backend Services and OAuth/Basic Secrets remain in the HTTPRoute namespace. TLS certificate Secrets remain in the Gateway namespace. Cross-namespace backend and certificate references are rejected; ReferenceGrant authorization is not implemented.

Set authentication and proxy annotations on the HTTPRoute, including k8s.tak-os.com/oauth2-secret for built-in OIDC. Gateway and GatewayClass annotations are not substitutes for route annotations.

Supported routing features

Feature	Support
Hostnames	Exact and wildcard listener/route hostname intersection
Paths	`Exact` and segment-based `PathPrefix`; omitted matches default to `/`
Headers	Exact matching; header names are case insensitive and values are exact
Multiple matches	OR across `matches` entries; requirements within one match are combined
Backend selection	Weighted same-namespace Services using numeric Service ports; omitted weight is 1
Request headers	`RequestHeaderModifier` set/add/remove; multiple modifiers merge in order
Redirects	`RequestRedirect` hostname, statusCode, and scheme; no path or port rewrite
TLS	HTTPS termination on port 443; one same-namespace Secret per listener
Listeners	HTTP on 80 and HTTPS on 443

Method, query parameter, and regex matches are unsupported. Unsupported matches are skipped; if every explicit match is unsupported, no route is installed for that rule. Do not assume it becomes a catch-all. Unsupported filters include URLRewrite, ResponseHeaderModifier, RequestMirror, and ExtensionRef.

Gateway API timeout fields, retries, session persistence, TLSRoute, passthrough, and re-encryption are unsupported. Use the supported timeout annotations for backend timeouts. These limits mean support for selected Core features does not establish full Gateway API conformance.

Verify attachment

kubectl get gatewayclass tak-os -o yaml
kubectl -n apps get gateway app-gateway -o yaml
kubectl -n apps get httproute my-app -o yaml
kubectl -n apps describe gateway app-gateway
kubectl -n apps describe httproute my-app

Inspect the controller's status conditions:

Resource	Conditions to inspect
GatewayClass	`Accepted=True` for a matching controller name
Gateway	`Accepted=True`; `Programmed=True` when at least one listener is programmed
Listener	`Accepted`, `Programmed`, `ResolvedRefs`, and `attachedRoutes`
HTTPRoute parent	`Accepted` and `ResolvedRefs` for each parent attachment

Common reasons include NoMatchingParent, BackendNotFound, InvalidKind, RefNotPermitted, UnsupportedValue, InvalidCertificateRef, PortUnavailable, and UnsupportedProtocol. Status reconciliation is best effort and preserves other controllers' entries. Confirm the actual request path as well as status.

Route overlap

Ingress and Gateway resources share a route table. When host and path specificity are equal, a protocol-specific Gateway route takes precedence over an Ingress route. Other Ingress routes can still handle traffic not matched by the Gateway route's scheme. Avoid overlapping ownership during migration, and verify HTTP and HTTPS independently before removing the old Ingress.