translators

package
v2.12.4 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2024 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// FromResourceKindPriorityShiftBits is the highest 2 bits 45-44 used in priority field of Kong route
	// to note the kind of the resource from which the route is translated.
	// 11 - routes from Ingress.
	// 10 - routes from HTTPRoute.
	// 01 - routes from GRPCRoute.
	FromResourceKindPriorityShiftBits = 44
	// ResourceKindBitsIngress is the value of highest 2 bits for routes from ingresses.
	ResourceKindBitsIngress = 3
	// ResourceKindBitsHTTPRoute is the value of highest 2 bits for routes from HTTPRoutes.
	ResourceKindBitsHTTPRoute = 2
	// ResourceKindBitsGRPCRoute is the value of highest 2 bits for routes from GRPCRoutes.
	ResourceKindBitsGRPCRoute = 1
)
View Source 
const (
	// KongPathRegexPrefix is the reserved prefix string that instructs Kong 3.0+ to interpret a path as a regex.
	KongPathRegexPrefix = "~"

	// ControllerPathRegexPrefix is the prefix string used to indicate that the controller should treat a path as a
	// regular expression. The controller replaces this prefix with KongPathRegexPrefix when sending routes to Kong.
	ControllerPathRegexPrefix = "/~"
)
View Source 
const (
	// CatchAllHTTPExpression is the expression to match all HTTP/HTTPS requests.
	// For rules with no matches and no hostnames in its parent HTTPRoute or GRPCRoute,
	// we need to generate a "catch-all" route for the rule:
	// https://github.com/Kong/kubernetes-ingress-controller/issues/4526
	// but Kong does not allow empty expression in expression router,
	// so we define this is we need a route to match all HTTP/HTTPS requests.
	CatchAllHTTPExpression = `(net.protocol == "http") || (net.protocol == "https")`
)

Variables

View Source 
var (
	ErrRouteValidationNoRules                          = errors.New("no rules provided")
	ErrRouteValidationQueryParamMatchesUnsupported     = errors.New("query param matches are not yet supported")
	ErrRouteValidationNoMatchRulesOrHostnamesSpecified = errors.New("no match rules or hostnames specified")
	ErrRotueValidationRuleNoBackendRef                 = errors.New("no backendRefs in rule")
)

Functions

func ApplyExpressionToL4KongRoute added in v2.12.0 

func ApplyExpressionToL4KongRoute(r *kongstate.Route)

ApplyExpressionToL4KongRoute convert route flavor from traditional to expressions against protocols, snis and dest ports.

func GenerateKongExpressionRoutesFromGRPCRouteRule added in v2.10.0 

func GenerateKongExpressionRoutesFromGRPCRouteRule(grpcroute *gatewayv1alpha2.GRPCRoute, ruleNumber int) []kongstate.Route

GenerateKongExpressionRoutesFromGRPCRouteRule generates expression based kong routes from a single GRPCRouteRule.

func GenerateKongExpressionRoutesFromHTTPRouteMatches added in v2.10.0 

func GenerateKongExpressionRoutesFromHTTPRouteMatches(
	translation KongRouteTranslation,
	ingressObjectInfo util.K8sObjectInfo,
	hostnames []string,
	tags []*string,
) ([]kongstate.Route, error)

GenerateKongExpressionRoutesFromHTTPRouteMatches generates Kong routes from HTTPRouteRule pointing to a specific backend.

func GenerateKongRoutesFromGRPCRouteRule added in v2.10.0 

func GenerateKongRoutesFromGRPCRouteRule(
	grpcroute *gatewayv1alpha2.GRPCRoute,
	ruleNumber int,
	prependRegexPrefix bool,
) []kongstate.Route

func GeneratePluginsFromHTTPRouteFilters added in v2.10.0 

func GeneratePluginsFromHTTPRouteFilters(filters []gatewayv1beta1.HTTPRouteFilter, path string, tags []*string) []kong.Plugin

GeneratePluginsFromHTTPRouteFilters converts HTTPRouteFilter into Kong plugins. path is the parameter to be used by the redirect plugin, to perform redirection.

func KongExpressionRouteFromHTTPRouteMatchWithPriority added in v2.11.0 

func KongExpressionRouteFromHTTPRouteMatchWithPriority(
	httpRouteMatchWithPriority SplitHTTPRouteMatchToKongRoutePriority,
) kongstate.Route

KongExpressionRouteFromHTTPRouteMatchWithPriority translates a split HTTPRoute match into expression based kong route with assigned priority.

func KongExpressionRouteFromSplitGRPCRouteMatchWithPriority added in v2.11.0 

func KongExpressionRouteFromSplitGRPCRouteMatchWithPriority(
	matchWithPriority SplitGRPCRouteMatchToPriority,
) kongstate.Route

KongExpressionRouteFromSplitGRPCRouteMatchWithPriority generates expression based Kong route from split GRPCRoute match which contains one or no hostname, and a GRPCRoute match, with its priority is beforehand.

func KongServiceNameFromSplitGRPCRouteMatch added in v2.11.0 

func KongServiceNameFromSplitGRPCRouteMatch(match SplitGRPCRouteMatch) string

KongServiceNameFromSplitGRPCRouteMatch generates the name of translated Kong service from split GRPCRoute match with the source GRPCRoute and rule index.

func KongServiceNameFromSplitHTTPRouteMatch added in v2.11.0 

func KongServiceNameFromSplitHTTPRouteMatch(match SplitHTTPRouteMatch) string

KongServiceNameFromSplitHTTPRouteMatch generates service name from split HTTPRoute match. since one HTTPRoute may be split by hostname and rule, the service name will be generated in the format "httproute.<namespace>.<name>.<hostname>.<rule index>". For example: `httproute.default.example.foo.com.0`.

func MaybePrependRegexPrefix added in v2.10.0 

func MaybePrependRegexPrefix(path, controllerPrefix string, applyLegacyHeuristic bool) string

MaybePrependRegexPrefix takes a path, controller regex prefix, and a legacy heuristic toggle. It returns the path with the Kong regex path prefix if it either began with the controller prefix or did not, but matched the legacy heuristic, and the heuristic was enabled.

func MaybePrependRegexPrefixForIngressV1Fn added in v2.10.0 

func MaybePrependRegexPrefixForIngressV1Fn(ingress *netv1.Ingress, applyLegacyHeuristic bool) func(path string) *string

MaybePrependRegexPrefixForIngressV1Fn returns a function that prepends a regex prefix to a path for a given netv1.Ingress.

func MaybeRewriteURI added in v2.12.0 

func MaybeRewriteURI(service *kongstate.Service, rewriteURIEnable bool) error

MaybeRewriteURI appends a request-transformer plugin to Kong routes based on the value of konghq.com/rewrite annotation configured on related K8s Ingresses.

func PathsFromIngressPaths added in v2.6.0 

func PathsFromIngressPaths(httpIngressPath netv1.HTTPIngressPath, addRegexPrefix bool) []*string

PathsFromIngressPaths takes a path and Ingress path type and returns a set of Kong route paths that satisfy that path type. It optionally adds the Kong 3.x regex path prefix for path types that require a regex path. It rejects unknown path types with an error.

func PortDefFromIntStr added in v2.8.1 

func PortDefFromIntStr(is intstr.IntOrString) kongstate.PortDef

func PortDefFromServiceBackendPort added in v2.8.1 

func PortDefFromServiceBackendPort(sbp *netv1.ServiceBackendPort) kongstate.PortDef

func TranslateIngresses added in v2.10.0 

func TranslateIngresses(
	ingresses []*netv1.Ingress,
	icp kongv1alpha1.IngressClassParametersSpec,
	flags TranslateIngressFeatureFlags,
	translatedObjectsCollector TranslatedKubernetesObjectsCollector,
) map[string]kongstate.Service

TranslateIngresses receives a slice of Kubernetes Ingress objects and produces a translated set of kong.Services and kong.Routes which will come wrapped in a kongstate.Service object.

