graph

package
v1.6.2 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2025 License: Apache-2.0 Imports: 34 Imported by: 0

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

Constants

View Source 
const (
	FilterRequestHeaderModifier  = FilterType(v1.HTTPRouteFilterRequestHeaderModifier)
	FilterResponseHeaderModifier = FilterType(v1.HTTPRouteFilterResponseHeaderModifier)
	FilterExtensionRef           = FilterType(v1.HTTPRouteFilterExtensionRef)
	FilterRequestMirror          = FilterType(v1.HTTPRouteFilterRequestMirror)
)

The following FilterTypes are supported by GRPCRoutes and HTTPRoutes.

View Source 
const (
	FilterRequestRedirect = FilterType(v1.HTTPRouteFilterRequestRedirect)
	FilterURLRewrite      = FilterType(v1.HTTPRouteFilterURLRewrite)
)

The following FilterTypes are supported by HTTPRoutes only.

View Source 
const CAKey = "ca.crt"

Variables

This section is empty.

Functions

func ConvertGRPCMatches 

func ConvertGRPCMatches(grpcMatches []v1.GRPCRouteMatch) []v1.HTTPRouteMatch

ConvertGRPCMatches converts a GRPCMatch list to an HTTPRouteMatch list.

func GetAllowedRouteLabelSelector 

