Gateway API

Exam tasks: 3.4 (use the Gateway API to manage ingress traffic), with 3.5 when migrating from Ingress

The decision: which Gateway listener should accept this traffic, which namespaces may attach routes to it, and how should the HTTPRoute match and split requests across backends?

Three resources, three ownersCopy Anchor Link

• Gateway API is CRDs plus a controller, not part of core Kubernetes. Without an implementation (Envoy Gateway, Istio, Cilium, NGINX Gateway Fabric, Contour, Traefik and others) the objects are accepted and nothing listens.
• GatewayClass, Gateway, HTTPRoute and GRPCRoute are gateway.networking.k8s.io/v1 in the Standard channel. ReferenceGrant, TLSRoute and ListenerSet reached v1 in Gateway API 1.5, and TCPRoute and UDPRoute in 1.6.

k get crd | grep gateway.networking.k8s.io     # are the CRDs installed?
k get gatewayclass                              # ACCEPTED should be True
# install Standard channel CRDs (version from the task or the project's releases page)
k apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.2/standard-install.yaml

The GatewayCopy Anchor Link

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public
  namespace: gw-system
spec:
  gatewayClassName: envoy            # must match an existing GatewayClass
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "*.orbit.test"
    allowedRoutes:
      namespaces:
        from: Selector               # Same (default) | All | Selector
        selector:
          matchLabels:
            gateway-access: public
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "*.orbit.test"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: orbit-wildcard-tls     # kubernetes.io/tls Secret in gw-system
    allowedRoutes:
      namespaces:
        from: All

• allowedRoutes.namespaces.from defaults to Same: only routes in the Gateway's own namespace can attach. This is the usual reason an app team's route is ignored.
• Check k -n gw-system get gateway public: PROGRAMMED True and an ADDRESS mean the data plane is up.

The HTTPRouteCopy Anchor Link

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: atlas
  namespace: atlas
spec:
  parentRefs:
  - name: public
    namespace: gw-system
    sectionName: https              # attach to one listener only (optional)
  hostnames:
  - maps.orbit.test
  rules:
  - matches:
    - path:
        type: PathPrefix            # Exact | PathPrefix | RegularExpression
        value: /tiles
    backendRefs:
    - name: atlas-v1
      port: 8080
      weight: 90
    - name: atlas-v2
      port: 8080
      weight: 10
  - matches:
    - headers:
      - name: x-beta
        value: "on"
      path:
        type: PathPrefix
        value: /tiles               # same path as above, so the header match decides
    backendRefs:
    - name: atlas-v2
      port: 8080

• Inside one matches entry, conditions are ANDed (path and header and method). Separate entries are ORed.
• With no matches, a rule matches everything (PathPrefix /). When several rules match, the most specific wins: Exact path, then longest prefix, then more header matches, and so on.
• weight is relative: 90 and 10 send about 10% to v2. weight: 0 sends none. Omitted means 1.
• backendRefs.port is the Service port, and the Service must be in the route's namespace unless a ReferenceGrant allows otherwise.

FiltersCopy Anchor Link

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

Cross-namespace referencesCopy Anchor Link

• Route to Gateway in another namespace: the Gateway's allowedRoutes must permit the route's namespace.
• Route to a Service in another namespace, or Gateway to a Secret in another namespace: the target namespace must create a ReferenceGrant allowing it.

apiVersion: gateway.networking.k8s.io/v1   # v1beta1 before Gateway API 1.5
kind: ReferenceGrant
metadata:
  name: allow-atlas-routes
  namespace: tiles-backend          # where the Service lives
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: atlas
  to:
  - group: ""
    kind: Service

Coming from IngressCopy Anchor Link

The ingress2gateway tool converts existing Ingress objects into Gateway API resources as a starting point.

ScenariosCopy Anchor Link

DrillCopy Anchor Link

kubectl config use-context lab-gw

A Gateway API implementation and the GatewayClass envoy are installed. In namespace atlas, Services atlas-v1 and atlas-v2 listen on port 8080.

1. Create Gateway public in namespace atlas with an HTTP listener on port 80 for hostname maps.orbit.test.
2. Create HTTPRoute atlas that sends /tiles traffic 70/30 to atlas-v1 / atlas-v2, except that /tiles requests with header x-beta: on always go to atlas-v2.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public
  namespace: atlas
spec:
  gatewayClassName: envoy
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: maps.orbit.test
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: atlas
  namespace: atlas
spec:
  parentRefs:
  - name: public
  hostnames:
  - maps.orbit.test
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /tiles
    backendRefs:
    - name: atlas-v1
      port: 8080
      weight: 70
    - name: atlas-v2
      port: 8080
      weight: 30
  - matches:
    - path:
        type: PathPrefix
        value: /tiles
      headers:
      - name: x-beta
        value: "on"
    backendRefs:
    - name: atlas-v2
      port: 8080

k apply -f atlas-gw.yaml
k -n atlas get gateway public                      # PROGRAMMED True, note ADDRESS
k -n atlas get httproute atlas -o jsonpath='{.status.parents[0].conditions[*].type}{"\n"}{.status.parents[0].conditions[*].status}{"\n"}'
GW=$(k -n atlas get gateway public -o jsonpath='{.status.addresses[0].value}')
for i in $(seq 20); do curl -s -H 'Host: maps.orbit.test' http://$GW/tiles; done   # mix of v1 and v2
curl -s -H 'Host: maps.orbit.test' -H 'x-beta: on' http://$GW/tiles               # v2 every time

Further readingCopy Anchor Link

• Gateway API concepts (kubernetes.io)
• Gateway API overview
• HTTP traffic splitting
• Migrating from Ingress