Documentation ¶
Index ¶
- Constants
- Variables
- func ApplyExpressionToL4KongRoute(r *kongstate.Route)
- func GenerateKongExpressionRoutesFromGRPCRouteRule(grpcroute *gatewayv1alpha2.GRPCRoute, ruleNumber int) []kongstate.Route
- func GenerateKongExpressionRoutesFromHTTPRouteMatches(translation KongRouteTranslation, ingressObjectInfo util.K8sObjectInfo, ...) ([]kongstate.Route, error)
- func GenerateKongRoutesFromGRPCRouteRule(grpcroute *gatewayv1alpha2.GRPCRoute, ruleNumber int, prependRegexPrefix bool) []kongstate.Route
- func GeneratePluginsFromHTTPRouteFilters(filters []gatewayv1beta1.HTTPRouteFilter, path string, tags []*string) []kong.Plugin
- func KongExpressionRouteFromHTTPRouteMatchWithPriority(httpRouteMatchWithPriority SplitHTTPRouteMatchToKongRoutePriority) kongstate.Route
- func KongExpressionRouteFromSplitGRPCRouteMatchWithPriority(matchWithPriority SplitGRPCRouteMatchToPriority) kongstate.Route
- func KongServiceNameFromSplitGRPCRouteMatch(match SplitGRPCRouteMatch) string
- func KongServiceNameFromSplitHTTPRouteMatch(match SplitHTTPRouteMatch) string
- func MaybePrependRegexPrefix(path, controllerPrefix string, applyLegacyHeuristic bool) string
- func MaybePrependRegexPrefixForIngressV1Fn(ingress *netv1.Ingress, applyLegacyHeuristic bool) func(path string) *string
- func MaybeRewriteURI(service *kongstate.Service, rewriteURIEnable bool) error
- func PathsFromIngressPaths(httpIngressPath netv1.HTTPIngressPath, addRegexPrefix bool) []*string
- func PortDefFromIntStr(is intstr.IntOrString) kongstate.PortDef
- func PortDefFromServiceBackendPort(sbp *netv1.ServiceBackendPort) kongstate.PortDef
- func TranslateIngresses(ingresses []*netv1.Ingress, icp kongv1alpha1.IngressClassParametersSpec, ...) map[string]kongstate.Service
- type GRPCRoutePriorityTraits
- type HTTPRoutePriorityTraits
- type IngressRoutePriorityTraits
- type KongRouteTranslation
- type KongServiceTranslation
- type RoutePriorityType
- type SplitGRPCRouteMatch
- type SplitGRPCRouteMatchToPriority
- type SplitHTTPRouteMatch
- type SplitHTTPRouteMatchToKongRoutePriority
- type TranslateIngressFeatureFlags
- type TranslatedKubernetesObjectsCollector
Constants ¶
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 )
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 = "/~" )
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 ¶
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
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 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
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
MaybeRewriteURI appends a request-transformer plugin if the value of konghq.com/rewrite annotation is valid.
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 }