func GetAllowedRouteLabelSelector(l v1.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 {
	// BackendTLSPolicy is the BackendTLSPolicy of the Service which is referenced by the backendRef.
	BackendTLSPolicy *BackendTLSPolicy
	// SvcNsName is the NamespacedName of the Service referenced by the backendRef.
	SvcNsName types.NamespacedName
	// ServicePort is the ServicePort of the Service which is referenced by the backendRef.
	ServicePort v1.ServicePort
	// Weight is the weight of the backendRef.
	Weight int32
	// Valid indicates whether the backendRef is valid.
	// No configuration should be generated for an invalid BackendRef.
	Valid bool
}

BackendRef is an internal representation of a backendRef in an HTTP/GRPC/TLSRoute.

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 BackendTLSPolicy 

type BackendTLSPolicy struct {
	// Source is the source resource.
	Source *v1alpha3.BackendTLSPolicy
	// CaCertRef is the name of the ConfigMap that contains the CA certificate.
	CaCertRef types.NamespacedName
	// Gateway is the name of the Gateway that is being checked for this BackendTLSPolicy.
	Gateway types.NamespacedName
	// Conditions include Conditions for the BackendTLSPolicy.
	Conditions []conditions.Condition
	// Valid shows whether the BackendTLSPolicy is valid.
	Valid bool
	// IsReferenced shows whether the BackendTLSPolicy is referenced by a BackendRef.
	IsReferenced bool
	// Ignored shows whether the BackendTLSPolicy is ignored.
	Ignored bool
}

type CaCertConfigMap 

type CaCertConfigMap struct {
	// Source holds the actual ConfigMap resource. Can be nil if the ConfigMap does not exist.
	Source *apiv1.ConfigMap
	// CACert holds the actual CA Cert data.
	CACert []byte
}

CaCertConfigMap represents a ConfigMap resource that holds CA Cert data.

type ClusterState 

type ClusterState struct {
	GatewayClasses     map[types.NamespacedName]*gatewayv1.GatewayClass
	Gateways           map[types.NamespacedName]*gatewayv1.Gateway
	HTTPRoutes         map[types.NamespacedName]*gatewayv1.HTTPRoute
	TLSRoutes          map[types.NamespacedName]*v1alpha2.TLSRoute
	Services           map[types.NamespacedName]*v1.Service
	Namespaces         map[types.NamespacedName]*v1.Namespace
	ReferenceGrants    map[types.NamespacedName]*v1beta1.ReferenceGrant
	Secrets            map[types.NamespacedName]*v1.Secret
	CRDMetadata        map[types.NamespacedName]*metav1.PartialObjectMetadata
	BackendTLSPolicies map[types.NamespacedName]*v1alpha3.BackendTLSPolicy
	ConfigMaps         map[types.NamespacedName]*v1.ConfigMap
	NginxProxies       map[types.NamespacedName]*ngfAPI.NginxProxy
	GRPCRoutes         map[types.NamespacedName]*gatewayv1.GRPCRoute
	NGFPolicies        map[PolicyKey]policies.Policy
	SnippetsFilters    map[types.NamespacedName]*ngfAPI.SnippetsFilter
}

ClusterState includes cluster resources necessary to build the Graph.

type ExtensionRefFilter 

type ExtensionRefFilter struct {
	// SnippetsFilter contains the SnippetsFilter. Will be non-nil if the Ref.Kind is SnippetsFilter and the
	// SnippetsFilter exists.
	// Once we support more filters, we can extend this struct with more filter kinds.
	SnippetsFilter *SnippetsFilter
	// Valid indicates whether the filter is valid.
	Valid bool
}

ExtensionRefFilter are NGF-specific extensions to the "filter" behavior.

type Filter 

type Filter struct {
	// RequestHeaderModifier holds an HTTP Request Header Modifier filter.
	// Will be non-nil if FilterType is FilterRequestHeaderModifier.
	// Can be set on GRPCRoutes and HTTPRoutes.
	RequestHeaderModifier *v1.HTTPHeaderFilter
	// ResponseHeaderModifier holds an HTTP Response Header Modifier filter.
	// Will be non-nil if FilterType is FilterResponseHeaderModifier.
	// Can be set on GRPCRoutes and HTTPRoutes.
	ResponseHeaderModifier *v1.HTTPHeaderFilter
	// RequestRedirect holds an HTTP Request Redirect filter.
	// Will be non-nil if FilterType is FilterRequestRedirect.
	// Can be set on HTTPRoutes only.
	RequestRedirect *v1.HTTPRequestRedirectFilter
	// URLRewrite holds an HTTP URL Rewrite filter.
	// Will be non-nil if FilterType is FilterURLRewrite.
	// Can be set on HTTPRoutes only.
	URLRewrite *v1.HTTPURLRewriteFilter
	// RequestMirror holds an HTTP Request Mirror filter.
	// Will be non-nil if FilterType is FilterRequestMirror.
	// Can be set on GRPCRoutes and HTTPRoutes.
	RequestMirror *v1.HTTPRequestMirrorFilter
	// ExtensionRef holds an Extension Ref filter.
	// Will be non-nil if FilterType is FilterExtensionRef.
	// Can be set on GRPCRoutes and HTTPRoutes.
	ExtensionRef *v1.LocalObjectReference
	// ResolvedExtensionRef holds the filter that the Extension Ref points to.
	// Will be non-nil if the Extension Ref is non-nil and was resolved successfully.
	// Can be set on GRPCRoutes and HTTPRoutes.
	ResolvedExtensionRef *ExtensionRefFilter
	// RouteType is the type of Route that this filter is on.
	RouteType RouteType
	// FilterType is the type of filter.
	FilterType FilterType
}

Filter is a filter in a Route. The Filter can belong to a GRPCRoute or an HTTPRoute.

type FilterType 

type FilterType string

FilterType is the type of filter.

type Gateway 

type Gateway struct {
	// Source is the corresponding Gateway resource.
	Source *v1.Gateway
	// Listeners include the listeners of the Gateway.
	Listeners []*Listener
	// Conditions holds the conditions for the Gateway.
	Conditions []conditions.Condition
	// Policies holds the policies attached to the Gateway.
	Policies []*Policy
	// 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 *v1.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 Fabric in the
	// controllerName, but are not configured via the NGINX Gateway Fabric CLI argument. It doesn't hold the GatewayClass
	// resources that do not belong to the NGINX Gateway Fabric.
	IgnoredGatewayClasses map[types.NamespacedName]*gatewayv1.GatewayClass
	// IgnoredGateways holds the ignored Gateway resources, which belong to the NGINX Gateway Fabric (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 Fabric.
	IgnoredGateways map[types.NamespacedName]*gatewayv1.Gateway
	// Routes hold Route resources.
	Routes map[RouteKey]*L7Route
	// L4Routes hold L4Route resources.
	L4Routes map[L4RouteKey]*L4Route
	// 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
	// ReferencedNamespaces includes Namespaces with labels that match the Gateway Listener's label selector.
	ReferencedNamespaces map[types.NamespacedName]*v1.Namespace
	// ReferencedServices includes the NamespacedNames of all the Services that are referenced by at least one Route.
	ReferencedServices map[types.NamespacedName]*ReferencedService
	// ReferencedCaCertConfigMaps includes ConfigMaps that have been referenced by any BackendTLSPolicies.
	ReferencedCaCertConfigMaps map[types.NamespacedName]*CaCertConfigMap
	// BackendTLSPolicies holds BackendTLSPolicy resources.
	BackendTLSPolicies map[types.NamespacedName]*BackendTLSPolicy
	// NginxProxy holds the NginxProxy config for the GatewayClass.
	NginxProxy *NginxProxy
	// NGFPolicies holds all NGF Policies.
	NGFPolicies map[PolicyKey]*Policy
	// GlobalSettings contains global settings from the current state of the graph that may be
	// needed for policy validation or generation if certain policies rely on those global settings.
	GlobalSettings *policies.GlobalSettings
	// SnippetsFilters holds all the SnippetsFilters.
	SnippetsFilters map[types.NamespacedName]*SnippetsFilter
	// PlusSecrets holds the secrets related to NGINX Plus licensing.
	PlusSecrets map[types.NamespacedName][]PlusSecretFile
}

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

func BuildGraph 

func BuildGraph(
	state ClusterState,
	controllerName string,
	gcName string,
	plusSecrets map[types.NamespacedName][]PlusSecretFile,
	validators validation.Validators,
	protectedPorts ProtectedPorts,
) *Graph

BuildGraph builds a Graph from a state.

func (*Graph) IsNGFPolicyRelevant 

func (g *Graph) IsNGFPolicyRelevant(
	policy policies.Policy,
	gvk schema.GroupVersionKind,
	nsname types.NamespacedName,
) bool

IsNGFPolicyRelevant returns whether the NGF Policy is a part of the Graph, or targets a resource in the Graph.

func (*Graph) IsReferenced 

func (g *Graph) IsReferenced(resourceType ngftypes.ObjectType, nsname types.NamespacedName) bool

IsReferenced returns true if the Graph references the resource.

type L4Route 

type L4Route struct {
	// Source is the source Gateway API object of the Route.
	Source client.Object
	// ParentRefs describe the references to the parents in a Route.
	ParentRefs []ParentRef
	// Conditions define the conditions to be reported in the status of the Route.
	Conditions []conditions.Condition
	// Spec is the L4RouteSpec of the Route
	Spec L4RouteSpec
	// Valid indicates if the Route is valid.
	Valid bool
	// Attachable indicates if the Route is attachable to any Listener.
	Attachable bool
}

type L4RouteKey 

type L4RouteKey struct {
	// NamespacedName is the NamespacedName of the Route.
	NamespacedName types.NamespacedName
}

L4RouteKey is the unique identifier for a L4Route.

func CreateRouteKeyL4 

func CreateRouteKeyL4(obj client.Object) L4RouteKey

CreateRouteKeyL4 takes a client.Object and creates a L4RouteKey.

type L4RouteSpec 

type L4RouteSpec struct {
	// Hostnames defines a set of hostnames used to select a Route used to process the request.
	Hostnames []v1.Hostname
	// FIXME (sarthyparty): change to slice of BackendRef, as for now we are only supporting one BackendRef.
	// We will eventually support multiple BackendRef https://github.com/nginx/nginx-gateway-fabric/issues/2184
	BackendRef BackendRef
}

type L7Route 

type L7Route struct {
	// Source is the source Gateway API object of the Route.
	Source client.Object
	// RouteType is the type (http or grpc) of the Route.
	RouteType RouteType
	// Spec is the L7RouteSpec of the Route
	Spec L7RouteSpec
	// ParentRefs describe the references to the parents in a Route.
	ParentRefs []ParentRef
	// Conditions define the conditions to be reported in the status of the Route.
	Conditions []conditions.Condition
	// Policies holds the policies that are attached to the Route.
	Policies []*Policy
	// Valid indicates if the Route is valid.
	Valid bool
	// Attachable indicates if the Route is attachable to any Listener.
	Attachable bool
}

L7Route is the generic type for the layer 7 routes, HTTPRoute and GRPCRoute.

type L7RouteSpec 

type L7RouteSpec struct {
	// Hostnames defines a set of hostnames used to select a Route used to process the request.
	Hostnames []v1.Hostname
	// Rules are the list of HTTP matchers, filters and actions.
	Rules []RouteRule
}

type Listener 

type Listener struct {
	Name string
	// Source holds the source of the Listener from the Gateway resource.
	Source v1.Listener
	// Routes holds the GRPC/HTTPRoutes attached to the Listener.
	// Only valid routes are attached.
	Routes map[RouteKey]*L7Route
	// L4Routes holds the TLSRoutes attached to the Listener.
	L4Routes map[L4RouteKey]*L4Route
	// 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 []v1.RouteGroupKind
	// Valid shows whether the Listener is valid.
	// A Listener is considered valid if NGF can generate valid NGINX configuration for it.
	Valid bool
	// Attachable shows whether Routes can attach to the Listener.
	// Listener can be invalid but still attachable.
	Attachable bool
}

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

type NginxProxy 

type NginxProxy struct {
	// Source is the source resource.
	Source *ngfAPI.NginxProxy
	// ErrMsgs contains the validation errors if they exist, to be included in the GatewayClass condition.
	ErrMsgs field.ErrorList
	// Valid shows whether the NginxProxy is valid.
	Valid bool
}

NginxProxy represents the NginxProxy resource.

type ParentRef 

type ParentRef struct {
	// Attachment is the attachment status of the ParentRef. It could be nil. In that case, NGF didn't attempt to
	// attach because of problems with the Route.
	Attachment *ParentRefAttachmentStatus
	// SectionName is the name of a section within the target Gateway.
	SectionName *v1.SectionName
	// Port is the network port this Route targets.
	Port *v1.PortNumber
	// Gateway is the NamespacedName of the referenced Gateway
	Gateway types.NamespacedName
	// Idx is the index of the corresponding ParentReference in the Route.
	Idx int
}

ParentRef describes a reference to a parent in a Route.

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
	// ListenerPort is the port on the Listener that the Route is attached to.
	ListenerPort v1.PortNumber
	// Attached indicates if the ParentRef is attached to the Gateway.
	Attached bool
}

