Documentation

Index

Constants

View Source
const DEFAULT_ACCESS_LOG_TYPE = EnvoyAccessLog

    DEFAULT_ACCESS_LOG_TYPE is the default access log format.

    Variables

    View Source
    var DefaultFields = AccessLogFields([]string{
    	"@timestamp",
    	"authority",
    	"bytes_received",
    	"bytes_sent",
    	"downstream_local_address",
    	"downstream_remote_address",
    	"duration",
    	"method",
    	"path",
    	"protocol",
    	"request_id",
    	"requested_server_name",
    	"response_code",
    	"response_flags",
    	"uber_trace_id",
    	"upstream_cluster",
    	"upstream_host",
    	"upstream_local_address",
    	"upstream_service_time",
    	"user_agent",
    	"x_forwarded_for",
    })

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

      View Source
      var DefaultTLSCiphers = TLSCiphers([]string{
      	"[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]",
      	"[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]",
      
      	"ECDHE-ECDSA-AES256-GCM-SHA384",
      	"ECDHE-RSA-AES256-GCM-SHA384",
      })

        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.

        Functions

        func GetenvOr

        func GetenvOr(key string, defaultVal string) string

          GetenvOr reads an environment or return a default value

          func SanitizeCipherSuites

          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.

            Types

            type AccessLogFields

            type AccessLogFields []string

            func (AccessLogFields) AsFieldMap

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

            func (AccessLogFields) Validate

            func (a AccessLogFields) Validate() error

            type AccessLogType

            type AccessLogType string

              AccessLogType is the name of a supported access logging mechanism.

              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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html#envoy-v3-api-enum-config-cluster-v3-cluster-dnslookupfamily
                	// for more information.
                	DNSLookupFamily ClusterDNSFamilyType `yaml:"dns-lookup-family"`
                }

                  ClusterParameters holds various configurable cluster values.

                  type GatewayParameters

                  type GatewayParameters struct {
                  	Name      string `yaml:"name,omitempty"`
                  	Namespace string `yaml:"namespace,omitempty"`
                  }

                    GatewayParameters holds the configuration for what Gateway API Gateway Contour will be configured to watch.

                    func (GatewayParameters) Validate

                    func (g GatewayParameters) Validate() error

                      Validate the GatewayConfig. Name & Namespace must be specified.

                      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 LeaderElectionParameters

                        type LeaderElectionParameters struct {
                        	LeaseDuration time.Duration `yaml:"lease-duration,omitempty"`
                        	RenewDeadline time.Duration `yaml:"renew-deadline,omitempty"`
                        	RetryPeriod   time.Duration `yaml:"retry-period,omitempty"`
                        	Namespace     string        `yaml:"configmap-namespace,omitempty"`
                        	Name          string        `yaml:"configmap-name,omitempty"`
                        }

                          LeaderElectionParameters holds the config bits for leader election inside the configuration file.

                          type ListenerParameters

                          type ListenerParameters struct {
                          	// ConnectionBalancer. If the value is exact, the listener will use the exact connection balancer
                          	// See https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/listener.proto#envoy-api-msg-listener-connectionbalanceconfig
                          	// for more information.
                          	ConnectionBalancer string `yaml:"connection-balancer"`
                          }

                            ListenerParameters hold various configurable listener values.

                            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

                                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 https://www.envoyproxy.io/docs/envoy/v1.17.0/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto?highlight=xff_num_trusted_hops
                                	// for more information.
                                	XffNumTrustedHops uint32 `yaml:"num-trusted-hops"`
                                }

                                  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"`
                                  
                                  	// AccessLogFields sets the fields that JSON logging will
                                  	// output when AccessLogFormat is json.
                                  	AccessLogFields AccessLogFields `yaml:"json-fields,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: https://github.com/projectcontour/contour/issues/3221
                                  	DisableAllowChunkedLength bool `yaml:"disableAllowChunkedLength,omitempty"`
                                  
                                  	// LeaderElection contains leader election parameters.
                                  	LeaderElection LeaderElectionParameters `yaml:"leaderelection,omitempty"`
                                  
                                  	// Timeouts holds various configurable timeouts that can
                                  	// be set in the config file.
                                  	Timeouts TimeoutParameters `yaml:"timeouts,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"`
                                  }

                                    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) Validate

                                        func (p *Parameters) Validate() error

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

                                          type RateLimitService

                                          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"`
                                          }

                                            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

                                                      type TLSCiphers []string

                                                        TLSCiphers holds a list of TLS ciphers

                                                        func (TLSCiphers) Validate

                                                        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

                                                            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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-request-timeout
                                                              	// 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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-idle-timeout
                                                              	// 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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-stream-idle-timeout
                                                              	// 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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#envoy-v3-api-field-config-core-v3-httpprotocoloptions-max-connection-duration
                                                              	// 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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-delayed-close-timeout
                                                              	// 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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#envoy-v3-api-field-extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-drain-timeout
                                                              	// for more information.
                                                              	ConnectionShutdownGracePeriod string `yaml:"connection-shutdown-grace-period,omitempty"`
                                                              }

                                                                TimeoutParameters holds various configurable proxy timeout values.

                                                                func (TimeoutParameters) Validate

                                                                func (t TimeoutParameters) Validate() error

                                                                  Validate the timeout parameters.