Gateway Common Configuration Messages

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

Configurations used to build gateways.

ClusterDestination

Field	Description	Validation Rule
name	string The name of the destination cluster. Only one of name or labels must be specified.	–
labels	map<string, string> Labels associated with the cluster. Any cluster with matching labels will be selected as a target. Only one of name or labels must be specified.	–
network	string The network associated with the destination clusters. In addition to name/label selectors, only clusters matching the selected networks will be used as a target. At least one of name/labels, and/or network must be specified. Deprecated: The network field is deprecated and will be removed in future releases. Only labels matching against the cluster object is supported.	–
weight	uint32 The weight for traffic to a given destination.	–

CorsPolicy

Field	Description	Validation Rule
allowOrigin	List of string The list of origins that are allowed to perform CORS requests. The content will be serialized into the Access-Control-Allow-Origin header. Wildcard * will allow all origins.	–
allowMethods	List of string List of HTTP methods allowed to access the resource. The content will be serialized into the Access-Control-Allow-Methods header.	–
allowHeaders	List of string List of HTTP headers that can be used when requesting the resource. Serialized to Access-Control-Allow-Headers header.	–
exposeHeaders	List of string A white list of HTTP headers that the browsers are allowed to access. Serialized into Access-Control-Expose-Headers header.	–
maxAge	google.protobuf.Duration Specifies how long the results of a preflight request can be cached. Translates to the Access-Control-Max-Age header.	–
allowCredentials	google.protobuf.BoolValue Indicates whether the caller is allowed to send the actual request (not the preflight) using credentials. Translates to Access-Control-Allow-Credentials header.	–

ExternalRateLimitServiceSettings

Configuration for ratelimiting using an external ratelimit server The ratelimit server must expose Envoy's Rate Limit Service gRPC API.

If the rate limit service is called, and the response for any of the descriptors is over limit, a 429 response is returned. The rate limit filter also sets the x-envoy-ratelimited header.

If there is an error in calling rate limit service or rate limit service returns an error and failure_mode_deny is set to true, a 500 response is returned.

Field	Description	Validation Rule
domain	string REQUIRED The rate limit domain to use when calling the rate limit service. Ratelimit settings are namespaced to a domain.	string = {   min_bytes: 1 }
failClosed	bool If the rate limit service is unavailable, the request will fail if failClosed is set to true. Defaults to false.	–
rateLimitServerUri	string REQUIRED The URI at which the external rate limit server can be reached.	string = {   min_bytes: 1 }
rules	List of tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitRule REQUIRED A set of rate limit rules. Each rule describes a list of dimension to match on. Once matched, a list of descriptors are sent to the external rate limit server	repeated = {   min_items: 1 }
timeout	google.protobuf.Duration The timeout in seconds for the external rate limit server RPC. Defaults to 0.020 seconds (20ms). Traffic will not be allowed to the destination if failClosed is set to true and the request to the rate limit server times out.	–
tls	tetrateio.api.tsb.auth.v2.ClientTLSSettings Configure TLS parameters to be used when connecting to the external rate limit server. By default, the client will not validate the certificates it is presented with.	–

RateLimitDimension

RateLimitDimension is a set of conditions to match HTTP requests Once the conditions are satisfied, corresponding descriptors (set of keys and values) are emitted and sent to the external rate limit server. The server is expected to make a rate limit decision based on these descriptors. Please go through the Envoy RateLimit descriptor to get more information on descriptors

Field	Description	Validation Rule
sourceCluster	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.SourceCluster oneof _dimension_specifier Rate limit on source envoy cluster.	–
destinationCluster	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.DestinationCluster oneof _dimension_specifier Rate limit on destination envoy cluster.	–
remoteAddress	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RemoteAddress oneof _dimension_specifier Rate limit on remote address of client.	–
requestHeaders	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RequestHeaders oneof _dimension_specifier Rate limit on the value of certain request headers.	–
headerValueMatch	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.HeaderValueMatch oneof _dimension_specifier Rate limit on the existence of certain request headers.	–