Types

type GRPCRoutePriorityTraits added in v2.11.0 

type GRPCRoutePriorityTraits struct {
	// PreciseHostname is set to true if the hostname is non-wildcard.
	PreciseHostname bool
	// HostnameLength is the length of hostname. Max 253.
	HostnameLength int
	// MethodMatchType is the type of method match (if exists).
	// preserve this field since the API specification has not provided priority of type of method match yet.
	// (In normal situation should be higher than length of service/method value).
	// related issue: https://github.com/kubernetes-sigs/gateway-api/issues/2216
	MethodMatchType gatewayv1alpha2.GRPCMethodMatchType
	// ServiceLength is the length of GRPC service name. Max 1024.
	ServiceLength int
	// MethodLength is the length of GRPC method name. Max 1024.
	MethodLength int
	// HeaderCount is the number of header matches in the match. Max 16.
	HeaderCount int
}

func CalculateGRCPRouteMatchPriorityTraits added in v2.11.0 

func CalculateGRCPRouteMatchPriorityTraits(match SplitGRPCRouteMatch) GRPCRoutePriorityTraits

CalculateGRCPRouteMatchPriorityTraits calculates the traits to decide priority based on the hostname and match split from source GRPCRoute. Specification of priority goes as follow: (The following comments are extracted from gateway API specification about GRPCRoute)

Precedence MUST be given to the rule with the largest number of:

  • Characters in a matching non-wildcard hostname.
  • Characters in a matching hostname.
  • Characters in a matching service.
  • Characters in a matching method.
  • Header matches.

Method match type is preserved since the specification of GRPCRoute has not provided its priority yet.

func (GRPCRoutePriorityTraits) EncodeToPriority added in v2.11.0 

func (t GRPCRoutePriorityTraits) EncodeToPriority() RoutePriorityType

EncodeToPriority turns GRPCRoute priority traits into the integer expressed priority. 

	   4                   3                   2                   1
 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+-+---------------+---------------------+---------------------+---------+----------------+
|P| host len      | GRPC service length | GRPC method length  |Header No| relative order |
+-+---------------+---------------------+---------------------+---------+----------------+

Where: P: set to 1 if the hostname is non-wildcard. host len: length of hostname. GRPC service length: length of `Service` part in method match GRPC method length: length of `Method` part in method match Header No.: number of header matches. relative order: relative order of creation timestamp, namespace and name and internal rule/match order between different (split) GRPCRoutes.

REVIEW: althogh not specified in official docs, do we need to assign a bit for GRPC method match type to assign higher priority for method match with `Exact` match?

type HTTPRoutePriorityTraits added in v2.11.0 

type HTTPRoutePriorityTraits struct {
	PreciseHostname bool
	HostnameLength  int
	PathType        gatewayv1beta1.PathMatchType
	PathLength      int
	HeaderCount     int
	HasMethodMatch  bool
	QueryParamCount int
}

func CalculateHTTPRouteMatchPriorityTraits added in v2.11.0 

func CalculateHTTPRouteMatchPriorityTraits(match SplitHTTPRouteMatch) HTTPRoutePriorityTraits

CalculateHTTPRouteMatchPriorityTraits calculates the parts of priority that can be decided by the fields in spec of the match split from HTTPRoute. Specification of priority goes as follow: (The following comments are extracted from gateway API specification about HTTPRoute)

In the event that multiple HTTPRoutes specify intersecting hostnames, precedence must be given to rules from the HTTPRoute with the largest number of:

  • Characters in a matching non-wildcard hostname.
  • Characters in a matching hostname.

If ties exist across multiple Routes, the matching precedence rules for HTTPRouteMatches takes over.

Proxy or Load Balancer routing configuration generated from HTTPRoutes MUST prioritize matches based on the following criteria, continuing on ties. Across all rules specified on applicable Routes, precedence must be given to the match having:

  • "Exact” path match.
  • "Prefix" path match with largest number of characters.
  • Method match.
  • Largest number of header matches.
  • Largest number of query param matches.

