Documentation
¶
Overview ¶
Package model contains a data model for translations from upstream Kubernetes resources to Cilium Kubernetes resources.
Initially, used for Ingress to CiliumEnvoyConfig translation to enable shared load balancing, but will be used for other things in the future (such as Gateway API support).
Index ¶
- func ComputeHosts(routeHostnames []string, listenerHostname *string, otherListenerHosts []string) []string
- type AccessLogs
- type AccessLogsFormat
- type AccessLogsTarget
- type Backend
- type BackendHTTPFilter
- type BackendPort
- type DirectResponse
- type FullyQualifiedResource
- type HTTPHeaderFilter
- type HTTPListener
- type HTTPRequestMirror
- type HTTPRequestRedirectFilter
- type HTTPRetry
- type HTTPRoute
- type HTTPURLRewriteFilter
- type Header
- type Infrastructure
- type KeyValueMatch
- type Listener
- type Model
- func (m *Model) AllPorts() []uint32
- func (m *Model) GetListeners() []Listener
- func (m *Model) HTTPPorts() []uint32
- func (m *Model) HTTPSPortsSorted() []uint32
- func (m *Model) IsAccessLogsConfigured() bool
- func (m *Model) IsEmpty() bool
- func (m *Model) IsHTTPAccessLogsConfigured() bool
- func (m *Model) IsHTTPListenerConfigured() bool
- func (m *Model) IsHTTPSListenerConfigured() bool
- func (m *Model) IsHTTPSPortConfigured(port uint32) bool
- func (m *Model) IsTCPAccessLogsConfigured() bool
- func (m *Model) IsTLSPassthroughListenerConfigured() bool
- func (m *Model) NeedsCrossProtocolSplit() bool
- func (m *Model) NeedsPerPortHTTPSListeners() bool
- func (m *Model) NeedsPerPortListeners() bool
- func (m *Model) NeedsPerPortTLSPassthroughListeners() bool
- func (m *Model) TLSPassthroughPorts() []uint32
- func (m *Model) TLSSecretsToHostnames() map[TLSSecret][]string
- func (m *Model) TLSSecretsToListeners() map[TLSSecret][]TLSListenerRef
- type Service
- type StringMatch
- type TLSListenerRef
- type TLSPassthroughListener
- func (l TLSPassthroughListener) GetAnnotations() map[string]string
- func (l TLSPassthroughListener) GetLabels() map[string]string
- func (l TLSPassthroughListener) GetPort() uint32
- func (l TLSPassthroughListener) GetService() *Service
- func (l TLSPassthroughListener) GetSources() []FullyQualifiedResource
- type TLSPassthroughRoute
- type TLSSecret
- type Telemetry
- type Timeout
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComputeHosts ¶
func ComputeHosts(routeHostnames []string, listenerHostname *string, otherListenerHosts []string) []string
ComputeHosts returns a list of the intersecting hostnames between the route and the listener. The below function is inspired from https://github.com/envoyproxy/gateway/blob/main/internal/gatewayapi/helpers.go. Special thanks to Envoy team. The function takes a list of route hostnames, a listener hostname, and a list of other listener hostnames. Note that the listenerHostname value will be skipped if it is present in the otherListenerHosts list.
Types ¶
type AccessLogs ¶ added in v1.18.12
type AccessLogs struct {
// Format specifies the access log format ("Text" or "JSON").
Format AccessLogsFormat `json:"format"`
// Text specifies the log template used when format is "Text".
Text string `json:"text,omitempty"`
// JSON specifies the field mapping used when format is "JSON".
JSON map[string]string `json:"json,omitempty"`
}
AccessLogs defines access logging configuration.
type AccessLogsFormat ¶ added in v1.18.12
type AccessLogsFormat string
AccessLogsFormat specifies the access log output format.
const ( AccessLogsFormatText AccessLogsFormat = "Text" AccessLogsFormatJSON AccessLogsFormat = "JSON" )
type AccessLogsTarget ¶ added in v1.18.12
type AccessLogsTarget string
AccessLogsTarget specifies where access logs are emitted.
const ( // AccessLogsTargetHTTP emits access logs from Envoy HTTP connection managers. AccessLogsTargetHTTP AccessLogsTarget = "HTTP" // AccessLogsTargetTCP emits access logs from Envoy TCP proxies, including TLS passthrough. AccessLogsTargetTCP AccessLogsTarget = "TCP" )
type Backend ¶
type Backend struct {
// Name of the Service.
Name string `json:"name,omitempty"`
// Namespace of the Service.
Namespace string `json:"namespace,omitempty"`
// Port contains the details of the port on the Service to connect to
// If unset, the same port as the top-level Listener will be used.
Port *BackendPort `json:"port,omitempty"`
// AppProtocol contains the application protocol as per KEP-3726
// for the port of the Service.
AppProtocol *string `json:"app_protocol,omitempty"`
// Weight specifies the percentage of traffic to send to this backend.
// This is computed as weight/(sum of all weights in backends) * 100.
Weight *int32 `json:"weight,omitempty"`
}
Backend holds a Kubernetes Service that points to a backend for traffic.
type BackendHTTPFilter ¶ added in v1.15.2
type BackendHTTPFilter struct {
// Name is the name of the Backend, the name is having the format of "namespace:name:port"
Name string `json:"name,omitempty"`
// RequestHeaderFilter can be used to add or remove an HTTP
// header from an HTTP request before it is sent to the upstream target.
RequestHeaderFilter *HTTPHeaderFilter `json:"request_header_filter,omitempty"`
// ResponseHeaderModifier can be used to add or remove an HTTP
// header from an HTTP response before it is sent to the client.
ResponseHeaderModifier *HTTPHeaderFilter `json:"response_header_modifier,omitempty"`
}
type BackendPort ¶
type BackendPort struct {
// Port holds the numeric port to connect to.
Port uint32 `json:"port,omitempty"`
// Name holds a string which will be used to connect to the port with a
// matching spec.ports[].name in the target Service.
Name string `json:"name,omitempty"`
}
BackendPort holds the details of what port on the Service to connect to. Only one of Port or Name can be set.
func (*BackendPort) GetPort ¶
func (be *BackendPort) GetPort() string
GetPort return the string representation of the port (either the port number or the port name)
type DirectResponse ¶
type DirectResponse struct {
StatusCode int `json:"status_code,omitempty"`
Body string `json:"body,omitempty"`
}
DirectResponse holds configuration for a direct response.
type FullyQualifiedResource ¶
type FullyQualifiedResource struct {
Name string `json:"name,omitempty"`
Namespace string `json:"namespace,omitempty"`
Group string `json:"group,omitempty"`
Version string `json:"version,omitempty"`
Kind string `json:"kind,omitempty"`
UID string `json:"uid,omitempty"`
}
FullyQualifiedResource stores the full details of a Kubernetes resource, including the Group, Version, and Kind. Namespace must be set to the empty string for cluster-scoped resources.
func AddSource ¶
func AddSource(sourceList []FullyQualifiedResource, source FullyQualifiedResource) []FullyQualifiedResource
type HTTPHeaderFilter ¶
type HTTPHeaderFilter struct {
// HeadersToAdd is a list of headers to add to the request.
// Existing headers with the same name will be appended to.
HeadersToAdd []Header `json:"headers_to_add,omitempty"`
// HeadersToSet is a list of headers to set in the request.
// Existing headers will be overwritten.
HeadersToSet []Header `json:"headers_to_set,omitempty"`
// HeadersToRemove is a list of headers to remove from the request.
HeadersToRemove []string `json:"headers_to_remove,omitempty"`
}
HTTPHeaderFilter holds configuration for a request header filter.
type HTTPListener ¶
type HTTPListener struct {
// Name of the HTTPListener
Name string `json:"name,omitempty"`
// Sources is a slice of fully qualified resources this HTTPListener is sourced
// from.
Sources []FullyQualifiedResource `json:"sources,omitempty"`
// IPAddress that the listener should listen on.
// The string must be parseable as an IP address.
Address string `json:"address,omitempty"`
// Port on which the service can be expected to be accessed by clients.
Port uint32 `json:"port,omitempty"`
// Hostname that the listener should match.
// Wildcards are supported in prefix or suffix forms, or the special wildcard `*`.
// An empty list means that the Listener should match all hostnames.
Hostname string `json:"hostname,omitempty"`
// TLS Certificate information. If omitted, then the listener is a cleartext HTTP listener.
TLS []TLSSecret `json:"tls,omitempty"`
// Routes associated with HTTP traffic to the service.
// An empty list means that traffic will not be routed.
Routes []HTTPRoute `json:"routes,omitempty"`
// Service configuration
Service *Service `json:"service,omitempty"`
// Infrastructure configuration
Infrastructure *Infrastructure `json:"infrastructure,omitempty"`
// ForceHTTPtoHTTPSRedirect enforces that, for HTTPListeners that have a
// TLS field set and create a HTTPS listener, an equivalent plaintext HTTP
// listener will be created that redirects requests from HTTP to HTTPS.
//
// This plaintext listener will override any other plaintext HTTP config in
// the final rendered Envoy Config.
ForceHTTPtoHTTPSRedirect bool `json:"force_http_to_https_redirect,omitempty"`
// Gamma is an indicator if this listener is a gamma listener
Gamma bool `json:"gamma,omitempty"`
}
HTTPListener holds configuration for any listener that terminates and proxies HTTP including HTTP and HTTPS. Each holds the configuration info for one distinct HTTP listener, by
- Hostname
- TLS
- Address
- Port
func (HTTPListener) GetAnnotations ¶ added in v1.15.0
func (l HTTPListener) GetAnnotations() map[string]string
func (HTTPListener) GetLabels ¶ added in v1.15.0
func (l HTTPListener) GetLabels() map[string]string
func (HTTPListener) GetPort ¶
func (l HTTPListener) GetPort() uint32
func (HTTPListener) GetService ¶ added in v1.18.0
func (l HTTPListener) GetService() *Service
func (HTTPListener) GetSources ¶
func (l HTTPListener) GetSources() []FullyQualifiedResource
type HTTPRequestMirror ¶
type HTTPRequestMirror struct {
// Backend is the backend handling the requests
Backend *Backend `json:"backend,omitempty"`
Numerator int32 `json:"numerator,omitempty"`
Denominator int32 `json:"denominator,omitempty"`
}
HTTPRequestMirror defines configuration for the RequestMirror filter.
type HTTPRequestRedirectFilter ¶
type HTTPRequestRedirectFilter struct {
// Scheme is the scheme to be used in the value of the `Location` header in
// the response. When empty, the scheme of the request is used.
Scheme *string `json:"scheme,omitempty"`
// Hostname is the hostname to be used in the value of the `Location`
// header in the response.
// When empty, the hostname of the request is used.
Hostname *string `json:"hostname,omitempty"`
// Path defines parameters used to modify the path of the incoming request.
// The modified path is then used to construct the `Location` header. When
// empty, the request path is used as-is.
Path *StringMatch `json:"path,omitempty"`
// Port is the port to be used in the value of the `Location`
// header in the response.
// When empty, port (if specified) of the request is used.
Port *int32 `json:"port,omitempty"`
// StatusCode is the HTTP status code to be used in response.
//
// Note that values may be added to this enum, implementations
// must ensure that unknown values will not cause a crash.
StatusCode *int `json:"status_code,omitempty"`
}
HTTPRequestRedirectFilter holds configuration for a request redirect.
type HTTPRetry ¶ added in v1.17.0
type HTTPRetry struct {
// Codes defines the HTTP response status codes for which a backend request
// should be retried.
Codes []uint32 `json:"codes,omitempty"`
// Attempts specifies the maximum number of times an individual request
// from the gateway to a backend should be retried.
Attempts *int `json:"attempts,omitempty"`
// Backoff specifies the minimum duration a Gateway should wait between
// retry attempts
Backoff *time.Duration `json:"backoff,omitempty"`
}
HTTPRetry holds the retry configuration for a route.
type HTTPRoute ¶
type HTTPRoute struct {
Name string `json:"name,omitempty"`
// Hostnames that the route should match
Hostnames []string `json:"hostnames,omitempty"`
// PathMatch specifies that the HTTPRoute should match a path.
PathMatch StringMatch `json:"path_match"`
// HeadersMatch specifies that the HTTPRoute should match a set of headers.
HeadersMatch []KeyValueMatch `json:"headers_match,omitempty"`
// QueryParamsMatch specifies that the HTTPRoute should match a set of query parameters.
QueryParamsMatch []KeyValueMatch `json:"query_params_match,omitempty"`
Method *string `json:"method,omitempty"`
// Backend is the backend handling the requests
Backends []Backend `json:"backends,omitempty"`
// BackendHTTPFilters can be used to add or remove HTTP
BackendHTTPFilters []*BackendHTTPFilter `json:"backend_http_filters,omitempty"`
// DirectResponse instructs the proxy to respond directly to the client.
DirectResponse *DirectResponse `json:"direct_response,omitempty"`
// RequestHeaderFilter can be used to add or remove an HTTP
// header from an HTTP request before it is sent to the upstream target.
RequestHeaderFilter *HTTPHeaderFilter `json:"request_header_filter,omitempty"`
// ResponseHeaderModifier can be used to add or remove an HTTP
// header from an HTTP response before it is sent to the client.
ResponseHeaderModifier *HTTPHeaderFilter `json:"response_header_modifier,omitempty"`
// RequestRedirect defines a schema for a filter that responds to the
// request with an HTTP redirection.
RequestRedirect *HTTPRequestRedirectFilter `json:"request_redirect,omitempty"`
// Rewrite defines a schema for a filter that modifies the URL of the request.
Rewrite *HTTPURLRewriteFilter `json:"rewrite,omitempty"`
// RequestMirrors defines a schema for a filter that mirrors HTTP requests
// Unlike other filter, multiple request mirrors are supported
RequestMirrors []*HTTPRequestMirror `json:"request_mirrors,omitempty"`
// IsGRPC is an indicator if this route is related to GRPC
IsGRPC bool `json:"is_grpc,omitempty"`
// Timeout holds the timeout configuration for a route.
Timeout Timeout `json:"timeout"`
// Retry holds the retry configuration for a route.
Retry *HTTPRetry `json:"retry,omitempty"`
}
HTTPRoute holds all the details needed to route HTTP traffic to a backend.
func (*HTTPRoute) GetMatchKey ¶
GetMatchKey returns the key to be used for matching the backend.
type HTTPURLRewriteFilter ¶
type HTTPURLRewriteFilter struct {
// Hostname is the value to be used to replace the Host header value during
// forwarding.
HostName *string `json:"host_name,omitempty"`
// Path is the values to be used to replace the path
Path *StringMatch `json:"path,omitempty"`
}
HTTPURLRewriteFilter defines a filter that modifies a request during forwarding. At most one of these filters may be used on a Route rule. This MUST NOT be used on the same Route rule as a HTTPRequestRedirect filter.
type Infrastructure ¶ added in v1.15.0
type Infrastructure struct {
// Labels is a map of labels to be propagated to LB service.
Labels map[string]string
// Annotations is a map of annotations to be propagated to LB service.
Annotations map[string]string
}
Infrastructure holds the labels and annotations configuration, which will be propagated to LB service.
type KeyValueMatch ¶
type KeyValueMatch struct {
Key string `json:"key,omitempty"`
Match StringMatch `json:"match"`
}
func (KeyValueMatch) String ¶
func (kv KeyValueMatch) String() string
type Model ¶
type Model struct {
HTTP []HTTPListener `json:"http,omitempty"`
TLSPassthrough []TLSPassthroughListener `json:"tls_passthrough,omitempty"`
Telemetry *Telemetry `json:"telemetry,omitempty"`
}
Model holds an abstracted data model representing the translation of various types of Kubernetes config to Cilium config.
func (*Model) AllPorts ¶ added in v1.18.0
AllPorts returns a list of unique ports for all listeners.
func (*Model) GetListeners ¶
func (*Model) HTTPPorts ¶ added in v1.18.0
HTTPPorts returns a list of unique ports for all HTTP listeners.
func (*Model) HTTPSPortsSorted ¶ added in v1.19.6
HTTPSPortsSorted returns sorted, unique ports for all HTTPS listeners.
func (*Model) IsAccessLogsConfigured ¶ added in v1.18.12
IsAccessLogsConfigured returns true if access logging is configured.
func (*Model) IsEmpty ¶ added in v1.18.0
IsEmpty returns true if the model has no HTTP or TLS Passthrough listeners.
func (*Model) IsHTTPAccessLogsConfigured ¶ added in v1.18.12
IsHTTPAccessLogsConfigured returns true if HTTP access logging is configured.
func (*Model) IsHTTPListenerConfigured ¶ added in v1.18.0
IsHTTPListenerConfigured returns true if the model has any HTTP listeners.
func (*Model) IsHTTPSListenerConfigured ¶ added in v1.18.0
IsHTTPSListenerConfigured returns true if the model has any HTTPS listeners.
func (*Model) IsHTTPSPortConfigured ¶ added in v1.19.6
IsHTTPSPortConfigured returns true if the model contains an HTTPS listener on the given port number.
func (*Model) IsTCPAccessLogsConfigured ¶ added in v1.18.12
IsTCPAccessLogsConfigured returns true if TCP access logging is configured.
func (*Model) IsTLSPassthroughListenerConfigured ¶ added in v1.18.0
IsTLSPassthroughListenerConfigured returns true if the model has any TLS Passthrough listeners.
func (*Model) NeedsCrossProtocolSplit ¶ added in v1.19.6
NeedsCrossProtocolSplit returns true when HTTPS and TLS passthrough filter chains on different Gateway listener ports cannot safely share a combined Envoy listener.
Filter chains from different Gateway listener ports must not share any SNI match because a combined Envoy listener would otherwise erase the original Gateway listener port boundary and route traffic for one listener to another. Same-port HTTPS and TLS passthrough conflicts cannot be fixed by per-port listeners and need to be rejected before translation.
func (*Model) NeedsPerPortHTTPSListeners ¶ added in v1.19.6
NeedsPerPortHTTPSListeners returns true if the model has more than one distinct HTTPS port.
func (*Model) NeedsPerPortListeners ¶ added in v1.19.6
NeedsPerPortListeners returns true if any protocol has enough distinct ports to require per-port Envoy Listener resources, or if cross-protocol SNI overlap would make a combined listener lose the Gateway listener port boundary.
func (*Model) NeedsPerPortTLSPassthroughListeners ¶ added in v1.19.6
NeedsPerPortTLSPassthroughListeners returns true if the model has more than one distinct TLS passthrough port.
func (*Model) TLSPassthroughPorts ¶ added in v1.18.0
TLSPassthroughPorts returns a list of unique ports for all TLS Passthrough listeners.
func (*Model) TLSSecretsToHostnames ¶ added in v1.18.0
TLSSecretsToHostnames returns a map of TLS secrets to hostnames. This is only for HTTP listeners.
func (*Model) TLSSecretsToListeners ¶ added in v1.19.6
func (m *Model) TLSSecretsToListeners() map[TLSSecret][]TLSListenerRef
TLSSecretsToListeners returns, for each TLS secret, the set of (hostname, port) pairs of all HTTPS listeners that reference it.
type Service ¶
type Service struct {
// Type is the type of service that is being used for Listener (e.g. Load Balancer or Node port)
// Defaults to Load Balancer type
Type string `json:"type,omitempty"`
// InsecureNodePort is the back-end port of the service that is being used for HTTP Listener
// Applicable only if Type is Node NodePort
InsecureNodePort *uint32 `json:"insecure_node_port,omitempty"`
// SecureNodePort is the back-end port of the service that is being used for HTTPS Listener
// Applicable only if Type is Node NodePort
SecureNodePort *uint32 `json:"secure_node_port,omitempty"`
ExternalTrafficPolicy string `json:"external_traffic_policy,omitempty"`
LoadBalancerClass *string `json:"load_balancer_class,omitempty"`
LoadBalancerSourceRanges []string `json:"load_balancer_source_ranges,omitempty"`
LoadBalancerSourceRangesPolicy string `json:"load_balancer_source_ranges_policy,omitempty"`
IPFamilies []string `json:"ip_families,omitempty"`
IPFamilyPolicy *string `json:"ip_family_policy,omitempty"`
AllocateLoadBalancerNodePorts *bool `json:"allocate_load_balancer_node_ports,omitempty"`
TrafficDistribution *string `json:"traffic_distribution,omitempty"`
}
Service holds the configuration for desired Service details Note: This is a subset of the Service.Spec struct from k8s Service. Not all fields are supported.
type StringMatch ¶
type StringMatch struct {
Prefix string `json:"prefix,omitempty"`
Exact string `json:"exact,omitempty"`
Regex string `json:"regex,omitempty"`
}
StringMatch describes various types of string matching. Only one field may be set. If no fields are set, all paths should match (no path match criteria should be generated for Envoy.)
func (StringMatch) String ¶
func (sm StringMatch) String() string
type TLSListenerRef ¶ added in v1.19.6
TLSListenerRef records a (hostname, port) pair for an HTTPS listener.
type TLSPassthroughListener ¶ added in v1.16.0
type TLSPassthroughListener struct {
// Name of the TLSListener
Name string `json:"name,omitempty"`
// Sources is a slice of fully qualified resources this TLSListener is sourced
// from.
Sources []FullyQualifiedResource `json:"sources,omitempty"`
// IPAddress that the listener should listen on.
// The string must be parseable as an IP address.
Address string `json:"address,omitempty"`
// Port on which the service can be expected to be accessed by clients.
Port uint32 `json:"port,omitempty"`
// Hostname that the listener should match.
// Wildcards are supported in prefix or suffix forms, or the special wildcard `*`.
// An empty list means that the Listener should match all hostnames.
Hostname string `json:"hostname,omitempty"`
// Routes associated with traffic to the service.
// An empty list means that traffic will not be routed.
Routes []TLSPassthroughRoute `json:"routes,omitempty"`
// Service configuration
Service *Service `json:"service,omitempty"`
// Infrastructure configuration
Infrastructure *Infrastructure `json:"infrastructure,omitempty"`
}
TLSPassthroughListener holds configuration for any listener that proxies TLS based on the SNI value. Each holds the configuration info for one distinct TLS listener, by
- Hostname
- Address
- Port
func (TLSPassthroughListener) GetAnnotations ¶ added in v1.16.0
func (l TLSPassthroughListener) GetAnnotations() map[string]string
func (TLSPassthroughListener) GetLabels ¶ added in v1.16.0
func (l TLSPassthroughListener) GetLabels() map[string]string
func (TLSPassthroughListener) GetPort ¶ added in v1.16.0
func (l TLSPassthroughListener) GetPort() uint32
func (TLSPassthroughListener) GetService ¶ added in v1.18.0
func (l TLSPassthroughListener) GetService() *Service
func (TLSPassthroughListener) GetSources ¶ added in v1.16.0
func (l TLSPassthroughListener) GetSources() []FullyQualifiedResource
type TLSPassthroughRoute ¶ added in v1.16.0
type TLSPassthroughRoute struct {
Name string `json:"name,omitempty"`
// Hostnames that the route should match
Hostnames []string `json:"hostnames,omitempty"`
// Backend is the backend handling the requests
Backends []Backend `json:"backends,omitempty"`
}
TLSPassthroughRoute holds all the details needed to route TLS traffic to a backend.
type TLSSecret ¶
type TLSSecret struct {
Name string `json:"name,omitempty"`
Namespace string `json:"namespace,omitempty"`
}
TLSSecret holds a reference to a secret containing a TLS keypair.
type Telemetry ¶ added in v1.18.12
type Telemetry struct {
// AccessLogs configures access logging.
AccessLogs map[AccessLogsTarget][]AccessLogs `json:"access_logs,omitempty"`
// NamespacedName identifies the Gateway associated with this telemetry configuration.
NamespacedName types.NamespacedName `json:"namespaced_name"`
}
Telemetry defines observability configuration.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ingestion holds functions that translate from Kubernetes resources into Listener types for storage in the model.
|
Package ingestion holds functions that translate from Kubernetes resources into Listener types for storage in the model. |
|
Package translation building block for translation from model to CiliumEnvoyConfig, Service, etc.
|
Package translation building block for translation from model to CiliumEnvoyConfig, Service, etc. |
|
ingress
Package ingress contains the translation logic from Ingress to CiliumEnvoyConfig and related resources.
|
Package ingress contains the translation logic from Ingress to CiliumEnvoyConfig and related resources. |