DestinationCluster

Emit descriptor entry - a key-value pair of the form ("destination_cluster", "\<routed target cluster\>") where destination_cluster is the destination envoy cluster to which traffic is bound to.

HeaderValueMatch

Emit descriptor entry - a key-value pair of the form ("header_match", "\<descriptor_value\>"), where descriptor_value is a user specified value corresponding to a header match event.

Field	Description	Validation Rule
headers	map<string, tetrateio.api.tsb.gateway.v2.StringMatch> REQUIRED Specifies a set of headers that the rate limit action should match on. The action will check the request’s headers against all the specified headers in the config. A match will happen if all the headers in the config are present in the request with the same values (or based on presence if the value field is not in the config). The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.	map = {   min_pairs: 1 }
descriptorValue	string REQUIRED The value to use in the descriptor entry.	string = {   min_bytes: 1 }

RemoteAddress

Emit descriptor entry - a key-value pair of the form ("remote_address", "\<trusted address from x-forwarded-for\>")

RequestHeaders

Emit descriptor entry - a key-value pair of the form ("\<descriptor_key\>", "\<header_value_queried_from_header\>") where descriptor_key is a user specified key to emit when the HTTP header is seen.

Field	Description	Validation Rule
headerName	string REQUIRED The header name to be queried from the request headers. The header’s value is used to populate the value of the descriptor entry for the descriptor_key.	string = {   min_bytes: 1 }
descriptorKey	string REQUIRED The key to use in the descriptor entry.	string = {   min_bytes: 1 }

SourceCluster

Emit descriptor entry - a key-value pair of the form ("source_cluster", "\<local service cluster\>") where source_cluster is the source envoy cluster (corresponding to the --service-cluster flag value set by Istio).

RateLimitRule

Field	Description	Validation Rule
dimensions	List of tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension REQUIRED A list of dimensions that are to be applied for this rate limit configuration. Order matters as the dimensions are processed sequentially and the descriptor is composed by appending descriptor entries in that sequence. If the condition for a dimension is not satisfied and cannot append a descriptor entry, no descriptor list is generated for the entire setting.	repeated = {   min_items: 1 }

HTTPRewrite

Configuration for an URL rewrite rule.

Field	Description	Validation Rule
uri	string Rewrite the path (or the prefix) portion of the URI with this value. If the original URI was matched based on prefix, the value provided in this field will replace the corresponding matched prefix.	–
authority	string Rewrite the Authority/Host header with this value.	–

Headers

Header manipulation rules.

Field	Description	Validation Rule
request	tetrateio.api.tsb.gateway.v2.Headers.HeaderOperations Header manipulation rules to apply before forwarding a request to the destination service.	–
response	tetrateio.api.tsb.gateway.v2.Headers.HeaderOperations Header manipulation rules to apply before returning a response to the caller.	–

HeaderOperations

HeaderOperations Describes the header manipulations to apply.

Field	Description	Validation Rule
set	map<string, string> Overwrite the headers specified by key with the given values.	–
add	map<string, string> Append the given values to the headers specified by keys (will create a comma-separated list of values).	–
remove	List of string Remove a the specified headers.	–

HostsReachability

HostsReachability defines the list of gateway hosts that this workspace can reach. In multicluster deployments, hosts are reachable to all namespaces(*) by default. However, this may not always be necessary, as clients may only be present in a few namespaces. By configuring this, a list of namespaces can be limited to the namespaces configured in the workspace. Workspaces with no hosts reachability configuration are considered to have reachable to all hosts.

Field	Description	Validation Rule
hostnames	List of tetrateio.api.tsb.gateway.v2.StringMatch REQUIRED The Gateway hostname that can be one of the following. Hostnames should match hosts configured in the Gateway. Exact hostnames. For example, echo.tetrate.io. Prefix hostnames. For example, echo. Hosts starting with echo are considered. Regex hostnames. For example, ^echo.*io$. Hosts starting with echo and ending with io are considered. List can be empty []. Workspaces with explicitly empty hostnames are considered to not want to see any hosts.	–

HttpMatchCondition

A single match clause to match all aspects of a request.

Field	Description	Validation Rule
uri	tetrateio.api.tsb.gateway.v2.StringMatch URI to match.	–
headers	map<string, tetrateio.api.tsb.gateway.v2.StringMatch> The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.	–

HttpModifyAction

HTTP path/url/header modification.

Field	Description	Validation Rule
rewrite	tetrateio.api.tsb.gateway.v2.HTTPRewrite Rewrite the HTTP Host or URL or both.	–
headers	tetrateio.api.tsb.gateway.v2.Headers Add/remove/overwrite one or more HTTP headers in a request or response.	–

RateLimitSettings

Configuration for ratelimiting HTTP/gRPC requests This has a list of rate limit rules that can be configured. With each rule a list of dimensions can be defined. A request counts towards the limit if all of the dimensions match the attributes of the request. When the matched requests exceed the limit, a 429 response is returned.

Field	Description	Validation Rule
rules	List of tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitRule REQUIRED A list of rules for ratelimiting. Each rule defines a list of dimensions to match on and the rate limit value for the rule. Each rule is independant of the other.	repeated = {   min_items: 1 }
failClosed	bool If the rate limit service is unavailable, the request will fail if failClosed is set to true. Defaults to false.	–
timeout	google.protobuf.Duration The timeout in seconds for the rate limit server RPC. Defaults to 0.020 seconds (20ms). Traffic will not be allowed to the destination if failClosed is set to true and the request to the rate limit server times out.	–

RateLimitDimension

RateLimitDimension is a condition to match HTTP requests that should be rate limited.

Field	Description	Validation Rule
remoteAddress	tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitDimension.RemoteAddress oneof _dimension_specifier Rate limit on the remote address of client.	–
header	tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitDimension.Header oneof _dimension_specifier Rate limit on certain HTTP headers. Special header names such as :path and :method can also be used.	–

Header

RateLimit based on certain headers

Field	Description	Validation Rule
name	string REQUIRED Name of the header to match on.	string = {   min_len: 1 }
value	tetrateio.api.tsb.gateway.v2.StringMatch Value of the header to match on if matching on a specific value. If not specified, ratelimit on every unique value of the header.	–

RemoteAddress

RateLimit based on the client's remote address, extracted from the trusted X-Forwarded-For header.

Field	Description	Validation Rule
value	string REQUIRED Ratelimit on a specific remote address. If the value is set to "*", ratelimit on every unique remote address.	string = {   min_len: 1 }

RateLimitRule

RateLimitRule is the block to define each internal ratelimit configuration.

Field	Description	Validation Rule
dimensions	List of tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitDimension REQUIRED A list of dimensions to define each ratelimit rule. Requests count towards the ratelimit value only when each and every condition in a dimension is matched for a given HTTP request.	repeated = {   min_items: 1 }
limit	tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitValue REQUIRED The ratelimit value that will be configured for the above rules.	message = {   required: true }

RateLimitValue

RateLimitValue specifies the values that will be used to determine the rate limit.

Field	Description	Validation Rule
requestsPerUnit	uint32 REQUIRED Specifies the value of the rate limit.	–
unit	tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitValue.Unit REQUIRED Specifies the unit of time for rate limit.	enum = {   defined_only: true }

RateLimiting

Configuration for ratelimiting HTTP/gRPC requests can be rate limited based on a variety of attributes in the request such as headers (including cookies), URL path/prefixes, client remote address etc.

Field	Description	Validation Rule
settings	tetrateio.api.tsb.gateway.v2.RateLimitSettings oneof _ratelimit_specifier Use Envoy and TSB's rateLimit server for ratelimiting HTTP Requests	–
externalService	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings oneof _ratelimit_specifier Configure ratelimiting using an external ratelimit server. This configuration only configures Envoy's ratelimit filters The user is expected to provision and configure their own external ratelimit server with the appropriate ratelimit values	–

Redirect

Field	Description	Validation Rule
uri	string On a redirect, overwrite the Path portion of the URL with this value.	–
authority	string On a redirect, overwrite the Authority/Host portion of the URL with this value.	–
redirectCode	uint32 On a redirect, Specifies the HTTP status code to use in the redirect response. It is expected to be 3XX. The default response code is MOVED_PERMANENTLY (301).	–
port	uint32 On a redirect, overwrite the Port portion of the URL with this value	–
scheme	string On a redirect, overwrite the scheme with this one. This can be used to perform http -> https redirect by setting this to "https". Currently, the only supported values are "http" and "https" (in lower-case).	–

ServerTLSSettings

Field	Description	Validation Rule
mode	tetrateio.api.tsb.gateway.v2.ServerTLSSettings.TLSMode Set this to SIMPLE, or MUTUAL for one-way TLS, mutual TLS respectively.	–
secretName	string The name of the secret in Kubernetes that holds the TLS certs including the CA certificates. The secret (type generic) should contain the following keys and values: key: \<privateKey\>, cert: \<serverCert\>, cacert: \<CACertificate\>.	–
files	tetrateio.api.tsb.gateway.v2.ServerTLSSettings.FileSource Load the keys and certificates from files accessible to the ingress gateway workload. Only one of secretName or files must be specified.	–
minProtocolVersion	tetrateio.api.tsb.gateway.v2.TLSProtocol Set the minimum supported TLS protocol version. Valid options: TLS_AUTO, TLSV1_0, TLSV1_1, TLSV1_2, TLSV1_3.	enum = {   defined_only: true }
maxProtocolVersion	tetrateio.api.tsb.gateway.v2.TLSProtocol Set the maximum supported TLS protocol version. Valid options: TLS_AUTO, TLSV1_0, TLSV1_1, TLSV1_2, TLSV1_3.	enum = {   defined_only: true }
cipherSuites	List of string List of cipher suites to be used for TLS connections. Examples of cipher suites: "TLS_RSA_WITH_AES_256_CBC_SHA" "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" "TLS_DHE_RSA_WITH_AES_256_GCM_SHA384" "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256" "TLS_RSA_WITH_3DES_EDE_CBC_SHA"	–
subjectAltNames	List of string List of Subject Alternative Names (SAN) from the client's certificate that are accepted for client identity verification during the TLS handshake.	–

FileSource

File path configuration of TLS keys and certificates.

Field	Description	Validation Rule
serverCertificate	string The path to the server cert file	–
privateKey	string The path to the server private key file	–
caCertificates	string The path to the file containing ca certs for verifying clients while using mutual TLS	–

StringMatch

Describes how to match a given string in HTTP headers. Match is case-sensitive.

Field	Description	Validation Rule
exact	string oneof _match_type Exact string match.	–
prefix	string oneof _match_type Prefix-based match.	–
regex	string oneof _match_type ECMAscript style regex-based match.	–

Unit

Units of time.

Field	Number	Description
UNKNOWN	0
SECOND	1
MINUTE	2
HOUR	3
DAY	4

TLSMode

Field	Number	Description
DISABLED	0
SIMPLE	1
MUTUAL	2
OPTIONAL_MUTUAL	3	Similar to MUTUAL mode, except that the client certificate is optional. Unlike SIMPLE mode, A client certificate will still be explicitly requested during handshake, but the client is not required to send a certificate. If a client certificate is presented, it will be validated. ca_certificates should be specified for validating client certificates.

TLSProtocol

Enumeration for TLS protocol versions.

Field	Number	Description
TLS_AUTO	0
TLSV1_0	1
TLSV1_1	2
TLSV1_2	3
TLSV1_3	4