Kubernetes Ingress Spec Structure

Kubernetes Ingress Spec Structure describes the precise schema of the spec field within an Ingress resource, the nested fields it is composed of, and how those fields combine to express a complete set of routing rules for a single object.

Top-Level Spec Fields

ingressClassName

This field holds a string referencing the IngressClass responsible for implementing the resource. Its presence at the top level of the spec, rather than as an annotation, reflects its status as a first-class, schema-validated field in the current stable version of the API, replacing an earlier annotation-based convention.

defaultBackend

This optional field defines a fallback Service and port used to handle any request that does not match any rule in the rules list. It follows the same backend structure used within individual rules, referencing a Service name and either a named or numeric port.

tls

This field holds a list of TLS configuration blocks, each specifying a set of hosts the block applies to and a Secret name containing the corresponding certificate and private key, allowing a single Ingress to serve multiple TLS configurations for different host groups.

The Rules Array

Rule-Level Host Field

Each entry in the rules array may specify an optional host field, a fully qualified domain name that the rule applies to. Omitting the host field creates a rule that matches any host, commonly used as a catch-all within a namespace that only serves one application.

HTTP Block Within Each Rule

Nested within each rule is an http block containing a paths array, since the current stable Ingress API version only formally supports HTTP-based routing rules at this structural level, despite the broader conceptual scope sometimes associated with Ingress.

Path Entry Structure

path and pathType Fields

Each entry in the paths array declares a path string to match and a pathType, which determines how that string is interpreted, Exact for a literal full match, Prefix for matching any request path beginning with the given segment, or ImplementationSpecific for controller-defined matching behavior.

Backend Reference Within a Path

Each path entry includes a backend field structured identically to the top-level default backend, referencing a Service by name and specifying either a number or name for the target port, since Services can expose multiple named ports and the Ingress must disambiguate which one traffic should be forwarded to.

Resource Backend Alternative

Non-Service Backend Targets

The backend structure also supports a resource field as an alternative to a Service reference, allowing an Ingress path to point at a different kind of backend object entirely, such as a storage bucket abstraction, provided the target Ingress controller implements support for that resource type.

Status Subresource

Load Balancer Address Reporting

Separate from the spec, the Ingress resource's status field is populated by the controller implementing it, reporting the external IP addresses or hostnames through which the Ingress is actually reachable, giving API consumers a way to discover the live entry point without needing separate knowledge of the controller's own exposure mechanism.