func (HTTPRoutePriorityTraits) EncodeToPriority added in v2.11.0 

func (t HTTPRoutePriorityTraits) EncodeToPriority() RoutePriorityType

EncodeToPriority turns HTTPRoute priority traits into the integer expressed priority. 

	   4                   3                   2                   1
 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+-+---------------+-+-+-------------------+-+---------+---------+-----------------------+
|P| host len      |E|R|  Path length      |M|Header No|Query No.| relative order        |
+-+---------------+-+-+-------------------+-+---------+-------- +-----------------------+

Where: P: set to 1 if the hostname is non-wildcard. host len: host length of hostname. E: set to 1 if the path type is `Exact`. R: set to 1 if the path type in `RegularExpression`. Path length: length of `path.Value`. M: set to 1 if Method match is specified. Header No.: number of header matches. Query No.: number of query parameter matches. relative order: relative order of creation timestamp, namespace and name and internal rule/match order between different (split) HTTPRoutes.

type IngressRoutePriorityTraits added in v2.11.0 

type IngressRoutePriorityTraits struct {
	MatchFields   int
	PlainHostOnly bool
	HeaderCount   int
	MaxPathLength int
	HasRegexPath  bool
}

func (IngressRoutePriorityTraits) EncodeToPriority added in v2.11.0 

func (t IngressRoutePriorityTraits) EncodeToPriority() RoutePriorityType

EncodeToPriority encodes the traits to `priority` field used in Kong expression based routes. The bits are assigned in the following way: 

      4                   3                   2                   1
3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | MF | Header Number |P| PRESERVED |R| Path Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Where:

  • MF (Match Fields): how many fields there are to match on (path, host, headers, methods, SNIs).
  • Header Number: number of headers to match.
  • PRESERVED: reserved for future use if we want add other fields into consideration.
  • P (Plain Host): set if ALL hosts are non-wildcard.
  • R (Regex): if set, regex match is used.
  • Path Length: maximum length of the path to match.

type KongRouteTranslation added in v2.8.0 

type KongRouteTranslation struct {
	Name    string
	Matches []gatewayv1beta1.HTTPRouteMatch
	Filters []gatewayv1beta1.HTTPRouteFilter
}

KongRouteTranslation is a translation of a single HTTPRoute rule into metadata that can be used to instantiate Kong routes.

type KongServiceTranslation added in v2.8.0 

type KongServiceTranslation struct {
	Name        string
	BackendRefs []gatewayv1beta1.HTTPBackendRef
	KongRoutes  []KongRouteTranslation
}

KongServiceTranslation is a translation of a single HTTPRoute into metadata that can be used to instantiate Kong routes and services. Routes from this object should route traffic to BackendRefs from this object.

func TranslateHTTPRoute added in v2.8.0 

func TranslateHTTPRoute(route *gatewayv1beta1.HTTPRoute) []*KongServiceTranslation

TranslateHTTPRoute translates a list of HTTPRoutes into a list of HTTPRouteTranslationMeta objects that can be used to instantiate Kong routes and services. The translation is done by grouping the HTTPRoutes by their backendRefs. This means that all the rules of a single HTTPRoute will be grouped together if they share the same backendRefs.

type RoutePriorityType added in v2.12.1 

type RoutePriorityType = uint64

RoutePriorityType is the type of priority field of Kong routes. 

var (
	NormalIngressExpressionPriority RoutePriorityType = 1
	IngressDefaultBackendPriority   RoutePriorityType = 0
)

type SplitGRPCRouteMatch added in v2.11.0 

type SplitGRPCRouteMatch struct {
	Source     *gatewayv1alpha2.GRPCRoute
	Hostname   string
	Match      gatewayv1alpha2.GRPCRouteMatch
	RuleIndex  int
	MatchIndex int
}

SplitGRPCRouteMatch is the GRPCRouteMatch split by rule and match from the source GRPCRoute. RuleIndex and MatchIndex annotates the place of the match in the source GRPCRoute.

func SplitGRPCRoute added in v2.11.0 

func SplitGRPCRoute(grpcroute *gatewayv1alpha2.GRPCRoute) []SplitGRPCRouteMatch

SplitGRPCRoute splits a GRPCRoute by hostname and match into multiple matches. Each split match contains at most 1 hostname, and 1 rule with 1 match.

type SplitGRPCRouteMatchToPriority added in v2.11.0 

type SplitGRPCRouteMatchToPriority struct {
	Match    SplitGRPCRouteMatch
	Priority uint64
}

func AssignRoutePriorityToSplitGRPCRouteMatches added in v2.11.0 

func AssignRoutePriorityToSplitGRPCRouteMatches(
	logger logr.Logger,
	splitGRPCouteMatches []SplitGRPCRouteMatch,
) []SplitGRPCRouteMatchToPriority

AssignRoutePriorityToSplitGRPCRouteMatches assigns priority to ALL split GRPCRoute matches that are split by hostnames and matches from GRPCRoutes listed from the cache. Firstly assign "fixed" bits by the following fields of the matches: hostname, GRPC method match, number of header matches. If ties exists in the first step, where multiple matches has the same priority calculated from the fields, we run a sort for the matches in the tie and assign the bits for "relative order" according to the sorting result of these matches.

type SplitHTTPRouteMatch added in v2.11.0 

type SplitHTTPRouteMatch struct {
	Source     *gatewayv1beta1.HTTPRoute
	Hostname   string
	Match      gatewayv1beta1.HTTPRouteMatch
	RuleIndex  int
	MatchIndex int
}

func SplitHTTPRoute added in v2.11.0 

func SplitHTTPRoute(httproute *gatewayv1beta1.HTTPRoute) []SplitHTTPRouteMatch

SplitHTTPRoute splits HTTPRoutes into matches with at most one hostname, and one rule with exactly one match. It will split one rule with multiple hostnames and multiple matches to one hostname and one match per each HTTPRoute.

type SplitHTTPRouteMatchToKongRoutePriority added in v2.11.0 

type SplitHTTPRouteMatchToKongRoutePriority struct {
	Match    SplitHTTPRouteMatch
	Priority RoutePriorityType
}

func AssignRoutePriorityToSplitHTTPRouteMatches added in v2.11.0 

func AssignRoutePriorityToSplitHTTPRouteMatches(
	logger logr.Logger,
	splitHTTPRouteMatches []SplitHTTPRouteMatch,
) []SplitHTTPRouteMatchToKongRoutePriority

AssignRoutePriorityToSplitHTTPRouteMatches assigns priority to ALL split matches from ALL HTTPRoutes in the cache. Firstly assign "fixed" bits by the following fields of the match: hostname, path type, path length, method match, number of header matches, number of query param matches. If ties exists in the first step, where multiple matches has the same priority calculated from the fields, we run a sort for the matches in the tie and assign the bits for "relative order" according to the sorting result of these matches.

type TranslateIngressFeatureFlags added in v2.10.0 

type TranslateIngressFeatureFlags struct {
	// RegexPathPrefix enables adding the Kong 3.x+ regex path prefix on regex paths generated by the controller
	// (to satisfy the Ingress Prefix and Exact path types) or indicated by a resource (e.g. when an HTTPRoute uses a
	// RegularExpression Match). It does _not_ enable heuristic regex path detection for Ingress ImplementationSpecific
	// paths, which require an IngressClass setting.
	RegexPathPrefix bool

	// ExpressionRoutes indicates whether to translate Kubernetes objects to expression based Kong Routes.
	ExpressionRoutes bool

	// CombinedServices enables parser to create a single Kong Service when a Kubernetes Service is referenced
	// by multiple Ingresses. This is effective only when EnableCombinedServiceRoutes is enabled.
	CombinedServices bool
}

type TranslatedKubernetesObjectsCollector added in v2.10.0 

type TranslatedKubernetesObjectsCollector interface {
	Add(client.Object)
}

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.