objects

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package objects provides typed, read-only views over unstructured Gateway API and kgateway objects. It decodes only the fields the UI needs and applies the Gateway API defaults, so callers never handle raw maps.

Index

Constants

View Source
const DelegationLabelKey = "delegation.kgateway.dev/label"

DelegationLabelKey is the label a label-mode delegation ref selects on (kgateway api/labels/delegation.go:7).

View Source
const GatewayAPIGroup = "gateway.networking.k8s.io"

GatewayAPIGroup is the API group of the Gateway API.

View Source
const InheritParentMatcherAnnotation = "delegation.kgateway.dev/inherit-parent-matcher"

InheritParentMatcherAnnotation makes a delegated child inherit its parent's matcher.

Variables

This section is empty.

Functions

func Conditions

func Conditions(u *unstructured.Unstructured) []metav1.Condition

Conditions returns status.conditions.

func ControllerName

func ControllerName(gatewayClass *unstructured.Unstructured) string

ControllerName returns spec.controllerName of a GatewayClass.

func FindCondition

func FindCondition(cs []metav1.Condition, typ string) *metav1.Condition

FindCondition returns the condition of type typ, or nil.

func GatewayAddresses

func GatewayAddresses(u *unstructured.Unstructured) []string

GatewayAddresses returns the values of status.addresses.

func GatewayClassName

func GatewayClassName(u *unstructured.Unstructured) string

GatewayClassName returns spec.gatewayClassName of a Gateway.

func GatewaySpecListeners

func GatewaySpecListeners(u *unstructured.Unstructured) []string

GatewaySpecListeners returns the names in a Gateway's spec.listeners.

func IsStale

IsStale reports whether c may describe an older generation of u than the current spec. A condition without observedGeneration (0) gives no evidence that it is current, so it counts as stale.

Types

type AllowedRoutes

type AllowedRoutes struct {
	Namespaces RouteNamespaces
	Kinds      []GroupKind
}

AllowedRoutes is a listener's allowedRoutes.

type AncestorStatus

type AncestorStatus struct {
	AncestorRef    ParentRef
	ControllerName string
	Conditions     []metav1.Condition
}

AncestorStatus is one entry of a policy's status.ancestors.

func PolicyAncestors

func PolicyAncestors(u *unstructured.Unstructured) []AncestorStatus

PolicyAncestors returns status.ancestors with defaults applied.

type BackendRef

type BackendRef struct {
	Ref             Ref
	Port            int32
	Weight          int32
	WeightDefaulted bool
	Filters         []Filter
	// Delegation is set when the ref delegates to child routes.
	Delegation *DelegationRef
}

BackendRef is one rule backendRef. Kind defaults to Service and Namespace to the route's. An absent weight is 1 with WeightDefaulted set; an absent port is 0.

type BackendTarget

type BackendTarget struct {
	Ref    Ref
	Mirror bool
}

BackendTarget is a backend a route sends or mirrors traffic to.

func BackendTargets

func BackendTargets(v *HTTPRouteView) []BackendTarget

BackendTargets returns every non-delegation backendRef and every RequestMirror target of v, in the order written. A delegation ref's filters become policies on its children and send no traffic, so they are skipped.

func BackendTargetsAs added in v0.6.0

func BackendTargetsAs(v *HTTPRouteView, delegates bool) []BackendTarget

BackendTargetsAs is BackendTargets for a controller that delegates or not. Without delegation every backendRef is an ordinary target, filters included.

func RouteBackendTargets

func RouteBackendTargets(u *unstructured.Unstructured) []BackendTarget

RouteBackendTargets returns the spec.rules[].backendRefs and RequestMirror targets of any route kind (GRPCRoute, TCPRoute, TLSRoute), with Gateway API defaults applied. Use BackendTargets for a decoded HTTPRoute. It never fails.

type BackendView

type BackendView struct {
	Type       string
	Conditions []metav1.Condition
}

BackendView is the decoded kgateway Backend.

func DecodeBackend

func DecodeBackend(u *unstructured.Unstructured) *BackendView

DecodeBackend decodes a kgateway Backend. It never fails.

type Consumer added in v0.7.0

type Consumer struct {
	Consumer   Ref
	Role       string
	BackendRef Ref
	// Port is the written backendRef port, 0 when unset.
	Port  int
	Field string
}

Consumer is a non-route object that names a backend, with the role it uses the backend in and the JSON path of the reference.

type Decoder

Decoder decodes typed views. Implementations may cache.

type DelegationMode

type DelegationMode string

DelegationMode is how a delegation backendRef selects child routes.

const (
	DelegationName     DelegationMode = "name"
	DelegationWildcard DelegationMode = "wildcard"
	DelegationLabel    DelegationMode = "label"
)

Delegation modes (computed-rules §3.2).

type DelegationRef

type DelegationRef struct {
	Mode      DelegationMode
	Namespace string
	Name      string
	Label     string
}

DelegationRef is a delegation backendRef. Namespace defaults to the parent route's; Name is set in name mode and Label in label mode.

type Direct

type Direct struct{}

Direct is a Decoder that decodes on every call.

func (Direct) Backend

Backend decodes u with DecodeBackend.

func (Direct) Gateway

Gateway decodes u with DecodeGateway.

func (Direct) HTTPRoute

HTTPRoute decodes u with DecodeHTTPRoute.

func (Direct) ListenerSet

ListenerSet decodes u with DecodeListenerSet.

func (Direct) Route

Route decodes u with DecodeRoute.

func (Direct) RouteHostnames

func (Direct) RouteHostnames(u *unstructured.Unstructured) *RouteHostnames

RouteHostnames decodes u with DecodeRouteHostnames.

type Filter

type Filter struct {
	Type         string
	ExtensionRef *Ref
	Mirror       *MirrorFilter
	Config       map[string]any
}

Filter is one HTTPRouteFilter. Config is the filter as written.

type Fraction

type Fraction struct {
	Numerator, Denominator int32
}

Fraction is a mirror fraction; Denominator defaults to 100.

type GRPCMatch added in v0.7.0

type GRPCMatch struct {
	Method  *GRPCMethodMatch
	Headers []KeyMatch
}

GRPCMatch is one GRPCRouteMatch.

type GRPCMethodMatch added in v0.7.0

type GRPCMethodMatch struct {
	Type, Service, Method string
}

GRPCMethodMatch is a GRPCRoute method match; Type defaults to Exact.

type GatewayView

type GatewayView struct {
	Class                string
	Listeners            []Listener
	SpecAddresses        []string
	StatusAddresses      []string
	AttachedListenerSets *int32
	// AllowedListeners is spec.allowedListeners as written, nil when absent.
	AllowedListeners map[string]any
	Conditions       []metav1.Condition
	ListenerStatus   []ListenerStatus
}

GatewayView is the decoded spec and status of a Gateway.

func DecodeGateway

func DecodeGateway(u *unstructured.Unstructured) *GatewayView

DecodeGateway decodes a Gateway. It never fails.

type GroupKind

type GroupKind struct {
	Group string `json:"group"`
	Kind  string `json:"kind"`
}

GroupKind is an API group and kind.

type HTTPRouteView

type HTTPRouteView struct {
	Hostnames []string
	// ParentRefs are spec.parentRefs resolved; WrittenRefs are the same refs
	// as written, index-aligned.
	ParentRefs           []ParentRef
	WrittenRefs          []WrittenRef
	Rules                []Rule
	Parents              []RouteParentStatus
	Labels               map[string]string
	InheritParentMatcher bool
}

HTTPRouteView is the decoded spec and status of an HTTPRoute.

func DecodeHTTPRoute

func DecodeHTTPRoute(u *unstructured.Unstructured) *HTTPRouteView

DecodeHTTPRoute decodes an HTTPRoute. It never fails.

type KeyMatch

type KeyMatch struct {
	Type, Name, Value string
}

KeyMatch is a header or query parameter match; Type defaults to Exact.

type Listener

type Listener struct {
	Name string
	// Port is 0 when unset.
	Port          int32
	Protocol      string
	Hostname      string
	TLS           *ListenerTLS
	AllowedRoutes AllowedRoutes
}

Listener is a spec listener of a Gateway or ListenerSet with defaults applied.

type ListenerSetView

type ListenerSetView struct {
	Parent         ParentRef
	Listeners      []Listener
	Conditions     []metav1.Condition
	ListenerStatus []ListenerStatus
}

ListenerSetView is the decoded spec and status of a ListenerSet.

func DecodeListenerSet

func DecodeListenerSet(u *unstructured.Unstructured) *ListenerSetView

DecodeListenerSet decodes a ListenerSet. It never fails.

type ListenerStatus

type ListenerStatus struct {
	Name           string
	AttachedRoutes int32
	SupportedKinds []GroupKind
	Conditions     []metav1.Condition
}

ListenerStatus is one entry of a Gateway's status.listeners.

func GatewayListeners

func GatewayListeners(u *unstructured.Unstructured) []ListenerStatus

GatewayListeners returns status.listeners.

type ListenerTLS

type ListenerTLS struct {
	Mode            string
	CertificateRefs []Ref
}

ListenerTLS is a listener's TLS block. Certificate refs are identities only; they are never looked up. TLS options are not decoded.

type Match

type Match struct {
	Path        *PathMatch
	Headers     []KeyMatch
	QueryParams []KeyMatch
	Method      string
}

Match is one HTTPRouteMatch.

type MirrorFilter

type MirrorFilter struct {
	Backend  Ref
	Port     int32
	Percent  *int32
	Fraction *Fraction
}

MirrorFilter is a RequestMirror filter. Port is 0 when unset.

type ParentRef

type ParentRef struct {
	Group       string `json:"group"`
	Kind        string `json:"kind"`
	Namespace   string `json:"namespace"`
	Name        string `json:"name"`
	SectionName string `json:"sectionName,omitempty"`
	// Port is the parentRef port; 0 means unset (Gateway API ports start at 1).
	Port int32 `json:"port,omitempty"`
}

ParentRef is a Gateway API parent or ancestor reference with defaults applied.

func ListenerSetParent

func ListenerSetParent(u *unstructured.Unstructured) ParentRef

ListenerSetParent returns spec.parentRef of a ListenerSet with defaults applied.

func RouteParentRefs

func RouteParentRefs(u *unstructured.Unstructured) []ParentRef

RouteParentRefs returns spec.parentRefs with defaults applied.

func (ParentRef) Ref

func (p ParentRef) Ref() Ref

Ref returns the identity of the referenced object. Section name and port are dropped: they select a listener, not a different object.

type PathMatch

type PathMatch struct {
	Type, Value string
}

PathMatch is a path match; Type defaults to PathPrefix and Value to "/".

type Ref

type Ref struct {
	Group     string `json:"group"`
	Kind      string `json:"kind"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
}

Ref identifies an object.

func DecodeBackendRefAt added in v0.7.0

func DecodeBackendRefAt(u *unstructured.Unstructured, path ...string) (ref Ref, port int, ok bool)

DecodeBackendRefAt decodes the Gateway API backendRef object at path in u, with the core group, kind Service and u's namespace as defaults. ok is false when there is no such object or it names nothing. It never fails.

func RefOf

func RefOf(u *unstructured.Unstructured) Ref

RefOf returns the Ref of u.

func (Ref) Compare

func (r Ref) Compare(o Ref) int

Compare orders r and o by group, kind, namespace and name, stopping at the first field that differs.

func (Ref) String

func (r Ref) String() string

String returns "namespace/name", or "name" for cluster-scoped objects.

type RouteHostnames

type RouteHostnames struct {
	Hostnames []string
}

RouteHostnames holds spec.hostnames of a GRPCRoute or TLSRoute.

func DecodeRouteHostnames

func DecodeRouteHostnames(u *unstructured.Unstructured) *RouteHostnames

DecodeRouteHostnames decodes spec.hostnames of any route kind. It never fails.

type RouteNamespaces

type RouteNamespaces struct {
	From     string
	Selector *metav1.LabelSelector
}

RouteNamespaces is allowedRoutes.namespaces; From defaults to Same.

type RouteParentStatus

type RouteParentStatus struct {
	ParentRef ParentRef
	// Written is the status parentRef as written, for report keys.
	Written        WrittenRef `json:"-"`
	ControllerName string
	Conditions     []metav1.Condition
}

RouteParentStatus is one entry of a route's status.parents.

func RouteParents

func RouteParents(u *unstructured.Unstructured) []RouteParentStatus

RouteParents returns status.parents with defaults applied to each parentRef.

type RouteView

type RouteView struct {
	Hostnames  []string
	ParentRefs []ParentRef
	// WrittenRefs are ParentRefs as written, index-aligned.
	WrittenRefs []WrittenRef
	Parents     []RouteParentStatus
	Targets     []BackendTarget
}

RouteView is the decoded spec and status any route kind shares (GRPCRoute, TCPRoute, TLSRoute), for callers that do not need a full HTTPRouteView. Fields are as RouteParentRefs, RouteParents and RouteBackendTargets return them.

func DecodeRoute

func DecodeRoute(u *unstructured.Unstructured) *RouteView

DecodeRoute decodes the shared fields of any route kind in one pass. It never fails.

type Rule

type Rule struct {
	Index int
	Name  string
	// Matches is nil when omitted and empty for an explicit empty list.
	Matches []Match
	// GRPCMatches is set for a GRPCRoute only, with the same nil/empty rule.
	GRPCMatches []GRPCMatch
	Filters     []Filter
	BackendRefs []BackendRef
}

Rule is one spec.rules entry.

func DecodeRouteRules added in v0.7.0

func DecodeRouteRules(u *unstructured.Unstructured) []Rule

DecodeRouteRules decodes spec.rules of a GRPCRoute, TCPRoute or TLSRoute, with backendRefs and filters as for an HTTPRoute. Only a GRPCRoute has matches (GRPCMatches; Matches stays nil), and no ref is a delegation. It never fails.

type WrittenRef

type WrittenRef struct {
	Group, Kind, Namespace, Name, SectionName string
	// Port is the written port; PortSet reports whether one was written.
	Port    int32
	PortSet bool
}

WrittenRef is a parentRef as written: omitted fields are empty strings and no defaults are applied. It is comparable, so it serves as a report key and a persistence identity (design §4.1, computed-rules §7).

func WrittenParentRefs

func WrittenParentRefs(u *unstructured.Unstructured) []WrittenRef

WrittenParentRefs returns spec.parentRefs of any route kind as written, index-aligned with RouteParentRefs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL