Defined Type: envoyproxy::tls_terminator

Defined in:
modules/envoyproxy/manifests/tls_terminator.pp

Summary

Configure envoy to be a TLS proxy to local services. It's thought as a simple shoe-in replacement for tlsproxy::localssl in limited use-cases for internal usage. The port on which Envoy should listen must be specified in the title.

Overview

SPDX-License-Identifier: Apache-2.0

Examples:

Set up a simple TLS termination for an upstream serving on port 80

envoyproxy::tls_terminator { '443':
  upstreams => [{
    server_names => ['citoid.svc.eqiad.wmnet', 'citoid'],
    cert_path    => '/etc/ssl/localcerts/citoid.crt',
    key_path     => '/etc/ssl/localcerts/citoid.key',
    upstream_port => 1234
  },
  {
    server_names => ['pdfrenderer.svc.eqiad.wmnet', 'pdfrenderer'],
    cert_path    => '/etc/ssl/localcerts/evil.crt',
    key_path     => '/etc/ssl/localcerts/evil.key',
    upstream_port => 666
  }],
  connect_timeout => 0.25,
  global_cert_path => '/etc/ssl/localcerts/services.crt',
  global_cert_key  => '/etc/ssl/localcert/services.key'
}

Set up non-sni only termination to backends, listen on TCP port 444

envoyproxy::tls_terminator { '444':
  upstreams => [{
    server_names => ['citoid.svc.eqiad.wmnet', 'citoid'],
    upstream_port => 1234
  },
  {
    server_names => ['pdfrenderer.svc.eqiad.wmnet', 'pdfrenderer'],
    upstream_port => 666
  }],
  connect_timeout => 0.25,
  global_cert_path => '/etc/ssl/localcerts/services.crt',
  global_cert_key  => '/etc/ssl/localcert/services.key'
}

Set up TLS global proxying in front of apache

envoyproxy::tls_terminator { '443':
  upstreams => [{
    server_names => ['*'],
    upstream_port => 80B
  },
  connect_timeout => 0.25,
  global_cert_path => '/etc/ssl/localcerts/services.crt',
  global_cert_key  => '/etc/ssl/localcert/services.key'
}

Parameters:

  • upstreams (Array[Envoyproxy::Tlsconfig]) (defaults to: []) —

    A list of Envoyproxy::Tlsconfig structures defining the upstream server configurations. A non-SNI default catchall will be autogenerated.

  • redir_port (Optional[Stdlib::Port]) (defaults to: undef) —

    TCP port to listen on as plain HTTP. This listener will redirect GET/HEAD to HTTPS with 301 and deny all other methods with 403. It does not proxy any traffic. If undefined, no HTTP redirect will be created. Default is undefined.

  • global_certs (Array[Envoyproxy::Tlscertificate]) (defaults to: []) —

    A list of certs to use

  • access_log (Boolean) (defaults to: false) —

    If true, sets up the access log for the TLS terminator.

  • websockets (Boolean) (defaults to: false) —

    If true, allows websocket upgrades.

  • use_remote_address (Boolean) (defaults to: true) —

    If true append the client IP to the x-forwarded-for header

  • fast_open_queue (Integer) (defaults to: 0) —

    The size of the fast open queue. If zero, TFO is disabled.

  • connect_timeout (Float) (defaults to: 1.0) —

    The time is seconds to wait before declaring a connection timeout to the upstream resource

  • upstream_response_timeout (Float) (defaults to: 65.0) —

    The time is seconds to wait for a response before declaring a connection timeout to the upstream resource

  • listen_ipv6 (Boolean) (defaults to: false) —

    Listen on IPv6 adding ipv4_compat allow both IPv4 and IPv6 connections, with peer IPv4 addresses mapped into IPv6 space as ::FFFF:<IPv4-address>

  • response_headers_to_add (Hash[String, String]) (defaults to: {}) —

    A dictionary of response headers to add to responses

  • generate_request_id (Boolean) (defaults to: true) —

    If true x-request-id will be populateed with a random UUID4 if the header does not exist.

  • circuit_breakers_config (Envoyproxy::Circuitbreakersconfig) (defaults to: 'defaults') —

    Specify a circuit breakers configuration preset. Current supported values are 'defaults' and 'disabled'.

  • retry_policy (Hash) (defaults to: {}) —

    An optional hash specifying the retry policy. It should map 1:1 what goes in the envoy configuration.

  • header_key_format (Envoyproxy::Headerkeyformat) (defaults to: 'none') —

    If proper_case, will capitalize headers for HTTP/1.1 requests If preserve_case, will preserve case on headers for HTTP/1.1 requests If none, will lowercase headers for HTTP/1.1 requests

  • global_tlsparams (Optional[Envoyproxy::Tlsparams]) (defaults to: undef) —

    Set Tlsparams for the non-SNI listener:

    cipher_suites => <= TLSv1.2 cipher suites
ecdh_curves   => ECDH curves
  • stek_files (Array[Stdlib::UnixPath]) (defaults to: []) —

    Set Session Ticket Encryption files to be used on both non-SNI and SNI listeners

  • global_alpn_protocols (Optional[Envoyproxy::Alpn]) (defaults to: undef) —

    Set ALPN protocols on the non-SNI listener. This is required to enable downstream H2 support

  • idle_timeout (Optional[Float]) (defaults to: undef) —

    The time in seconds to wait before closing a keepalive connection when inactive.

  • downstream_idle_timeout (Optional[Float]) (defaults to: undef) —

    The time in seconds to wait before closing a downstream keepalive connection when inactive.

  • stream_idle_timeout (Optional[Float]) (defaults to: undef) —

    The stream idle timeout for connections managed by the connection manager. If not specified, this defaults to 5 minutes. This timeout SHOULD be configured in the presence of untrusted downstreams.

  • request_timeout (Optional[Float]) (defaults to: undef) —

    The amount of time that Envoy will wait for the entire request to be received. The timer is activated when the request is initiated, and is disarmed when the last byte of the request is sent upstream. If not specified or set to 0, this timeout is disabled. This timeout SHOULD be configured in the presence of untrusted downstreams.

  • request_headers_timeout (Optional[Float]) (defaults to: undef) —

    The amount of time that Envoy will wait for the request headers to be received. The timer is activated when the first byte of the headers is received, and is disarmed when the last byte of the headers has been received. If not specified or set to 0, this timeout is disabled. This timeout SHOULD be configured in the presence of untrusted downstreams.

  • delayed_close_timeout (Optional[Float]) (defaults to: undef) —

    It is defined as a grace period after connection close processing has been locally initiated during which Envoy will wait for the peer to close (i.e., a TCP FIN/RST is received by Envoy from the downstream connection) prior to Envoy closing the socket associated with that connection The default timeout is 1s if this option is not specified

  • tls_handshake_timeout (Optional[Float]) (defaults to: undef) —

    TLS handshake timeout in seconds. Only available for V3 configuration and envoy >= 1.17.0

  • max_requests_per_conn (Optional[Integer]) (defaults to: undef) —

    The maximum number of requests to send over a connection

  • lua_script (Optional[String]) (defaults to: undef) —

    lua script contents to use as a global lua script. Only available for V3 configuration

  • connection_buffer_limit (Optional[Integer]) (defaults to: undef) —

    Soft limit (in bytes) on size of the listener’s new connection read and write buffers. According to envoy documentation this must be configured in presence of untrusted downstreams.

  • http2_options (Optional[Envoyproxy::Http2options]) (defaults to: undef) —

    Set HTTP/2 protocol options for downstream connections

  • error_html —

    Set the override html format for the error page if not empty

  • has_error_page (Boolean) (defaults to: false)
  • local_otel_reporting_pct (Float) (defaults to: 0.0) 


140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'modules/envoyproxy/manifests/tls_terminator.pp', line 140

define envoyproxy::tls_terminator(
    Array[Envoyproxy::Tlsconfig]       $upstreams                 = [],
    Boolean                            $access_log                = false,
    Boolean                            $websockets                = false,
    Boolean                            $use_remote_address        = true,
    Integer                            $fast_open_queue           = 0,
    Float                              $connect_timeout           = 1.0,
    Float                              $upstream_response_timeout = 65.0,
    Envoyproxy::Headerkeyformat        $header_key_format         = 'none',
    Boolean                            $listen_ipv6               = false,
    Boolean                            $generate_request_id       = true,
    Hash[String, String]               $response_headers_to_add   = {},
    Envoyproxy::Circuitbreakersconfig  $circuit_breakers_config   = 'defaults',
    Hash                               $retry_policy              = {},
    Optional[Stdlib::Port]             $redir_port                = undef,
    Array[Envoyproxy::Tlscertificate]  $global_certs              = [],
    Optional[Envoyproxy::Tlsparams]    $global_tlsparams          = undef,
    Array[Stdlib::UnixPath]            $stek_files                = [],
    Optional[Envoyproxy::Alpn]         $global_alpn_protocols     = undef,
    Optional[Float]                    $idle_timeout              = undef,
    Optional[Float]                    $downstream_idle_timeout   = undef,
    Optional[Float]                    $stream_idle_timeout       = undef,
    Optional[Float]                    $request_timeout           = undef,
    Optional[Float]                    $request_headers_timeout   = undef,
    Optional[Float]                    $delayed_close_timeout     = undef,
    Optional[Float]                    $tls_handshake_timeout     = undef,
    Optional[Integer]                  $max_requests_per_conn     = undef,
    Optional[String]                   $lua_script                = undef,
    Optional[Integer]                  $connection_buffer_limit   = undef,
    Optional[Envoyproxy::Http2options] $http2_options             = undef,
    Boolean                            $has_error_page            = false,
    Float                              $local_otel_reporting_pct  = 0.0,
) {

    # First of all, we can't configure a tls terminator if envoy is not installed.
    if !defined(Class['envoyproxy']) {
        fail('envoyproxy::tls_terminator should only be used once the envoyproxy class is declared.')
    }

    # As this is a fundamental function, install it with high priority
    # Please note they will be removed if we remove the terminator declaration.

    # We need a separate definition for each upstream cluster
    $upstreams.each |$upstream| {
        $upstream_name = $upstream['upstream'] ? {
            Envoyproxy::Ipupstream  => "local_port_${upstream['upstream']['port']}",
            Envoyproxy::Udsupstream => "local_path_${upstream['upstream']['path']}",
        }

        if !defined(Envoyproxy::Cluster["cluster_${upstream_name}"]) { # nothing wrong with several listeners using the same cluster
            envoyproxy::cluster { "cluster_${upstream_name}":
                priority => 0,
                content  => template('envoyproxy/tls_terminator/cluster.yaml.erb'),
            }
        }
    }
    envoyproxy::listener { "tls_terminator_${name}":
        priority => 0,
        content  => template('envoyproxy/tls_terminator/listener.yaml.erb'),
    }
    if $redir_port {
        # Redirection is less important, install it at the bottom of the pyle.
        envoyproxy::listener { "http_redirect_${name}":
            priority => 99,
            content  => template('envoyproxy/tls_terminator/redirect_listener.yaml.erb'),
        }
    }
}