Kubernetes Ingress and Gateway Guidelines

Kubernetes Ingress and Gateway Guidelines describe the practices for routing external HTTP(S) and other Layer 7 traffic into a cluster using the Ingress resource and its successor, the Gateway API, so that many backend Services can share a small, consistently managed set of external entry points instead of each provisioning its own dedicated load balancer. These guidelines cover choosing between Ingress and Gateway API, structuring routing rules safely, TLS management, and the operational practices that keep a shared entry point from becoming a single point of failure or a source of routing ambiguity.

Ingress vs. Gateway API

The Ingress Resource

Ingress provides host- and path-based HTTP routing to backend Services through a set of rules interpreted by an Ingress controller. It has been the standard mechanism for years, but its API is deliberately minimal, pushing controller-specific behavior (rewrite rules, rate limiting, canary weighting) into vendor-specific annotations that are not portable across controllers.

The Gateway API

The Gateway API is a more expressive, role-oriented successor that separates infrastructure provisioning (GatewayClass, Gateway) from routing configuration (HTTPRoute, GRPCRoute, and others), and standardizes capabilities that Ingress could only express through annotations — weighted traffic splitting, header-based matching, and cross-namespace routing with explicit permission. New deployments should generally default to the Gateway API where the cluster's controller supports it, reserving Ingress for compatibility with existing tooling or controllers that haven't yet adopted Gateway API.

Controller Choice Determines Available Behavior

Both Ingress and Gateway API are specifications implemented by a controller (such as an NGINX-, Envoy-, or cloud-provider-based implementation); the actual routing, TLS, and traffic-shaping capabilities available depend entirely on which controller is installed, and evaluating that controller's feature set against actual routing requirements is a prerequisite to designing correct routing rules.

Routing Rule Design

Explicit Path and Host Matching

Routing rules should specify exact, intentional host and path matches rather than overly broad catch-all rules, since ambiguous or overlapping rules across multiple Ingress/HTTPRoute objects can produce routing behavior that depends on undocumented tie-breaking logic in the specific controller implementation.

Path Type Precision

For Ingress, pathType: Exact or Prefix should be chosen deliberately rather than left to the controller's default interpretation — Prefix matching with an insufficiently specific prefix can unintentionally capture requests meant for a different backend.

Cross-Namespace Routing Requires Explicit Permission

Gateway API's ReferenceGrant mechanism requires the target namespace to explicitly opt in before a Gateway in another namespace can route to Services within it, preventing a shared, centrally-managed Gateway from silently gaining the ability to route to arbitrary workloads without the owning team's consent.

TLS and Certificate Management

Centralized TLS Termination

Terminating TLS at the ingress/gateway layer, rather than at each individual backend, centralizes certificate management and reduces the number of places private keys need to be stored and rotated. Backend traffic behind the ingress layer should still be encrypted when it crosses a trust boundary, even though the client-facing TLS session terminates earlier.

Automated Certificate Issuance

Certificates should be issued and renewed automatically (via an ACME-based controller or equivalent), referenced by Ingress/Gateway resources rather than manually uploaded and tracked, since manual certificate rotation is one of the most common causes of preventable outages from expired certificates.

Minimum TLS Version and Cipher Policy

The minimum accepted TLS version and cipher suite set should be configured explicitly at the ingress/gateway layer rather than left at controller defaults, ensuring the cluster's actual security posture reflects a deliberate decision rather than whatever the controller happened to ship with.

Traffic Shaping and Progressive Delivery

Weighted Traffic Splitting

Both HTTPRoute (natively) and Ingress controllers (via annotations) support splitting traffic across multiple backend Services by weight, which is the mechanism underlying canary releases — routing a small percentage of real traffic to a new version before committing the full rollout to it.

Rate Limiting and Request Validation at the Edge

Applying rate limiting, request size limits, and basic request validation at the ingress/gateway layer protects backend workloads from abusive or malformed traffic before it ever reaches application code, and centralizes a control that would otherwise need to be duplicated in every backend service.

Availability of the Entry Point Itself

The Gateway Layer Is a Shared Point of Failure

Because many backend Services typically route through a small number of Gateway/Ingress controller replicas, that layer must itself be run with multiple replicas, spread across failure domains, and protected by the same resource, health check, and disruption budget guidelines applied to any other critical service — an outage in the ingress layer takes down every backend behind it simultaneously, regardless of how healthy those backends are.

Observability at the Edge

Because all external traffic passes through this layer, it is the natural place to capture consistent request-level metrics, logs, and traces across the entire cluster's externally-facing surface, providing visibility that would otherwise require instrumenting every backend service individually.

Example Configuration

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: codartium-api-route
  namespace: codartium
spec:
  parentRefs:
    - name: shared-gateway
      namespace: gateway-system
  hostnames: ["api.codartium.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: codartium-api-stable
          port: 80
          weight: 90
        - name: codartium-api-canary
          port: 80
          weight: 10

Practical Consequences

Well-designed ingress and gateway configuration provides a consolidated, observable, and consistently secured entry point for all external traffic, with routing rules that behave predictably and TLS that never lapses unnoticed. Neglecting these guidelines commonly produces ambiguous routing conflicts between overlapping rules, expired-certificate outages from manual TLS management, or a fragile single point of failure at the edge that was never resourced or replicated to match its outsized importance to overall cluster availability.