graph

Documentation

Overview

Package graph translates the cluster state (Gateway API and Kubernetes resources) into a graph-like representation, for which: - Resources are validated. For example, if a Gateway listener is invalid, the graph representation will reflect that. - Connections between resources are found. For example, if an HTTPRoute attaches to a Gateway, the graph representation reflects that. - Any validation or connections-related errors are captured.

Those three points make it easier to generate intermediate data plane configuration and statuses for resources.

The package includes the types to represent the graph and the functions to convert resources into their graph representation.

The validation of the resource fields consists of two parts: - Data-plane specific validation. For example, validating the value of an HTTP header. Such validation is delegated to the data-plane specific implementation of a Validator. - Data-plane agnostic validation. For such validation, the values either don't affect the data-plane configuration directly or they must be validated to process a resource. For example, hostnames must be validated to be able to bind an HTTPRoute to a Listener.

Index

• type BackendGroup
  • func (bg *BackendGroup) GroupName() string
• type BackendRef
• type ClusterState
• type Gateway
• type GatewayClass
• type Graph
  • func BuildGraph(state ClusterState, controllerName string, gcName string, ...) *Graph
• type Listener
• type ParentRef
• type ParentRefAttachmentStatus
• type Route
  • func (r *Route) GetAllBackendGroups() []BackendGroup
• type Rule

Types

type BackendGroup

type BackendGroup struct {
	Source   types.NamespacedName
	Backends []BackendRef
	RuleIdx  int
}

BackendGroup represents a group of backends for a rule in an HTTPRoute.

func (*BackendGroup) GroupName

func (bg *BackendGroup) GroupName() string

GroupName returns the name of the backend group. This name must be unique across all HTTPRoutes and all rules within the same HTTPRoute. The RuleIdx is used to make the name unique across all rules within the same HTTPRoute. The RuleIdx may change for a given rule if an update is made to the HTTPRoute, but it will always match the index of the rule in the stored HTTPRoute.

type BackendRef

type BackendRef struct {
	Svc    *v1.Service
	Name   string
	Port   int32
	Weight int32
	Valid  bool
}

BackendRef is an internal representation of a backendRef in an HTTPRoute.

type ClusterState

type ClusterState struct {
	GatewayClasses map[types.NamespacedName]*v1beta1.GatewayClass
	Gateways       map[types.NamespacedName]*v1beta1.Gateway
	HTTPRoutes     map[types.NamespacedName]*v1beta1.HTTPRoute
	Services       map[types.NamespacedName]*v1.Service
}

ClusterState includes cluster resources necessary to build the Graph.

type Gateway

type Gateway struct {
	// Source is the corresponding Gateway resource.
	Source *v1beta1.Gateway
	// Listeners include the listeners of the Gateway.
	Listeners map[string]*Listener
}

Gateway represents the winning Gateway resource.

type GatewayClass

type GatewayClass struct {
	// Source is the source resource.
	Source *v1beta1.GatewayClass
	// Conditions include Conditions for the GatewayClass.
	Conditions []conditions.Condition
	// Valid shows whether the GatewayClass is valid.
	Valid bool
}

GatewayClass represents the GatewayClass resource.

type Graph

type Graph struct {
	// GatewayClass holds the GatewayClass resource.
	GatewayClass *GatewayClass
	// Gateway holds the winning Gateway resource.
	Gateway *Gateway
	// IgnoredGateways holds the ignored Gateway resources, which belong to the NGINX Gateway (based on the
	// GatewayClassName field of the resource) but ignored. It doesn't hold the Gateway resources that do not belong to
	// the NGINX Gateway.
	IgnoredGateways map[types.NamespacedName]*v1beta1.Gateway
	// Routes holds Route resources.
	Routes map[types.NamespacedName]*Route
}

Graph is a Graph-like representation of Gateway API resources.

func BuildGraph

func BuildGraph(
	state ClusterState,
	controllerName string,
	gcName string,
	secretMemoryMgr secrets.SecretDiskMemoryManager,
	validators validation.Validators,
) *Graph

BuildGraph builds a Graph from a state.

type Listener

type Listener struct {
	// Source holds the source of the Listener from the Gateway resource.
	Source v1beta1.Listener
	// Routes holds the routes attached to the Listener.
	// Only valid routes are attached.
	Routes map[types.NamespacedName]*Route
	// AcceptedHostnames is an intersection between the hostnames supported by the Listener and the hostnames
	// from the attached routes.
	AcceptedHostnames map[string]struct{}
	// SecretPath is the path to the secret on disk.
	SecretPath string
	// Conditions holds the conditions of the Listener.
	Conditions []conditions.Condition
	// Valid shows whether the Listener is valid.
	// A Listener is considered valid if NKG can generate valid NGINX configuration for it.
	Valid bool
}

Listener represents a Listener of the Gateway resource. FIXME(pleshakov) For now, we only support HTTP and HTTPS listeners.

type ParentRef

type ParentRef struct {
	// Attachment is the attachment status of the ParentRef. It could be nil. In that case, NGK didn't attempt to
	// attach because of problems with the Route.
	Attachment *ParentRefAttachmentStatus
	// Gateway is the NamespacedName of the referenced Gateway
	Gateway types.NamespacedName
	// Idx is the index of the corresponding ParentReference in the HTTPRoute.
	Idx int
}

ParentRef describes a reference to a parent in an HTTPRoute.

type ParentRefAttachmentStatus

type ParentRefAttachmentStatus struct {
	// FailedCondition is the condition that describes why the ParentRef is not attached to the Gateway. It is set
	// when Attached is false.
	FailedCondition conditions.Condition
	// Attached indicates if the ParentRef is attached to the Gateway.
	Attached bool
}

ParentRefAttachmentStatus describes the attachment status of a ParentRef.

type Route

type Route struct {
	// Source is the source resource of the Route.
	// FIXME(pleshakov)
	// For now, we assume that the source is only HTTPRoute.
	// Later we can support more types - TLSRoute, TCPRoute and UDPRoute.
	Source *v1beta1.HTTPRoute
	// ParentRefs includes ParentRefs with NKG Gateways only.
	ParentRefs []ParentRef
	// Conditions include Conditions for the HTTPRoute.
	Conditions []conditions.Condition
	// Rules include Rules for the HTTPRoute. Each Rule[i] corresponds to the ith HTTPRouteRule.
	// If the Route is invalid, this field is nil
	Rules []Rule
	// Valid tells if the Route is valid.
	// If it is invalid, NGK should not generate any configuration for it.
	Valid bool
}

Route represents an HTTPRoute.

func (*Route) GetAllBackendGroups

func (r *Route) GetAllBackendGroups() []BackendGroup

GetAllBackendGroups returns BackendGroups for all rules with valid matches and filters in the Route.

FIXME(pleshakov) Improve the name once https://github.com/nginxinc/nginx-kubernetes-gateway/issues/468 is implemented. The current name doesn't reflect the filtering of rules inside the loops. See also the discussion below for more context: https://github.com/nginxinc/nginx-kubernetes-gateway/pull/455#discussion_r1136277589

type Rule

type Rule struct {
	// BackendGroup is the BackendGroup of the rule.
	BackendGroup BackendGroup
	// ValidMatches indicates whether the matches of the rule are valid.
	// If the matches are invalid, NGK should not generate any configuration for the rule.
	ValidMatches bool
	// ValidFilters indicates whether the filters of the rule are valid.
	// If the filters are invalid, the data-plane should return 500 error provided that the matches are valid.
	ValidFilters bool
}

Rule represents a rule of an HTTPRoute.