Gateway — the cluster operator resource

Gateway is the resource that defines the load balancer instance. The cluster operator creates the Gateway. This lesson walks the Gateway, the listeners, and the operational discipline.

The Gateway

The Gateway is the namespaced resource that defines the load balancer instance:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: prod-app
spec:
  gatewayClassName: nginx
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        certificateRefs:
          - name: prod-tls
      allowedRoutes:
        namespaces:
          from: Same

The Gateway defines the listeners, the TLS, and the allowed routes.

flowchart LR
    A[Gateway] --> B[Listener: http:80]
    A --> C[Listener: https:443]
    B --> D[HTTP routes]
    C --> E[HTTPS routes]
    C --> F[TLS termination]

The Gateway’s listeners are the entry points for the external traffic.

The listeners

The listeners are the ports and protocols that the Gateway accepts:

listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same

The listener’s fields:

• name: the listener’s name (unique within the Gateway).
• port: the port the listener accepts.
• protocol: the protocol (HTTP, HTTPS, TCP, UDP, TLS).
• allowedRoutes: the routes that can be attached to the listener.

The allowedRoutes field restricts which routes can be attached. The cluster operator can limit the attachment to the same namespace or to specific namespaces.

The TLS configuration

The TLS configuration is per-listener:

listeners:
  - name: https
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      certificateRefs:
        - name: prod-tls
      options:
        apiVersion: networking.g8s.io/v1
        kind: EnvoyProxy
        name: prod-proxy

The TLS modes:

• Terminate: the Gateway terminates TLS; the backend receives HTTP.
• Passthrough: the Gateway forwards TLS; the backend terminates TLS.

The certificateRefs references the TLS secret.

The address assignment

The Gateway’s address is assigned by the controller:

status:
  addresses:
    - value: 1.2.3.4
      type: IPAddress
  listeners:
    - name: http
      supportedKinds:
        - group: gateway.networking.k8s.io
          kind: HTTPRoute
      attachedRoutes: 5
      conditions:
        - type: Programmed
          status: "True"

The address is the load balancer’s IP. The listener status shows the supported kinds and the number of attached routes.

The failure modes

The Gateway’s failure modes:

• GatewayClass missing: the GatewayClass is not installed. The fix is to install the GatewayClass.
• Controller missing: the controller is not installed. The fix is to install the controller.
• Listener conflict: the listener’s port is already in use. The fix is to change the port.
• TLS certificate invalid: the TLS certificate is invalid. The fix is to update the certificate.
• allowedRoutes misconfigured: the allowedRoutes is wrong. The fix is to verify the allowedRoutes.

The operational discipline

The Gateway’s operational discipline:

• Document the Gateway. The Gateway is the cluster’s HTTP gateway configuration.
• Audit the Gateway at every change. The Gateway is critical configuration.
• Test the Gateway in staging. The Gateway must work for the workload.
• Monitor the Gateway’s status. The status is the leading indicator.
• Plan the Gateway’s evolution. The Gateway can be replaced with a new controller.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The Gateway is the cluster’s HTTP gateway configuration. The cluster operator must treat it as critical configuration.
• Document the Gateway. The Gateway is the cluster’s HTTP gateway configuration.
• Audit the Gateway at every change. The Gateway is critical configuration.
• Test the Gateway in staging. The Gateway must work for the workload.
• Monitor the Gateway’s status. The status is the leading indicator.
• Plan the Gateway’s evolution. The Gateway can be replaced with a new controller.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the cluster operator on the Gateway’s diagnostics. The diagnostics are the team’s tools.
• Document the Gateway’s design. The Gateway is the cluster’s HTTP gateway; the documentation is the reference.