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

• func GetAllowedRouteLabelSelector(l v1beta1.Listener) *metav1.LabelSelector
• func GetMoreSpecificHostname(hostname1, hostname2 string) string
• type BackendRef
  • func (b BackendRef) ServicePortReference() string
• type ClusterState
• type Gateway
• type GatewayClass
• type Graph
  • func BuildGraph(state ClusterState, controllerName string, gcName string, ...) *Graph
  • func (g *Graph) IsReferenced(resourceType client.Object, nsname types.NamespacedName) bool
• type Listener
• type ParentRef
• type ParentRefAttachmentStatus
• type ProtectedPorts
• type Route
• type Rule
• type Secret

Functions

func GetAllowedRouteLabelSelector

func GetAllowedRouteLabelSelector(l v1beta1.Listener) *metav1.LabelSelector

GetAllowedRouteLabelSelector returns a listener's AllowedRoutes label selector if it exists.

func GetMoreSpecificHostname

func GetMoreSpecificHostname(hostname1, hostname2 string) string

GetMoreSpecificHostname returns the more specific hostname between the two inputs.

This function assumes that the two hostnames match each other, either: - Exactly - One as a substring of the other

Types

type BackendRef

type BackendRef struct {
	// Svc is the service referenced by the backendRef.
	Svc *v1.Service
	// Port is the port of the backendRef.
	Port int32
	// Weight is the weight of the backendRef.
	Weight int32
	// Valid indicates whether the backendRef is valid.
	Valid bool
}

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

func (BackendRef) ServicePortReference

func (b BackendRef) ServicePortReference() string

ServicePortReference returns a string representation for the service and port that is referenced by the BackendRef.

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
	Namespaces      map[types.NamespacedName]*v1.Namespace
	ReferenceGrants map[types.NamespacedName]*v1beta1.ReferenceGrant
	Secrets         map[types.NamespacedName]*v1.Secret
}

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
	// Conditions holds the conditions for the Gateway.
	Conditions []conditions.Condition
	// Valid indicates whether the Gateway Spec is valid.
	Valid bool
}

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
	// IgnoredGatewayClasses holds the ignored GatewayClass resources, which reference NGINX Gateway in the
	// controllerName, but are not configured via the NGINX Gateway CLI argument. It doesn't hold the GatewayClass
	// resources that do not belong to the NGINX Gateway.
	IgnoredGatewayClasses map[types.NamespacedName]*v1beta1.GatewayClass
	// 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
	// ReferencedSecrets includes Secrets referenced by Gateway Listeners, including invalid ones.
	// It is different from the other maps, because it includes entries for Secrets that do not exist
	// in the cluster. We need such entries so that we can query the Graph to determine if a Secret is referenced
	// by the Gateway, including the case when the Secret is newly created.
	ReferencedSecrets map[types.NamespacedName]*Secret
}

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

func BuildGraph

func BuildGraph(
	state ClusterState,
	controllerName string,
	gcName string,
	validators validation.Validators,
	protectedPorts ProtectedPorts,
) *Graph

BuildGraph builds a Graph from a state.

func (*Graph) IsReferenced

func (g *Graph) IsReferenced(resourceType client.Object, nsname types.NamespacedName) bool

IsReferenced returns true if the Graph references the resource.

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
	// AllowedRouteLabelSelector is the label selector for this Listener's allowed routes, if defined.
	AllowedRouteLabelSelector labels.Selector
	// ResolvedSecret is the namespaced name of the Secret resolved for this listener.
	// Only applicable for HTTPS listeners.
	ResolvedSecret *types.NamespacedName
	// Conditions holds the conditions of the Listener.
	Conditions []conditions.Condition
	// SupportedKinds is the list of RouteGroupKinds allowed by the listener.
	SupportedKinds []v1beta1.RouteGroupKind
	// 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. 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 {
	// AcceptedHostnames is an intersection between the hostnames supported by an attached Listener
	// and the hostnames from this Route. Key is listener name, value is list of hostnames.
	AcceptedHostnames map[string][]string
	// 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 ProtectedPorts

type ProtectedPorts map[int32]string

ProtectedPorts are the ports that may not be configured by a listener with a descriptive name of each port.

type Route

type Route struct {
	// Source is the source resource of the Route.
	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.

type Rule

type Rule struct {
	// BackendRefs is a list of BackendRefs for the rule.
	BackendRefs []BackendRef
	// 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.

type Secret

type Secret struct {
	// Source holds the actual Secret resource. Can be nil if the Secret does not exist.
	Source *apiv1.Secret
}

Secret represents a Secret resource.