dag

package
v1.24.2 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2023 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Overview

Package dag provides a data model, in the form of a directed acyclic graph, of the relationship between Kubernetes Ingress, Service, and Secret objects.

Index

Constants

View Source 
const (
	// HeaderMatchTypeExact matches a header value exactly.
	HeaderMatchTypeExact = "exact"

	// HeaderMatchTypeContains matches a header value if it contains the
	// provided value.
	HeaderMatchTypeContains = "contains"

	// HeaderMatchTypePresent matches a header if it is present in a request.
	HeaderMatchTypePresent = "present"

	// HeaderMatchTypeRegex matches a header if it matches the provided regular
	// expression.
	HeaderMatchTypeRegex = "regex"
)
View Source 
const (
	KindHTTPRoute = "HTTPRoute"
	KindTLSRoute  = "TLSRoute"
	KindGateway   = "Gateway"
)
View Source 
const (
	HTTP_LISTENER_NAME  = "ingress_http"
	HTTPS_LISTENER_NAME = "ingress_https"
)

nolint:revive

View Source 
const (
	// LoadBalancerPolicyWeightedLeastRequest specifies the backend with least
	// active requests will be chosen by the load balancer.
	LoadBalancerPolicyWeightedLeastRequest = "WeightedLeastRequest"

	// LoadBalancerPolicyRandom denotes the load balancer will choose a random
	// backend when routing a request.
	LoadBalancerPolicyRandom = "Random"

	// LoadBalancerPolicyRoundRobin denotes the load balancer will route
	// requests in a round-robin fashion among backend instances.
	LoadBalancerPolicyRoundRobin = "RoundRobin"

	// LoadBalancerPolicyCookie denotes load balancing will be performed via a
	// Contour specified cookie.
	LoadBalancerPolicyCookie = "Cookie"

	// LoadBalancerPolicyRequestHash denotes request attribute hashing is used
	// to make load balancing decisions.
	LoadBalancerPolicyRequestHash = "RequestHash"
)
View Source 
const (
	// CACertificateKey is the key name for accessing TLS CA certificate bundles in Kubernetes Secrets.
	CACertificateKey = "ca.crt"

	// CRLKey is the key name for accessing CRL bundles in Kubernetes Secrets.
	CRLKey = "crl.pem"
)
View Source 
const (
	// QueryParamMatchTypeExact matches a querystring parameter value exactly.
	QueryParamMatchTypeExact = "exact"
)

Variables

This section is empty.

Functions

func ExtensionClusterName added in v1.13.0 

func ExtensionClusterName(meta types.NamespacedName) string

ExtensionClusterName generates a unique Envoy cluster name for an ExtensionCluster. The namespaced name of an ExtensionCluster is globally unique, so we can simply use that as the cluster name. As long as we scope the context with the "extension" prefix there can't be a conflict. Note that the name doesn't include a hash of the contents because we want a 1-1 mapping between ExtensionServices and Envoy Clusters; we don't want a new Envoy Cluster just because a field changed.

func ValidateRegex added in v1.10.0 

func ValidateRegex(regex string) error

ValidateRegex returns an error if the supplied RE2 regex syntax is invalid.

Types

type AuthorizationServerBufferSettings added in v1.20.0 

type AuthorizationServerBufferSettings struct {
	// MaxRequestBytes sets the maximum size of message body
	// ExtAuthz filter will hold in-memory.
	// Envoy will return HTTP 413 and will not initiate the
	// authorization process when buffer reaches the number set
	// in this field. Refer to
	// https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto#envoy-v3-api-msg-extensions-filters-http-ext-authz-v3-buffersettings
	// for more details.
	MaxRequestBytes uint32

	// If AllowPartialMessage is true,
	// then Envoy will buffer the body until MaxRequestBytes are reached.
	AllowPartialMessage bool

	// If PackAsBytes is true, the body sent to Authorization Server is in raw bytes.
	PackAsBytes bool
}

AuthorizationServerBufferSettings enables ExtAuthz filter to buffer client request data and send it as part of authorization request

type Builder 

type Builder struct {
	// Source is the source of Kubernetes objects
	// from which to build a DAG.
	Source KubernetesCache

	// Processors is the ordered list of Processors to
	// use to build the DAG.
	Processors []Processor

	// Metrics contains Prometheus metrics.
	Metrics *metrics.Metrics
}

Builder builds a DAG.

func (*Builder) Build 

func (b *Builder) Build() *DAG

Build builds and returns a new DAG by running the configured DAG processors, in order.

type CORSAllowOriginMatch added in v1.23.0 

type CORSAllowOriginMatch struct {
	// Type is the type of matching to perform.
	// Wildcard matches are treated as exact matches.
	Type CORSAllowOriginMatchType

	// Value is the pattern to match against, the specifics of which
	// will depend on the type of match.
	Value string
}

CORSAllowOriginMatch specifies how allowed origins should be matched.

type CORSAllowOriginMatchType added in v1.23.0 

type CORSAllowOriginMatchType int

CORSAllowOriginMatchType differentiates different CORS origin matching methods. 

const (
	// CORSAllowOriginMatchExact will match an origin exactly.
	// Wildcard "*" matches should be configured as exact matches.
	CORSAllowOriginMatchExact CORSAllowOriginMatchType = iota

	// CORSAllowOriginMatchRegex denote a regex pattern will be used
	// to match the origin in a request.
	CORSAllowOriginMatchRegex
)

type CORSPolicy added in v1.9.0 

type CORSPolicy struct {
	// Specifies whether the resource allows credentials.
	AllowCredentials bool
	// AllowOrigin specifies the origins that will be allowed to do CORS requests.
	AllowOrigin []CORSAllowOriginMatch
	// AllowMethods specifies the content for the *access-control-allow-methods* header.
	AllowMethods []string
	// AllowHeaders specifies the content for the *access-control-allow-headers* header.
	AllowHeaders []string
	// ExposeHeaders Specifies the content for the *access-control-expose-headers* header.
	ExposeHeaders []string
	// MaxAge specifies the content for the *access-control-max-age* header.
	MaxAge timeout.Setting
}

CORSPolicy allows setting the CORS policy

type ClientCertificateDetails added in v1.24.0 

type ClientCertificateDetails struct {
	// Subject of the client cert.
	Subject bool
	// Client cert in URL encoded PEM format.
	Cert bool
	// Client cert chain (including the leaf cert) in URL encoded PEM format.
	Chain bool
	// DNS type Subject Alternative Names of the client cert.
	DNS bool
	// URI type Subject Alternative Name of the client cert.
	URI bool
}

ClientCertificateDetails defines which parts of the client certificate will be forwarded.

type Cluster added in v1.0.0 

type Cluster struct {
	// Upstream is the backend Kubernetes service traffic arriving
	// at this Cluster will be forwarded to.
	Upstream *Service

	// The relative weight of this Cluster compared to its siblings.
	Weight uint32

	// The protocol to use to speak to this cluster.
	Protocol string

	// UpstreamValidation defines how to verify the backend service's certificate
	UpstreamValidation *PeerValidationContext

	// The load balancer strategy to use when picking a host in the cluster.
	// See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#enum-config-cluster-v3-cluster-lbpolicy
	LoadBalancerPolicy string

	// Cluster http health check policy
	*HTTPHealthCheckPolicy

	// Cluster tcp health check policy
	*TCPHealthCheckPolicy

	// RequestHeadersPolicy defines how headers are managed during forwarding
	RequestHeadersPolicy *HeadersPolicy

	// ResponseHeadersPolicy defines how headers are managed during forwarding
	ResponseHeadersPolicy *HeadersPolicy

	// CookieRewritePolicies is a list of policies that define how HTTP Set-Cookie
	// headers should be rewritten for responses on this route.
	CookieRewritePolicies []CookieRewritePolicy

	// SNI is used when a route proxies an upstream using tls.
	// SNI describes how the SNI is set on a Cluster and is configured via RequestHeadersPolicy.Host key.
	// Policies set on service are used before policies set on a route. Otherwise the value of the externalService
	// is used if the route is configured to proxy to an externalService type.
	// If the value is not set, then SNI is not changed.
	SNI string

	// DNSLookupFamily defines how external names are looked up
	// When configured as V4, the DNS resolver will only perform a lookup
	// for addresses in the IPv4 family. If V6 is configured, the DNS resolver
	// will only perform a lookup for addresses in the IPv6 family.
	// If AUTO is configured, the DNS resolver will first perform a lookup
	// for addresses in the IPv6 family and fallback to a lookup for addresses
	// in the IPv4 family. If ALL is specified, the DNS resolver will perform a lookup for
	// both IPv4 and IPv6 families, and return all resolved addresses.
	// When this is used, Happy Eyeballs will be enabled for upstream connections.
	// Refer to Happy Eyeballs Support for more information.
	// Note: This only applies to externalName clusters.
	DNSLookupFamily string

	// ClientCertificate is the optional identifier of the TLS secret containing client certificate and
	// private key to be used when establishing TLS connection to upstream cluster.
	ClientCertificate *Secret

	// TimeoutPolicy specifies how to handle timeouts for this cluster.
	TimeoutPolicy ClusterTimeoutPolicy

	SlowStartConfig *SlowStartConfig
}

Cluster holds the connection specific parameters that apply to traffic routed to an upstream service.

type ClusterTimeoutPolicy added in v1.21.0 

type ClusterTimeoutPolicy struct {
	// IdleConnectionTimeout is the timeout applied to idle connection.
	IdleConnectionTimeout timeout.Setting

	// ConnectTimeout defines how long the proxy should wait when establishing connection to upstream service.
	ConnectTimeout time.Duration
}

ClusterTimeoutPolicy defines the timeout policy for a cluster.

type CookieHashOptions added in v1.12.0 

type CookieHashOptions struct {
	// CookieName is the name of the header to hash.
	CookieName string

	// TTL is how long the cookie should be valid for.
	TTL time.Duration

	// Path is the request path the cookie is valid for.
	Path string
}

CookieHashOptions contains options for hashing a HTTP cookie.

type CookieRewritePolicy added in v1.19.0 

type CookieRewritePolicy struct {
	Name   string
	Path   *string
	Domain *string
	// Using an uint since pointer to boolean gets dereferenced in golang
	// text templates so we have no way of distinguishing if unset or set to false.
	// 0 means unset, 1 means false, 2 means true
	Secure   uint
	SameSite *string
}

CookieRewritePolicy defines how attributes of an HTTP Set-Cookie header can be rewritten.

type DAG 

type DAG struct {
	// StatusCache holds a cache of status updates to send.
	StatusCache status.Cache

	Listeners          []*Listener
	VirtualHosts       map[string]*VirtualHost
	SecureVirtualHosts map[string]*SecureVirtualHost
	ExtensionClusters  []*ExtensionCluster
}

func (*DAG) EnsureSecureVirtualHost added in v1.9.0 

func (d *DAG) EnsureSecureVirtualHost(hostname string) *SecureVirtualHost

EnsureSecureVirtualHost adds a secure virtual host with the provided name to the DAG if it does not already exist, and returns it.

func (*DAG) EnsureService added in v1.9.0 

func (d *DAG) EnsureService(meta types.NamespacedName, port intstr.IntOrString, healthPort intstr.IntOrString, cache *KubernetesCache, enableExternalNameSvc bool) (*Service, error)

EnsureService looks for a Kubernetes service in the cache matching the provided namespace, name and port, and returns a DAG service for it. If a matching service cannot be found in the cache, an error is returned.

func (*DAG) EnsureVirtualHost added in v1.9.0 

func (d *DAG) EnsureVirtualHost(hostname string) *VirtualHost

EnsureVirtualHost adds a virtual host with the provided name to the DAG if it does not already exist, and returns it.

func (*DAG) GetClusters added in v1.20.0 

func (d *DAG) GetClusters() []*Cluster

func (*DAG) GetDNSNameClusters added in v1.23.0 

func (d *DAG) GetDNSNameClusters() []*DNSNameCluster

func (*DAG) GetExtensionCluster added in v1.9.0 

func (d *DAG) GetExtensionCluster(name string) *ExtensionCluster

GetExtensionCluster returns the extension cluster in the DAG that matches the provided name, or nil if no matching extension cluster is found.

func (*DAG) GetExtensionClusters added in v1.9.0 

func (d *DAG) GetExtensionClusters() map[string]*ExtensionCluster

GetExtensionClusters returns all extension clusters in the DAG.

func (*DAG) GetSecrets added in v1.20.0 

func (d *DAG) GetSecrets() []*Secret

func (*DAG) GetSecureVirtualHost added in v1.9.0 

func (d *DAG) GetSecureVirtualHost(hostname string) *SecureVirtualHost

GetSecureVirtualHost returns the secure virtual host in the DAG that matches the provided name, or nil if no matching secure virtual host is found.

func (*DAG) GetSecureVirtualHostRoutes added in v1.20.0 

func (d *DAG) GetSecureVirtualHostRoutes() map[*SecureVirtualHost][]*Route

func (*DAG) GetServiceClusters added in v1.20.0 

func (d *DAG) GetServiceClusters() []*ServiceCluster

func (*DAG) GetVirtualHost added in v1.9.0 

func (d *DAG) GetVirtualHost(hostname string) *VirtualHost

GetVirtualHost returns the virtual host in the DAG that matches the provided name, or nil if no matching virtual host is found.

func (*DAG) GetVirtualHostRoutes added in v1.20.0 

func (d *DAG) GetVirtualHostRoutes() map[*VirtualHost][]*Route

type DNSNameCluster added in v1.23.0 

type DNSNameCluster struct {
	Address            string
	Scheme             string
	Port               int
	DNSLookupFamily    string
	UpstreamValidation *PeerValidationContext
}

DNSNameCluster is a cluster that routes directly to a DNS name (i.e. not a Kubernetes service).

type DirectResponse added in v1.15.0 

type DirectResponse struct {
	// StatusCode is  the HTTP response status to be returned.
	StatusCode uint32
	// Body is the content of the response body.
	Body string
}

DirectResponse allows for a specific HTTP status code and body to be the response to a route request vs routing to an envoy cluster.

type ExactMatchCondition added in v1.14.0 

type ExactMatchCondition struct {
	Path string
}

ExactMatchCondition matches the entire path of a URL.

func (*ExactMatchCondition) String added in v1.14.0 

func (ec *ExactMatchCondition) String() string

type ExtensionCluster added in v1.9.0 

type ExtensionCluster struct {
	// Name is the (globally unique) name of the corresponding Envoy cluster resource.
	Name string

	// Upstream is the cluster that receives network traffic.
	Upstream ServiceCluster

	// The protocol to use to speak to this cluster.
	Protocol string

	// UpstreamValidation defines how to verify the backend service's certificate
	UpstreamValidation *PeerValidationContext

	// The load balancer type to use when picking a host in the cluster.
	// See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#enum-config-cluster-v3-cluster-lbpolicy
	LoadBalancerPolicy string

	// RouteTimeoutPolicy specifies how to handle timeouts to this extension.
	RouteTimeoutPolicy RouteTimeoutPolicy

	// TimeoutPolicy specifies how to handle timeouts for this cluster.
	ClusterTimeoutPolicy ClusterTimeoutPolicy

	// SNI is used when a route proxies an upstream using TLS.
	SNI string

	// ClientCertificate is the optional identifier of the TLS secret containing client certificate and
	// private key to be used when establishing TLS connection to upstream cluster.
	ClientCertificate *Secret
}

ExtensionCluster generates an Envoy cluster (aka ClusterLoadAssignment) for an ExtensionService resource.

type ExtensionServiceProcessor added in v1.9.0 

type ExtensionServiceProcessor struct {
	logrus.FieldLogger

	// ClientCertificate is the optional identifier of the TLS
	// secret containing client certificate and private key to be
	// used when establishing TLS connection to upstream cluster.
	ClientCertificate *types.NamespacedName

	// ConnectTimeout defines how long the proxy should wait when establishing connection to upstream service.
	ConnectTimeout time.Duration
}

func (*ExtensionServiceProcessor) Run added in v1.9.0 

func (p *ExtensionServiceProcessor) Run(dag *DAG, cache *KubernetesCache)

type GatewayAPIProcessor added in v1.13.0 

type GatewayAPIProcessor struct {
	logrus.FieldLogger

	// EnableExternalNameService allows processing of ExternalNameServices
	// This is normally disabled for security reasons.
	// See https://github.com/projectcontour/contour/security/advisories/GHSA-5ph6-qq5x-7jwc for details.
	EnableExternalNameService bool

	// ConnectTimeout defines how long the proxy should wait when establishing connection to upstream service.
	ConnectTimeout time.Duration
	// contains filtered or unexported fields
}

GatewayAPIProcessor translates Gateway API types into DAG objects and adds them to the DAG.

func (*GatewayAPIProcessor) Run added in v1.13.0 

func (p *GatewayAPIProcessor) Run(dag *DAG, source *KubernetesCache)

Run translates Gateway API types into DAG objects and adds them to the DAG.

type GenericKeyDescriptorEntry added in v1.15.0 

type GenericKeyDescriptorEntry struct {
	Key   string
	Value string
}

GenericKeyDescriptorEntry configures a descriptor entry that has a static key & value.

type GlobalRateLimitPolicy added in v1.13.0 

type GlobalRateLimitPolicy struct {
	Descriptors []*RateLimitDescriptor
}

GlobalRateLimitPolicy holds global rate limiting parameters.

type HTTPHealthCheckPolicy added in v1.2.0 

type HTTPHealthCheckPolicy struct {
	Path               string
	Host               string
	Interval           time.Duration
	Timeout            time.Duration
	UnhealthyThreshold uint32
	HealthyThreshold   uint32
}

HTTPHealthCheckPolicy http health check policy

type HTTPProxyProcessor added in v1.9.0 

type HTTPProxyProcessor struct {

	// DisablePermitInsecure disables the use of the
	// permitInsecure field in HTTPProxy.
	DisablePermitInsecure bool

	// FallbackCertificate is the optional identifier of the
	// TLS secret to use by default when SNI is not set on a
	// request.
	FallbackCertificate *types.NamespacedName

	// EnableExternalNameService allows processing of ExternalNameServices
	// This is normally disabled for security reasons.
	// See https://github.com/projectcontour/contour/security/advisories/GHSA-5ph6-qq5x-7jwc for details.
	EnableExternalNameService bool

	// DNSLookupFamily defines how external names are looked up
	// When configured as V4, the DNS resolver will only perform a lookup
	// for addresses in the IPv4 family. If V6 is configured, the DNS resolver
	// will only perform a lookup for addresses in the IPv6 family.
	// If AUTO is configured, the DNS resolver will first perform a lookup
	// for addresses in the IPv6 family and fallback to a lookup for addresses
	// in the IPv4 family. If ALL is specified, the DNS resolver will perform a lookup for
	// both IPv4 and IPv6 families, and return all resolved addresses.
	// When this is used, Happy Eyeballs will be enabled for upstream connections.
	// Refer to Happy Eyeballs Support for more information.
	// Note: This only applies to externalName clusters.
	DNSLookupFamily contour_api_v1alpha1.ClusterDNSFamilyType

	// ClientCertificate is the optional identifier of the TLS secret containing client certificate and
	// private key to be used when establishing TLS connection to upstream cluster.
	ClientCertificate *types.NamespacedName

	// Request headers that will be set on all routes (optional).
	RequestHeadersPolicy *HeadersPolicy

	// Response headers that will be set on all routes (optional).
	ResponseHeadersPolicy *HeadersPolicy

	// ConnectTimeout defines how long the proxy should wait when establishing connection to upstream service.
	ConnectTimeout time.Duration
	// contains filtered or unexported fields
}

HTTPProxyProcessor translates HTTPProxies into DAG objects and adds them to the DAG.

func (*HTTPProxyProcessor) Run added in v1.9.0 

func (p *HTTPProxyProcessor) Run(dag *DAG, source *KubernetesCache)

Run translates HTTPProxies into DAG objects and adds them to the DAG.

type HeaderHashOptions added in v1.12.0 

type HeaderHashOptions struct {
	// HeaderName is the name of the header to hash.
	HeaderName string
}

HeaderHashOptions contains options for hashing a HTTP header.

type HeaderMatchCondition added in v1.7.0 

type HeaderMatchCondition struct {
	Name      string
	Value     string
	MatchType string
	Invert    bool
}

HeaderMatchCondition matches request headers by MatchType

func (*HeaderMatchCondition) String added in v1.7.0 

func (hc *HeaderMatchCondition) String() string

type HeaderMatchDescriptorEntry added in v1.15.0 

type HeaderMatchDescriptorEntry struct {
	HeaderName string
	Key        string
}

HeaderMatchDescriptorEntry configures a descriptor entry that's populated only if the specified header is present on the request.

type HeaderValue added in v1.1.0 

type HeaderValue struct {
	// Name represents a key of a header
	Key string
	// Value represents the value of a header specified by a key
	Value string
}

type HeaderValueMatchDescriptorEntry added in v1.15.0 

type HeaderValueMatchDescriptorEntry struct {
	Headers     []HeaderMatchCondition
	ExpectMatch bool
	Value       string
}

type HeadersPolicy added in v1.1.0 

type HeadersPolicy struct {
	// HostRewrite defines if a host should be rewritten on upstream requests
	HostRewrite string

	Add    map[string]string
	Set    map[string]string
	Remove []string
}

HeadersPolicy defines how headers are managed during forwarding

type IngressProcessor added in v1.9.0 

type IngressProcessor struct {
	logrus.FieldLogger

	// ClientCertificate is the optional identifier of the TLS secret containing client certificate and
	// private key to be used when establishing TLS connection to upstream cluster.
	ClientCertificate *types.NamespacedName

	// EnableExternalNameService allows processing of ExternalNameServices
	// This is normally disabled for security reasons.
	// See https://github.com/projectcontour/contour/security/advisories/GHSA-5ph6-qq5x-7jwc for details.
	EnableExternalNameService bool

	// Request headers that will be set on all routes (optional).
	RequestHeadersPolicy *HeadersPolicy

	// Response headers that will be set on all routes (optional).
	ResponseHeadersPolicy *HeadersPolicy

	// ConnectTimeout defines how long the proxy should wait when establishing connection to upstream service.
	ConnectTimeout time.Duration
	// contains filtered or unexported fields
}

IngressProcessor translates Ingresses into DAG objects and adds them to the DAG.

func (*IngressProcessor) Run added in v1.9.0 

func (p *IngressProcessor) Run(dag *DAG, source *KubernetesCache)

Run translates Ingresses into DAG objects and adds them to the DAG.

type JWTProvider added in v1.23.0 

type JWTProvider struct {
	Name       string
	Issuer     string
	Audiences  []string
	RemoteJWKS RemoteJWKS
	ForwardJWT bool
}

type JWTRule added in v1.23.0 

type JWTRule struct {
	PathMatchCondition    MatchCondition
	HeaderMatchConditions []HeaderMatchCondition
	ProviderName          string
}

type KubernetesCache 

type KubernetesCache struct {
	// RootNamespaces specifies the namespaces where root
	// HTTPProxies can be defined. If empty, roots can be defined in any
	// namespace.
	RootNamespaces []string

	// Names of ingress classes to cache HTTPProxies/Ingresses for. If not
	// set, objects with no ingress class or DEFAULT_INGRESS_CLASS will be
	// cached.
	IngressClassNames []string

	// ConfiguredGatewayToCache is the optional name of the specific Gateway to cache.
	// If set, only the Gateway with this namespace/name will be kept.
	ConfiguredGatewayToCache *types.NamespacedName

	// Secrets that are referred from the configuration file.
	ConfiguredSecretRefs []*types.NamespacedName

	Client client.Reader

	logrus.FieldLogger
	// contains filtered or unexported fields
}

A KubernetesCache holds Kubernetes objects and associated configuration and produces DAG values.

func (*KubernetesCache) DelegationPermitted added in v1.8.0 

func (kc *KubernetesCache) DelegationPermitted(secret types.NamespacedName, targetNamespace string) bool

DelegationPermitted returns true if the referenced secret has been delegated to the namespace where the ingress object is located.

func (*KubernetesCache) Insert 

func (kc *KubernetesCache) Insert(obj interface{}) bool

Insert inserts obj into the KubernetesCache. Insert returns true if the cache accepted the object, or false if the value is not interesting to the cache. If an object with a matching type, name, and namespace exists, it will be overwritten.

func (*KubernetesCache) LookupCASecret added in v1.24.0 

func (kc *KubernetesCache) LookupCASecret(name types.NamespacedName) (*Secret, error)

func (*KubernetesCache) LookupCRLSecret added in v1.24.0 

func (kc *KubernetesCache) LookupCRLSecret(name types.NamespacedName) (*Secret, error)

func (*KubernetesCache) LookupService added in v1.9.0 

func (kc *KubernetesCache) LookupService(meta types.NamespacedName, port intstr.IntOrString) (*v1.Service, v1.ServicePort, error)

LookupService returns the Kubernetes service and port matching the provided parameters, or an error if a match can't be found.

func (*KubernetesCache) LookupTLSSecret added in v1.24.0 

func (kc *KubernetesCache) LookupTLSSecret(name types.NamespacedName) (*Secret, error)

func (*KubernetesCache) LookupUpstreamValidation added in v1.9.0 

func (kc *KubernetesCache) LookupUpstreamValidation(uv *contour_api_v1.UpstreamValidation, caCertificate types.NamespacedName) (*PeerValidationContext, error)

func (*KubernetesCache) Remove 

func (kc *KubernetesCache) Remove(obj interface{}) bool

Remove removes obj from the KubernetesCache. Remove returns a boolean indicating if the cache changed after the remove operation.

type Listener added in v0.10.0 

type Listener struct {
	// Name is the unique name of the listener.
	Name string

	// Address is the TCP address to listen on.
	// If blank 0.0.0.0, or ::/0 for IPv6, is assumed.
	Address string

	// Port is the TCP port to listen on.
	Port int

	VirtualHosts       []*VirtualHost
	SecureVirtualHosts []*SecureVirtualHost
}

A Listener represents a TCP socket that accepts incoming connections.

type ListenerProcessor added in v1.9.0 

type ListenerProcessor struct{}

ListenerProcessor adds an HTTP and an HTTPS listener to the DAG if there are virtual hosts and secure virtual hosts already defined as roots in the DAG.

func (*ListenerProcessor) Run added in v1.9.0 

func (p *ListenerProcessor) Run(dag *DAG, _ *KubernetesCache)

Run adds HTTP and HTTPS listeners to the DAG if there are virtual hosts and secure virtual hosts already defined as roots in the DAG.

type LocalRateLimitPolicy added in v1.12.0 

type LocalRateLimitPolicy struct {
	MaxTokens            uint32
	TokensPerFill        uint32
	FillInterval         time.Duration
	ResponseStatusCode   uint32
	ResponseHeadersToAdd map[string]string
}

LocalRateLimitPolicy holds local rate limiting parameters.

type MatchCondition added in v1.7.0 

type MatchCondition interface {
	fmt.Stringer
}

type MirrorPolicy added in v1.0.0 

type MirrorPolicy struct {
	Cluster *Cluster
}

MirrorPolicy defines the mirroring policy for a route.

type ObjectStatusWriter added in v1.0.0 

type ObjectStatusWriter struct {
	// contains filtered or unexported fields
}

func (*ObjectStatusWriter) SetInvalid added in v1.0.0 

func (osw *ObjectStatusWriter) SetInvalid(format string, args ...interface{})

func (*ObjectStatusWriter) SetValid added in v1.0.0 

func (osw *ObjectStatusWriter) SetValid()

func (*ObjectStatusWriter) WithObject added in v1.0.0 

func (osw *ObjectStatusWriter) WithObject(obj metav1.Object) (_ *ObjectStatusWriter, commit func())

WithObject returns a new ObjectStatusWriter with a copy of the current ObjectStatusWriter's values, including its status if set. This is convenient if the object shares a relationship with its parent. The caller should arrange for the commit function to be called to write the final status of the object.

func (*ObjectStatusWriter) WithValue added in v1.0.0 

func (osw *ObjectStatusWriter) WithValue(key, val string) *ObjectStatusWriter

type Observer added in v1.8.0 

type Observer interface {
	OnChange(*DAG)
}

Observer is an interface for receiving notification of DAG updates.

func ComposeObservers added in v1.8.0 

func ComposeObservers(observers ...Observer) Observer

ComposeObservers returns a new Observer that calls each of its arguments in turn.

type ObserverFunc added in v1.8.0 

type ObserverFunc func(*DAG)

ObserverFunc is a function that implements the Observer interface by calling itself. It can be nil.

func (ObserverFunc) OnChange added in v1.8.0 

func (f ObserverFunc) OnChange(d *DAG)

type PathRewritePolicy added in v1.24.0 

type PathRewritePolicy struct {
	// Replace the part of the path matched by a prefix match
	// with this value.
	PrefixRewrite string

	// Replace the full path with this value.
	FullPathRewrite string

	// Replace the part of the path matched by the specified
	// regex with "/" (intended for removing a prefix).
	PrefixRegexRemove string
}

PathRewritePolicy defines a policy for rewriting the path of the request during forwarding. At most one field should be populated.

type PeerValidationContext added in v1.4.0 

type PeerValidationContext struct {
	// CACertificate holds a reference to the Secret containing the CA to be used to
	// verify the upstream connection.
	CACertificate *Secret
	// SubjectName holds an optional subject name which Envoy will check against the
	// certificate presented by the upstream.
	SubjectName string
	// SkipClientCertValidation when set to true will ensure Envoy requests but
	// does not verify peer certificates.
	SkipClientCertValidation bool
	// ForwardClientCertificate adds the selected data from the passed client TLS certificate
	// to the x-forwarded-client-cert header.
	ForwardClientCertificate *ClientCertificateDetails
	// CRL holds a reference to the Secret containing the Certificate Revocation List.
	// It is used to check for revocation of the peer certificate.
	CRL *Secret
	// OnlyVerifyLeafCertCrl when set to true, only the certificate at the end of the
	// certificate chain will be subject to validation by CRL.
	OnlyVerifyLeafCertCrl bool
	// OptionalClientCertificate when set to true will ensure Envoy does not require
	// that the client sends a certificate but if one is sent it will process it.
	OptionalClientCertificate bool
}

PeerValidationContext defines how to validate the certificate on the upstream service.

func (*PeerValidationContext) GetCACertificate added in v1.4.0 

func (pvc *PeerValidationContext) GetCACertificate() []byte

GetCACertificate returns the CA certificate from PeerValidationContext.

func (*PeerValidationContext) GetCRL added in v1.22.0 

func (pvc *PeerValidationContext) GetCRL() []byte

GetCRL returns the Certificate Revocation List.

func (*PeerValidationContext) GetSubjectName added in v1.4.0 

func (pvc *PeerValidationContext) GetSubjectName() string

GetSubjectName returns the SubjectName from PeerValidationContext.

type PrefixMatchCondition added in v1.7.0 

type PrefixMatchCondition struct {
	Prefix          string
	PrefixMatchType PrefixMatchType
}

PrefixMatchCondition matches the start of a URL.

func (*PrefixMatchCondition) String added in v1.7.0 

func (pc *PrefixMatchCondition) String() string

type PrefixMatchType added in v1.14.0 

type PrefixMatchType int

PrefixMatchType represents different types of prefix matching alternatives. 

const (
	// PrefixMatchString represents a prefix match that functions like a
	// string prefix match, i.e. prefix /foo matches /foobar
	PrefixMatchString PrefixMatchType = iota
	// PrefixMatchSegment represents a prefix match that only matches full path
	// segments, i.e. prefix /foo matches /foo/bar but not /foobar
	PrefixMatchSegment
)

type Processor added in v1.9.0 

type Processor interface {
	// Run executes the processor.
	Run(dag *DAG, source *KubernetesCache)
}

Processor constructs part of a DAG.

type ProcessorFunc added in v1.9.0 

type ProcessorFunc func(*DAG, *KubernetesCache)

ProcessorFunc adapts a function to the Processor interface.

func (ProcessorFunc) Run added in v1.9.0 

func (pf ProcessorFunc) Run(dag *DAG, source *KubernetesCache)

type QueryParamMatchCondition added in v1.22.0 

type QueryParamMatchCondition struct {
	Name      string
	Value     string
	MatchType string
}

QueryParamMatchCondition matches querystring parameters by MatchType

func (*QueryParamMatchCondition) String added in v1.22.0 

func (qc *QueryParamMatchCondition) String() string

type QueryParameterHashOptions added in v1.21.0 

type QueryParameterHashOptions struct {
	// ParameterName is the name of the query parameter to hash.
	ParameterName string
}

QueryParameterHashOptions contains options for hashing a request query parameter.

type RateLimitDescriptor added in v1.13.0 

type RateLimitDescriptor struct {
	Entries []RateLimitDescriptorEntry
}

RateLimitDescriptor is a list of rate limit descriptor entries.

type RateLimitDescriptorEntry added in v1.13.0 

type RateLimitDescriptorEntry struct {
	GenericKey       *GenericKeyDescriptorEntry
	HeaderMatch      *HeaderMatchDescriptorEntry
	HeaderValueMatch *HeaderValueMatchDescriptorEntry
	RemoteAddress    *RemoteAddressDescriptorEntry
}

RateLimitDescriptorEntry is an entry in a rate limit descriptor. Exactly one field should be non-nil.

type RateLimitPolicy added in v1.12.0 

type RateLimitPolicy struct {
	Local  *LocalRateLimitPolicy
	Global *GlobalRateLimitPolicy
}

RateLimitPolicy holds rate limiting parameters.

type Redirect added in v1.20.0 

type Redirect struct {
	// Hostname is the host name to redirect to.
	Hostname string

	// Scheme is the scheme (http or https) to
	// use in the redirect.
	Scheme string

	// PortNumber is the port to redirect to,
	// if any.
	PortNumber uint32

	// StatusCode is the HTTP response code to
	// use. Valid options are 301 or 302.
	StatusCode int

	// Path is the path to swap the url during a redirect.
	// Valid options start with a `/`.
	Path string

	// Prefix is the value to swap with the  prefix of the url
	// during a redirect.
	// Valid options start with a `/`.
	Prefix string
}

Redirect allows for a 301/302 redirect to be the response to a route request vs. routing to an envoy cluster.

type RegexMatchCondition added in v1.7.0 

type RegexMatchCondition struct {
	Regex string
}

RegexMatchCondition matches the URL by regular expression.

func (*RegexMatchCondition) String added in v1.7.0 

func (rc *RegexMatchCondition) String() string

type RemoteAddressDescriptorEntry added in v1.15.0 

type RemoteAddressDescriptorEntry struct{}

RemoteAddressDescriptorEntry configures a descriptor entry that contains the remote address (i.e. client IP).

type RemoteJWKS added in v1.23.0 

type RemoteJWKS struct {
	URI           string
	Timeout       time.Duration
	Cluster       DNSNameCluster
	CacheDuration *time.Duration
}

type RequestHashPolicy added in v1.12.0 

type RequestHashPolicy struct {
	// Terminal determines if the request attribute is present, hash
	// calculation should stop with this element.
	Terminal bool

	// HeaderHashOptions is set when a header hash is desired.
	HeaderHashOptions *HeaderHashOptions

	// CookieHashOptions is set when a cookie hash is desired.
	CookieHashOptions *CookieHashOptions

	// HashSourceIP is set to true when source ip hashing is desired.
	HashSourceIP bool

	// QueryParameterHashOptions is set when a query parameter hash is desired.
	QueryParameterHashOptions *QueryParameterHashOptions
}

RequestHashPolicy holds configuration for calculating hashes on an individual request attribute.

type RetryPolicy added in v1.0.0 

type RetryPolicy struct {
	// RetryOn specifies the conditions under which retry takes place.
	// If empty, retries will not be performed.
	RetryOn string

	// RetriableStatusCodes specifies the HTTP status codes under which retry takes place.
	RetriableStatusCodes []uint32

	// NumRetries specifies the allowed number of retries.
	// Ignored if RetryOn is blank, or defaults to 1 if RetryOn is set.
	NumRetries uint32

	// PerTryTimeout specifies the timeout per retry attempt.
	// Ignored if RetryOn is blank.
	PerTryTimeout timeout.Setting
}

RetryPolicy defines the retry / number / timeout options

type Route 

type Route struct {

	// PathMatchCondition specifies a MatchCondition to match on the request path.
	// Must not be nil.
	PathMatchCondition MatchCondition

	// HeaderMatchConditions specifies a set of additional Conditions to
	// match on the request headers.
	HeaderMatchConditions []HeaderMatchCondition

	// QueryParamMatchConditions specifies a set of additional Conditions to
	// match on the querystring parameters.
	QueryParamMatchConditions []QueryParamMatchCondition

	// Priority specifies the relative priority of the Route when compared to other
	// Routes that may have equivalent match conditions. A lower value here means the
	// Route has a higher priority.
	Priority uint8

	Clusters []*Cluster

	// Should this route generate a 301 upgrade if accessed
	// over HTTP?
	HTTPSUpgrade bool

	// AuthDisabled is set if authorization should be disabled
	// for this route. If authorization is disabled, the AuthContext
	// field has no effect.
	AuthDisabled bool

	// AuthContext sets the authorization context (if authorization is enabled).
	AuthContext map[string]string

	// Is this a websocket route?
	// TODO(dfc) this should go on the service
	Websocket bool

	// TimeoutPolicy defines the timeout request/idle
	TimeoutPolicy RouteTimeoutPolicy

	// RetryPolicy defines the retry / number / timeout options for a route
	RetryPolicy *RetryPolicy

	// Indicates that during forwarding, the matched prefix (or path) should be swapped with this value
	PathRewritePolicy *PathRewritePolicy

	// Mirror Policy defines the mirroring policy for this Route.
	MirrorPolicy *MirrorPolicy

	// RequestHeadersPolicy defines how headers are managed during forwarding
	RequestHeadersPolicy *HeadersPolicy

	// ResponseHeadersPolicy defines how headers are managed during forwarding
	ResponseHeadersPolicy *HeadersPolicy

	// CookieRewritePolicies is a list of policies that define how HTTP Set-Cookie
	// headers should be rewritten for responses on this route.
	CookieRewritePolicies []CookieRewritePolicy

	// RateLimitPolicy defines if/how requests for the route are rate limited.
	RateLimitPolicy *RateLimitPolicy

	// RequestHashPolicies is a list of policies for configuring hashes on
	// request attributes.
	RequestHashPolicies []RequestHashPolicy

	// DirectResponse allows for a specific HTTP status code
	// to be the response to a route request vs routing to
	// an envoy cluster.
	DirectResponse *DirectResponse

	// Redirect allows for a 301 Redirect to be the response
	// to a route request vs. routing to an envoy cluster.
	Redirect *Redirect

	// JWTProvider names a JWT provider defined on the virtual
	// host to be used to validate JWTs on requests to this route.
	JWTProvider string
}

Route defines the properties of a route to a Cluster.

func (*Route) HasPathPrefix added in v1.1.0 

func (r *Route) HasPathPrefix() bool

HasPathPrefix returns whether this route has a PrefixPathCondition.

func (*Route) HasPathRegex added in v1.1.0 

func (r *Route) HasPathRegex() bool

HasPathRegex returns whether this route has a RegexPathCondition.

type RouteTimeoutPolicy added in v1.21.0 

type RouteTimeoutPolicy struct {
	// ResponseTimeout is the timeout applied to the response
	// from the backend server.
	ResponseTimeout timeout.Setting

	// IdleStreamTimeout is the timeout applied to idle connection during single request-response.
	// Stream is HTTP/2 and HTTP/3 concept, for HTTP/1 it refers to single request-response within connection.
	IdleStreamTimeout timeout.Setting
}

RouteTimeoutPolicy defines the timeout policy for a route.

type Secret 

type Secret struct {
	Object         *v1.Secret
	ValidTLSSecret *SecretValidationStatus
	ValidCASecret  *SecretValidationStatus
	ValidCRLSecret *SecretValidationStatus
}

Secret represents a K8s Secret for TLS usage as a DAG Vertex. A Secret is a leaf in the DAG.

func (*Secret) Cert added in v1.0.0 

func (s *Secret) Cert() []byte

Cert returns the secret's tls certificate

func (*Secret) Data 

func (s *Secret) Data() map[string][]byte

Data returns the contents of the backing secret's map.

func (*Secret) Name 

func (s *Secret) Name() string

func (*Secret) Namespace 

func (s *Secret) Namespace() string

func (*Secret) PrivateKey added in v1.0.0 

func (s *Secret) PrivateKey() []byte

PrivateKey returns the secret's tls private key

type SecretValidationStatus added in v1.24.0 

type SecretValidationStatus struct {
	Error error
}

type SecureVirtualHost 

type SecureVirtualHost struct {
	VirtualHost

	// TLS minimum protocol version. Defaults to envoy_tls_v3.TlsParameters_TLS_AUTO
	MinTLSVersion string

	// The cert and key for this host.
	Secret *Secret

	// FallbackCertificate
	FallbackCertificate *Secret

	// Service to TCP proxy all incoming connections.
	*TCPProxy

	// DownstreamValidation defines how to verify the client's certificate.
	DownstreamValidation *PeerValidationContext

	// AuthorizationService points to the extension that client
	// requests are forwarded to for authorization. If nil, no
	// authorization is enabled for this host.
	AuthorizationService *ExtensionCluster

	// AuthorizationResponseTimeout sets how long the proxy should wait
	// for authorization server responses.
	AuthorizationResponseTimeout timeout.Setting

	// AuthorizationFailOpen sets whether authorization server
	// failures should cause the client request to also fail. The
	// only reason to set this to `true` is when you are migrating
	// from internal to external authorization.
	AuthorizationFailOpen bool

	// AuthorizationServerWithRequestBody specifies configuration
	// for buffering request data sent to AuthorizationServer
	AuthorizationServerWithRequestBody *AuthorizationServerBufferSettings

	// JWTProviders specify how to verify JWTs.
	JWTProviders []JWTProvider
}

A SecureVirtualHost represents a HTTP host protected by TLS.

func (*SecureVirtualHost) Valid added in v1.0.0 

func (s *SecureVirtualHost) Valid() bool

type Service 

type Service struct {
	Weighted WeightedService

	// Protocol is the layer 7 protocol of this service
	// One of "", "h2", "h2c", or "tls".
	Protocol string

	// Max connections is maximum number of connections
	// that Envoy will make to the upstream cluster.
	MaxConnections uint32

	// MaxPendingRequests is maximum number of pending
	// requests that Envoy will allow to the upstream cluster.
	MaxPendingRequests uint32

	// MaxRequests is the maximum number of parallel requests that
	// Envoy will make to the upstream cluster.
	MaxRequests uint32

	// MaxRetries is the maximum number of parallel retries that
	// Envoy will allow to the upstream cluster.
	MaxRetries uint32

	// ExternalName is an optional field referencing a dns entry for Service type "ExternalName"
	ExternalName string
}

Service represents a single Kubernetes' Service's Port.

type ServiceCluster added in v1.9.0 

type ServiceCluster struct {
	// ClusterName is a globally unique name for this ServiceCluster.
	// It is eventually used as the Envoy ClusterLoadAssignment
	// name, and must not be empty.
	ClusterName string
	// Services are the load balancing targets. This slice must not be empty.
	Services []WeightedService
}

ServiceCluster capture the set of Kubernetes Services that will compose the endpoints for a Envoy cluster. Traffic is balanced across the Service slice based on the weight of the elements.

func (*ServiceCluster) AddService added in v1.9.0 

func (s *ServiceCluster) AddService(name types.NamespacedName, port v1.ServicePort)

AddService adds the given service with a default weight of 1.

func (*ServiceCluster) AddWeightedService added in v1.9.0 

func (s *ServiceCluster) AddWeightedService(weight uint32, name types.NamespacedName, port v1.ServicePort)

AddWeightedService adds the given service with the given weight.

func (*ServiceCluster) DeepCopy added in v1.9.0 

func (s *ServiceCluster) DeepCopy() *ServiceCluster

DeepCopy performs a deep copy of ServiceClusters TODO(jpeach): apply deepcopy-gen to DAG objects.

func (*ServiceCluster) Rebalance added in v1.9.0 

func (s *ServiceCluster) Rebalance()

Rebalance rewrites the weights for the service cluster so that if no weights are specifies, the traffic is evenly distributed. This matches the behavior of weighted routes. Note that this is a destructive operation.

func (*ServiceCluster) Validate added in v1.9.0 

func (s *ServiceCluster) Validate() error

Validate checks whether this ServiceCluster satisfies its semantic invariants.

type SlowStartConfig added in v1.23.0 

type SlowStartConfig struct {
	Window           time.Duration
	Aggression       float64
	MinWeightPercent uint32
}

SlowStartConfig holds configuration for gradually increasing amount of traffic to a newly added endpoint.

func (*SlowStartConfig) String added in v1.23.0 

func (s *SlowStartConfig) String() string

type Status 

type Status struct {
	Object      metav1.Object
	Status      string
	Description string
	Vhost       string
}

Status contains the status for an HTTPProxy (valid / invalid / orphan, etc)

type StatusWriter added in v1.0.0 

type StatusWriter struct {
	// contains filtered or unexported fields
}

func (*StatusWriter) WithObject added in v1.0.0 

func (sw *StatusWriter) WithObject(obj metav1.Object) (_ *ObjectStatusWriter, commit func())

WithObject returns an ObjectStatusWriter that can be used to set the state of the object. The state can be set as many times as necessary. The state of the object can be made permanent by calling the commit function returned from WithObject. The caller should pass the ObjectStatusWriter to functions interested in writing status, but keep the commit function for itself. The commit function should be either called via a defer, or directly if statuses are being set in a loop (as defers will not fire until the end of the function).

type TCPHealthCheckPolicy added in v1.2.0 

type TCPHealthCheckPolicy struct {
	Interval           time.Duration
	Timeout            time.Duration
	UnhealthyThreshold uint32
	HealthyThreshold   uint32
}

TCPHealthCheckPolicy tcp health check policy

type TCPProxy added in v0.8.0 

type TCPProxy struct {

	// Clusters is the, possibly weighted, set
	// of upstream services to forward decrypted traffic.
	Clusters []*Cluster
}

TCPProxy represents a cluster of TCP endpoints.

type VirtualHost 

type VirtualHost struct {
	// Name is the fully qualified domain name of a network host,
	// as defined by RFC 3986.
	Name string

	// CORSPolicy is the cross-origin policy to apply to the VirtualHost.
	CORSPolicy *CORSPolicy

	// RateLimitPolicy defines if/how requests for the virtual host
	// are rate limited.
	RateLimitPolicy *RateLimitPolicy

	Routes map[string]*Route
}

A VirtualHost represents a named L4/L7 service.

func (*VirtualHost) AddRoute added in v1.21.0 

func (v *VirtualHost) AddRoute(route *Route)

func (*VirtualHost) Valid added in v1.0.0 

func (v *VirtualHost) Valid() bool

type WeightedService added in v1.9.0 

type WeightedService struct {
	// Weight is the integral load balancing weight.
	Weight uint32
	// ServiceName is the v1.Service name.
	ServiceName string
	// ServiceNamespace is the v1.Service namespace.
	ServiceNamespace string
	// ServicePort is the port to which we forward traffic.
	ServicePort v1.ServicePort
	// HealthPort is the port for healthcheck.
	HealthPort v1.ServicePort
}

WeightedService represents the load balancing weight of a particular v1.Weighted port.

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.