ParentRefAttachmentStatus describes the attachment status of a ParentRef.

type PlusSecretFile 

type PlusSecretFile struct {
	// FieldName is the field name within the Secret that holds the data for this file.
	FieldName string
	// Content is the content of this file.
	Content []byte
	// Type is the type of Secret file.
	Type SecretFileType
}

PlusSecretFile specifies the type and content of an NGINX Plus Secret file. A user provides the names of the various Secrets on startup, and we store this info in a map to cross-reference with the actual Secrets that exist in k8s.

type Policy 

type Policy struct {
	// Source is the corresponding Policy resource.
	Source policies.Policy
	// Ancestors is a list of ancestor objects of the Policy. Used in status.
	Ancestors []PolicyAncestor
	// TargetRefs are the resources that the Policy targets.
	TargetRefs []PolicyTargetRef
	// Conditions holds the conditions for the Policy.
	// These conditions apply to the entire Policy.
	// The conditions in the Ancestor apply only to the Policy in regard to the Ancestor.
	Conditions []conditions.Condition
	// Valid indicates whether the Policy is valid.
	Valid bool
}

Policy represents an NGF Policy.

type PolicyAncestor 

type PolicyAncestor struct {
	// Ancestor is the ancestor object.
	Ancestor v1.ParentReference
	// Conditions contains the list of conditions of the Policy in relation to the ancestor.
	Conditions []conditions.Condition
}

PolicyAncestor represents an ancestor of a Policy.

type PolicyKey 

type PolicyKey struct {
	// Nsname is the NamespacedName of the Policy.
	NsName types.NamespacedName
	// GVK is the GroupVersionKind of the Policy.
	GVK schema.GroupVersionKind
}

PolicyKey is a unique identifier for an NGF Policy.

type PolicyTargetRef 

type PolicyTargetRef struct {
	// Kind is the Kind of the object.
	Kind v1.Kind
	// Group is the Group of the object.
	Group v1.Group
	// Nsname is the NamespacedName of the object.
	Nsname types.NamespacedName
}

PolicyTargetRef represents the object that the Policy is targeting.

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 ReferencedService 

type ReferencedService struct {
	// Policies is a list of NGF Policies that target this Service.
	Policies []*Policy
}

A ReferencedService represents a Kubernetes Service that is referenced by a Route and that belongs to the winning Gateway. It does not contain the v1.Service object, because Services are resolved when building the dataplane.Configuration.

type RouteBackendRef 

type RouteBackendRef struct {
	v1.BackendRef
	Filters []any
}

RouteBackendRef is a wrapper for v1.BackendRef and any BackendRef filters from the HTTPRoute or GRPCRoute.

type RouteKey 

type RouteKey struct {
	// NamespacedName is the NamespacedName of the Route.
	NamespacedName types.NamespacedName
	// RouteType is the type of the Route.
	RouteType RouteType
}

RouteKey is the unique identifier for a L7Route.

func CreateRouteKey 

func CreateRouteKey(obj client.Object) RouteKey

CreateRouteKey takes a client.Object and creates a RouteKey.

type RouteRule 

type RouteRule struct {
	// Matches define the predicate used to match requests to a given action.
	Matches []v1.HTTPRouteMatch
	// RouteBackendRefs are a wrapper for v1.BackendRef and any BackendRef filters from the HTTPRoute or GRPCRoute.
	RouteBackendRefs []RouteBackendRef
	// BackendRefs is an internal representation of a backendRef in a Route.
	BackendRefs []BackendRef
	// Filters define processing steps that must be completed during the request or response lifecycle.
	Filters RouteRuleFilters
	// ValidMatches indicates if the matches are valid and accepted by the Route.
	ValidMatches bool
}

type RouteRuleFilters 

type RouteRuleFilters struct {
	// Filters are the filters in the RouteRule.
	Filters []Filter
	// Valid indicates if the filters are valid and accepted by the Route.
	Valid bool
}

RouteRuleFilters holds the Filters for a RouteRule.

type RouteType 

type RouteType string
const (
	// RouteTypeHTTP indicates that the RouteType of the L7Route is HTTP.
	RouteTypeHTTP RouteType = "http"
	// RouteTypeGRPC indicates that the RouteType of the L7Route is gRPC.
	RouteTypeGRPC RouteType = "grpc"
)

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.

type SecretFileType 

type SecretFileType int

SecretFileType describes the type of Secret file used for NGINX Plus. 

const (
	// PlusReportJWTToken is the file for the NGINX Plus JWT Token.
	PlusReportJWTToken SecretFileType = iota
	// PlusReportCACertificate is the file for the NGINX Instance Manager CA certificate.
	PlusReportCACertificate
	// PlusReportClientSSLCertificate is the file for the NGINX Instance Manager client certificate.
	PlusReportClientSSLCertificate
	// PlusReportClientSSLKey is the file for the NGINX Instance Manager client key.
	PlusReportClientSSLKey
)

type SnippetsFilter 

type SnippetsFilter struct {
	// Source is the SnippetsFilter.
	Source *ngfAPI.SnippetsFilter
	// Snippets stored as a map of nginx context to snippet value.
	Snippets map[ngfAPI.NginxContext]string
	// Conditions define the conditions to be reported in the status of the SnippetsFilter.
	Conditions []conditions.Condition
	// Valid indicates whether the SnippetsFilter is semantically and syntactically valid.
	Valid bool
	// Referenced indicates whether the SnippetsFilter is referenced by a Route.
	Referenced bool
}

SnippetsFilter represents a ngfAPI.SnippetsFilter.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.