Version: v1.22.1 Latest Latest

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

Go to latest
Published: Sep 7, 2022 License: Apache-2.0 Imports: 10 Imported by: 0




This section is empty.


DefaultFields are fields that will be included by default when JSON logging is enabled.

DefaultTLSCiphers contains the list of default ciphers used by Contour. A handful are commented out, as they're arguably less secure. They're also unnecessary - most of the clients that might need to use the commented ciphers are unable to connect without TLS 1.0, which contour never enables.

This list is ignored if the client and server negotiate TLS 1.3.

The commented ciphers are left in place to simplify updating this list for future versions of envoy.

ValidTLSCiphers contains the list of TLS ciphers that Envoy supports See: Note: This list is a superset of what is valid for stock Envoy builds and those using BoringSSL FIPS.


func GetenvOr

func GetenvOr(key string, defaultVal string) string

GetenvOr reads an environment or return a default value

func SanitizeCipherSuites added in v1.13.0

func SanitizeCipherSuites(ciphers []string) []string

SanitizeCipherSuites trims a list of ciphers to remove whitespace and duplicates, returning the passed in default if the corrected list is empty. The ciphers argument should be a list of valid ciphers.


type AccessLogFields

type AccessLogFields []string

func (AccessLogFields) AsFieldMap

func (a AccessLogFields) AsFieldMap() map[string]string

func (AccessLogFields) Validate

func (a AccessLogFields) Validate() error

type AccessLogLevel added in v1.21.0

type AccessLogLevel string
const LogLevelDisabled AccessLogLevel = "disabled"
const LogLevelError AccessLogLevel = "error"
const LogLevelInfo AccessLogLevel = "info" // Default log level.

func (AccessLogLevel) Validate added in v1.21.0

func (a AccessLogLevel) Validate() error

type AccessLogType

type AccessLogType string

AccessLogType is the name of a supported access logging mechanism.

DEFAULT_ACCESS_LOG_TYPE is the default access log format. nolint:revive

const EnvoyAccessLog AccessLogType = "envoy"
const JSONAccessLog AccessLogType = "json"

func (AccessLogType) Validate

func (a AccessLogType) Validate() error

type ClusterDNSFamilyType

type ClusterDNSFamilyType string

ClusterDNSFamilyType is the Ip family to use for resolving DNS names in an Envoy cluster configuration.

const AutoClusterDNSFamily ClusterDNSFamilyType = "auto"
const IPv4ClusterDNSFamily ClusterDNSFamilyType = "v4"
const IPv6ClusterDNSFamily ClusterDNSFamilyType = "v6"

func (ClusterDNSFamilyType) Validate

func (c ClusterDNSFamilyType) Validate() error

type ClusterParameters

type ClusterParameters struct {
	// 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.
	// Note: This only applies to externalName clusters.
	// See
	// for more information.
	DNSLookupFamily ClusterDNSFamilyType `yaml:"dns-lookup-family"`

ClusterParameters holds various configurable cluster values.

type GatewayParameters added in v1.13.0

type GatewayParameters struct {
	// ControllerName is used to determine whether Contour should reconcile a
	// GatewayClass. The string takes the form of "<namespace>/contour".
	// If unset, the gatewayclass controller will not be started.
	// Exactly one of ControllerName or GatewayRef must be set.
	ControllerName string `yaml:"controllerName,omitempty"`

	// GatewayRef defines a specific Gateway that this Contour
	// instance corresponds to. If set, Contour will reconcile
	// only this gateway, and will not reconcile any gateway
	// classes.
	// Exactly one of ControllerName or GatewayRef must be set.
	GatewayRef *NamespacedName `yaml:"gatewayRef,omitempty"`

GatewayParameters holds the configuration for Gateway API controllers.

func (*GatewayParameters) Validate added in v1.13.0

func (g *GatewayParameters) Validate() error

Validate the GatewayConfig.

type HTTPVersionType

type HTTPVersionType string

HTTPVersionType is the name of a supported HTTP version.

const HTTPVersion1 HTTPVersionType = "http/1.1"
const HTTPVersion2 HTTPVersionType = "http/2"

func (HTTPVersionType) Validate

func (h HTTPVersionType) Validate() error

type HeadersPolicy added in v1.14.0

type HeadersPolicy struct {
	Set    map[string]string `yaml:"set,omitempty"`
	Remove []string          `yaml:"remove,omitempty"`

func (HeadersPolicy) Validate added in v1.14.0

func (h HeadersPolicy) Validate() error

type ListenerParameters added in v1.13.0

type ListenerParameters struct {
	// ConnectionBalancer. If the value is exact, the listener will use the exact connection balancer
	// See
	// for more information.
	ConnectionBalancer string `yaml:"connection-balancer"`

ListenerParameters hold various configurable listener values.

func (*ListenerParameters) Validate added in v1.20.0

func (p *ListenerParameters) Validate() error

type MetricsParameters added in v1.20.0

type MetricsParameters struct {
	Contour MetricsServerParameters `yaml:"contour,omitempty"`
	Envoy   MetricsServerParameters `yaml:"envoy,omitempty"`

MetricsParameters defines configuration for metrics server endpoints in both Contour and Envoy.

func (*MetricsParameters) Validate added in v1.20.0

func (p *MetricsParameters) Validate() error

type MetricsServerParameters added in v1.20.0

type MetricsServerParameters struct {
	// Address that metrics server will bind to.
	Address string `yaml:"address,omitempty"`

	// Port that metrics server will bind to.
	Port int `yaml:"port,omitempty"`

	// ServerCert is the file path for server certificate.
	// Optional: required only if HTTPS is used to protect the metrics endpoint.
	ServerCert string `yaml:"server-certificate-path,omitempty"`

	// ServerKey is the file path for the private key which corresponds to the server certificate.
	// Optional: required only if HTTPS is used to protect the metrics endpoint.
	ServerKey string `yaml:"server-key-path,omitempty"`

	// CABundle is the file path for CA certificate(s) used for validating the client certificate.
	// Optional: required only if client certificates shall be validated to protect the metrics endpoint.
	CABundle string `yaml:"ca-certificate-path,omitempty"`

MetricsServerParameters defines configuration for metrics server.

func (*MetricsServerParameters) HasTLS added in v1.20.0

func (p *MetricsServerParameters) HasTLS() bool

HasTLS returns true if parameters have been provided to enable TLS for metrics.

func (*MetricsServerParameters) Validate added in v1.20.0

func (p *MetricsServerParameters) Validate() error

type NamespacedName

type NamespacedName struct {
	Name      string `yaml:"name"`
	Namespace string `yaml:"namespace"`

NamespacedName defines the namespace/name of the Kubernetes resource referred from the configuration file. Used for Contour configuration YAML file parsing, otherwise we could use K8s types.NamespacedName.

func (NamespacedName) Validate

func (n NamespacedName) Validate() error

Validate that both name fields are present, or neither are.

type NetworkParameters added in v1.13.0

type NetworkParameters struct {
	// XffNumTrustedHops defines the number of additional ingress proxy hops from the
	// right side of the x-forwarded-for HTTP header to trust when determining the origin
	// client’s IP address.
	// See
	// for more information.
	XffNumTrustedHops uint32 `yaml:"num-trusted-hops,omitempty"`

	// Configure the port used to access the Envoy Admin interface.
	// If configured to port "0" then the admin interface is disabled.
	EnvoyAdminPort int `yaml:"admin-port,omitempty"`

NetworkParameters hold various configurable network values.

type Parameters

type Parameters struct {
	// Enable debug logging
	Debug bool

	// Kubernetes client parameters.
	InCluster  bool   `yaml:"incluster,omitempty"`
	Kubeconfig string `yaml:"kubeconfig,omitempty"`

	// Server contains parameters for the xDS server.
	Server ServerParameters `yaml:"server,omitempty"`

	// GatewayConfig contains parameters for the gateway-api Gateway that Contour
	// is configured to serve traffic.
	GatewayConfig *GatewayParameters `yaml:"gateway,omitempty"`

	// Address to be placed in status.loadbalancer field of Ingress objects.
	// May be either a literal IP address or a host name.
	// The value will be placed directly into the relevant field inside the status.loadBalancer struct.
	IngressStatusAddress string `yaml:"ingress-status-address,omitempty"`

	// AccessLogFormat sets the global access log format.
	// Valid options are 'envoy' or 'json'
	AccessLogFormat AccessLogType `yaml:"accesslog-format,omitempty"`

	// AccessLogFormatString sets the access log format when format is set to `envoy`.
	// When empty, Envoy's default format is used.
	AccessLogFormatString string `yaml:"accesslog-format-string,omitempty"`

	// AccessLogFields sets the fields that JSON logging will
	// output when AccessLogFormat is json.
	AccessLogFields AccessLogFields `yaml:"json-fields,omitempty"`

	// AccessLogLevel sets the verbosity level of the access log.
	AccessLogLevel AccessLogLevel `yaml:"accesslog-level,omitempty"`

	// TLS contains TLS policy parameters.
	TLS TLSParameters `yaml:"tls,omitempty"`

	// DisablePermitInsecure disables the use of the
	// permitInsecure field in HTTPProxy.
	DisablePermitInsecure bool `yaml:"disablePermitInsecure,omitempty"`

	// DisableAllowChunkedLength disables the RFC-compliant Envoy behavior to
	// strip the "Content-Length" header if "Transfer-Encoding: chunked" is
	// also set. This is an emergency off-switch to revert back to Envoy's
	// default behavior in case of failures. Please file an issue if failures
	// are encountered.
	// See:
	DisableAllowChunkedLength bool `yaml:"disableAllowChunkedLength,omitempty"`

	// DisableMergeSlashes disables Envoy's non-standard merge_slashes path transformation option
	// which strips duplicate slashes from request URL paths.
	DisableMergeSlashes bool `yaml:"disableMergeSlashes,omitempty"`

	// EnableExternalNameService allows processing of ExternalNameServices
	// Defaults to disabled for security reasons.
	// TODO(youngnick): put a link to the issue and CVE here.
	EnableExternalNameService bool `yaml:"enableExternalNameService,omitempty"`

	// Timeouts holds various configurable timeouts that can
	// be set in the config file.
	Timeouts TimeoutParameters `yaml:"timeouts,omitempty"`

	// Policy specifies default policy applied if not overridden by the user
	Policy PolicyParameters `yaml:"policy,omitempty"`

	// Namespace of the envoy service to inspect for Ingress status details.
	EnvoyServiceNamespace string `yaml:"envoy-service-namespace,omitempty"`

	// Name of the envoy service to inspect for Ingress status details.
	EnvoyServiceName string `yaml:"envoy-service-name,omitempty"`

	// DefaultHTTPVersions defines the default set of HTTPS
	// versions the proxy should accept. HTTP versions are
	// strings of the form "HTTP/xx". Supported versions are
	// "HTTP/1.1" and "HTTP/2".
	// If this field not specified, all supported versions are accepted.
	DefaultHTTPVersions []HTTPVersionType `yaml:"default-http-versions"`

	// Cluster holds various configurable Envoy cluster values that can
	// be set in the config file.
	Cluster ClusterParameters `yaml:"cluster,omitempty"`

	// Network holds various configurable Envoy network values.
	Network NetworkParameters `yaml:"network,omitempty"`

	// Listener holds various configurable Envoy Listener values.
	Listener ListenerParameters `yaml:"listener,omitempty"`

	// RateLimitService optionally holds properties of the Rate Limit Service
	// to be used for global rate limiting.
	RateLimitService RateLimitService `yaml:"rateLimitService,omitempty"`

	// MetricsParameters holds configurable parameters for Contour and Envoy metrics.
	Metrics MetricsParameters `yaml:"metrics,omitempty"`

Parameters contains the configuration file parameters for the Contour ingress controller.

func Defaults

func Defaults() Parameters

Defaults returns the default set of parameters.

func Parse

func Parse(in io.Reader) (*Parameters, error)

Parse reads parameters from a YAML input stream. Any parameters not specified by the input are according to Defaults().

func (Parameters) AccessLogFormatterExtensions added in v1.18.0

func (p Parameters) AccessLogFormatterExtensions() []string

AccessLogFormatterExtensions returns a list of formatter extension names required by the access log format.

func (*Parameters) Validate

func (p *Parameters) Validate() error

Validate verifies that the parameter values do not have any syntax errors.

type PolicyParameters added in v1.14.0

type PolicyParameters struct {
	// RequestHeadersPolicy defines the request headers set/removed on all routes
	RequestHeadersPolicy HeadersPolicy `yaml:"request-headers,omitempty"`

	// ResponseHeadersPolicy defines the response headers set/removed on all routes
	ResponseHeadersPolicy HeadersPolicy `yaml:"response-headers,omitempty"`

	// ApplyToIngress determines if the Policies will apply to ingress objects
	ApplyToIngress bool `yaml:"applyToIngress,omitempty"`

PolicyParameters holds default policy used if not explicitly set by the user

func (PolicyParameters) Validate added in v1.14.0

func (h PolicyParameters) Validate() error

Validate the header parameters.

type RateLimitService added in v1.13.0

type RateLimitService struct {
	// ExtensionService identifies the extension service defining the RLS,
	// formatted as <namespace>/<name>.
	ExtensionService string `yaml:"extensionService,omitempty"`

	// Domain is passed to the Rate Limit Service.
	Domain string `yaml:"domain,omitempty"`

	// FailOpen defines whether to allow requests to proceed when the
	// Rate Limit Service fails to respond with a valid rate limit
	// decision within the timeout defined on the extension service.
	FailOpen bool `yaml:"failOpen,omitempty"`

	// EnableXRateLimitHeaders defines whether to include the X-RateLimit
	// headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset
	// (as defined by the IETF Internet-Draft linked below), on responses
	// to clients when the Rate Limit Service is consulted for a request.
	// ref.
	EnableXRateLimitHeaders bool `yaml:"enableXRateLimitHeaders,omitempty"`

RateLimitService defines properties of a global Rate Limit Service.

type ResourceVersion

type ResourceVersion string

ResourceVersion is a version of an xDS server.

const XDSv3 ResourceVersion = "v3"

func (ResourceVersion) Validate

func (s ResourceVersion) Validate() error

Validate the xDS server versions.

type ServerParameters

type ServerParameters struct {
	// Defines the XDSServer to use for `contour serve`.
	// Defaults to "contour"
	XDSServerType ServerType `yaml:"xds-server-type,omitempty"`

ServerParameters holds the configuration for the Contour xDS server.

type ServerType

type ServerType string

ServerType is the name of a xDS server implementation.

const ContourServerType ServerType = "contour"
const EnvoyServerType ServerType = "envoy"

func (ServerType) Validate

func (s ServerType) Validate() error

Validate the xDS server type.

type TLSCiphers added in v1.13.0

type TLSCiphers []string

TLSCiphers holds a list of TLS ciphers

func (TLSCiphers) Validate added in v1.13.0

func (tlsCiphers TLSCiphers) Validate() error

Validate ciphers. Returns error on unsupported cipher.

type TLSParameters

type TLSParameters struct {
	MinimumProtocolVersion string `yaml:"minimum-protocol-version"`

	// FallbackCertificate defines the namespace/name of the Kubernetes secret to
	// use as fallback when a non-SNI request is received.
	FallbackCertificate NamespacedName `yaml:"fallback-certificate,omitempty"`

	// ClientCertificate defines the namespace/name of the Kubernetes
	// secret containing the client certificate and private key
	// to be used when establishing TLS connection to upstream
	// cluster.
	ClientCertificate NamespacedName `yaml:"envoy-client-certificate,omitempty"`

	// CipherSuites defines the TLS ciphers to be supported by Envoy TLS
	// listeners when negotiating TLS 1.2. Ciphers are validated against the
	// set that Envoy supports by default. This parameter should only be used
	// by advanced users. Note that these will be ignored when TLS 1.3 is in
	// use.
	CipherSuites TLSCiphers `yaml:"cipher-suites,omitempty"`

TLSParameters holds configuration file TLS configuration details.

func (TLSParameters) Validate added in v1.13.0

func (t TLSParameters) Validate() error

Validate TLS fallback certificate, client certificate, and cipher suites

type TimeoutParameters

type TimeoutParameters struct {
	// RequestTimeout sets the client request timeout globally for Contour. Note that
	// this is a timeout for the entire request, not an idle timeout. Omit or set to
	// "infinity" to disable the timeout entirely.
	// See
	// for more information.
	RequestTimeout string `yaml:"request-timeout,omitempty"`

	// ConnectionIdleTimeout defines how long the proxy should wait while there are
	// no active requests (for HTTP/1.1) or streams (for HTTP/2) before terminating
	// an HTTP connection. Set to "infinity" to disable the timeout entirely.
	// See
	// for more information.
	ConnectionIdleTimeout string `yaml:"connection-idle-timeout,omitempty"`

	// StreamIdleTimeout defines how long the proxy should wait while there is no
	// request activity (for HTTP/1.1) or stream activity (for HTTP/2) before
	// terminating the HTTP request or stream. Set to "infinity" to disable the
	// timeout entirely.
	// See
	// for more information.
	StreamIdleTimeout string `yaml:"stream-idle-timeout,omitempty"`

	// MaxConnectionDuration defines the maximum period of time after an HTTP connection
	// has been established from the client to the proxy before it is closed by the proxy,
	// regardless of whether there has been activity or not. Omit or set to "infinity" for
	// no max duration.
	// See
	// for more information.
	MaxConnectionDuration string `yaml:"max-connection-duration,omitempty"`

	// DelayedCloseTimeout defines how long envoy will wait, once connection
	// close processing has been initiated, for the downstream peer to close
	// the connection before Envoy closes the socket associated with the connection.
	// Setting this timeout to 'infinity' will disable it, equivalent to setting it to '0'
	// in Envoy. Leaving it unset will result in the Envoy default value being used.
	// See
	// for more information.
	DelayedCloseTimeout string `yaml:"delayed-close-timeout,omitempty"`

	// ConnectionShutdownGracePeriod defines how long the proxy will wait between sending an
	// initial GOAWAY frame and a second, final GOAWAY frame when terminating an HTTP/2 connection.
	// During this grace period, the proxy will continue to respond to new streams. After the final
	// GOAWAY frame has been sent, the proxy will refuse new streams.
	// See
	// for more information.
	ConnectionShutdownGracePeriod string `yaml:"connection-shutdown-grace-period,omitempty"`

	// ConnectTimeout defines how long the proxy should wait when establishing connection to upstream service.
	// If not set, a default value of 2 seconds will be used.
	// See
	// for more information.
	// +optional
	ConnectTimeout string `yaml:"connect-timeout,omitempty"`

TimeoutParameters holds various configurable proxy timeout values.

func (TimeoutParameters) Validate

func (t TimeoutParameters) Validate() error

Validate the timeout parameters.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL