Version: 1.3.x

Ingress Gateway

IngressGateway configures a workload to act as a gateway for traffic entering the mesh. The ingress gateway also provides basic API gateway functionalities such as JWT token validation and request authorization. Gateways in privileged workspaces can route to services outside the workspace while those in unprivileged workspaces can only route to services inside the workspace.

The following example declares an ingress gateway running on pods with app: gateway labels in the ns1 namespace. The gateway exposes a host bookinfo.com on https port 9443. TLS is terminated using the certificates in the Kubernetes secret bookinfo-certs. Clients are authenticated using JWT tokens, whose keys are obtained from the OIDC provider www.googleapis.com. The request is then authorized by an the user's authorization engine hosted at https://company.com/authz before being forwarded to the productpage service in the backend.

apiVersion: gateway.tsb.tetrate.io/v2
kind: IngressGateway
metadata:
  name: ingress-bookinfo
  group: g1
  workspace: w1
  tenant: mycompany
  organization: myorg
spec:
  workloadSelector:
    namespace: ns1
    labels:
      app: gateway
  http:
  - name: bookinfo
    port: 9443
    hostname: bookinfo.com
    tls:
      mode: SIMPLE
      secretName: bookinfo-certs
    authentication:
      jwt:
        issuer: https://www.googleapis.com/oauth2/v1/certs
        audience: bookinfo
    authorization:
      external:
        uri: https://company.com/authz
        includeRequestHeaders:
        - Authorization # forwards the header to the authorization service.
    routing:
      rules:
      - route:
          host: ns1/productpage.ns1.svc.cluster.local
    rateLimiting:
      settings:
        rules:
          # Ratelimit at 10 requests/hour for clients with a remote address of 1.2.3.4 
        - dimensions: 
          - remoteAddress:
              value: 1.2.3.4
          limit:
            requestsPerUnit: 10
            unit: HOUR
          # Ratelimit at 50 requests/minute for every unique value in the user-agent header
        - dimensions:
          - header:
              name: user-agent
          limit:
            requestsPerUnit: 50
            unit: MINUTE
          # Ratelimit at 100 requests/second for every unique client remote address
          # with the HTTP requests having a GET method and the path prefix of /productpage
        - dimensions:
          - remoteAddress:
              value: "*"
          - header:
              name: ":path"
              value:
                prefix: /productpage
          - header:
              name: ":method"
              value:
                exact: "GET"
          limit:
            requestsPerUnit: 100
            unit: SECOND

If the productpage.ns1 service on Kubernetes has a ServiceRoute with multiple subsets and weights, the traffic will be split across the subsets accordingly.

Authentication

Field	Description	Validation Rule
jwt	tetrateio.api.tsb.gateway.v2.Authentication.JWT	–

JWT

Field	Description	Validation Rule
issuer	string REQUIRED Identifies the issuer that issued the JWT. See issuer A JWT with different `iss` claim will be rejected. Example: https://foobar.auth0.com Example: 1234567-compute@developer.gserviceaccount.com	string = { min_len: `1` }
audiences	List of string The list of JWT audiences. that are allowed to access. A JWT containing any of these audiences will be accepted. The service name will be accepted if audiences is empty.	–
jwksUri	string URL of the provider's public key set to validate signature of the JWT. See OpenID Discovery. Optional if the key set document can either (a) be retrieved from OpenID Discovery of the issuer or (b) inferred from the email domain of the issuer (e.g. a Google service account). Example: `https://www.googleapis.com/oauth2/v1/certs` Note: Only one of jwks_uri and jwks should be used. jwks_uri will be ignored if it does.	–
jwks	string JSON Web Key Set of public keys to validate signature of the JWT. See https://auth0.com/docs/jwks. Note: Only one of jwks_uri and jwks should be used. jwks_uri will be ignored if it does.	–

Authorization

Configuration for authorizing a HTTP request

Field	Description	Validation Rule
external	tetrateio.api.tsb.gateway.v2.Authorization.ExternalAuthzBackend	–
local	tetrateio.api.tsb.gateway.v2.Authorization.LocalAuthz	–

ExternalAuthzBackend

Use an authorization running at the specified URI. Note that this mode is supported only for HTTPS servers.

Field	Description	Validation Rule
uri	string	–
includeRequestHeaders	List of string	–

LocalAuthz

Authorize the request in Envoy based on the JWT claims.

Field	Description	Validation Rule
rules	List of tetrateio.api.tsb.gateway.v2.LocalAuthzRule	–

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 (https://www.envoyproxy.io/docs/envoy/latest/configuration/other_features/rate_limit#config-rate-limit-service).

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

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 https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/common/ratelimit/v3/ratelimit.proto#envoy-v3-api-msg-extensions-common-ratelimit-v3-ratelimitdescriptor to get more information on descriptors

Field	Description	Validation Rule
sourceCluster	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.SourceCluster Rate limit on source envoy cluster.	–
destinationCluster	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.DestinationCluster Rate limit on destination envoy cluster.	–
remoteAddress	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RemoteAddress Rate limit on remote address of client.	–
requestHeaders	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RequestHeaders Rate limit on the value of certain request headers.	–
headerValueMatch	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.HeaderValueMatch 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.

Name	Number	Description

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 , StringMatch > 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.
descriptorValue	string 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>")

Name	Number	Description

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

Name	Number	Description

RateLimitRule

Field	Description	Validation Rule
dimensions	List of tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension 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.	–

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 , 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.	–

HttpRouting

Field	Description	Validation Rule
corsPolicy	tetrateio.api.tsb.gateway.v2.CorsPolicy Cross origin resource request policy settings for all routes.	–
rules	List of tetrateio.api.tsb.gateway.v2.HttpRule REQUIRED HTTP routes.	repeated = { min_items: `1` }

HttpRule

A single HTTP rule.

Field	Description	Validation Rule
match	List of tetrateio.api.tsb.gateway.v2.HttpMatchCondition One or more match conditions (OR-ed).	–
modify	tetrateio.api.tsb.gateway.v2.HttpModifyAction One or more mutations to be performed before forwarding. Includes typical modifications to be done on a single request like URL rewrite, host rewrite, headers to add/remove/append.	–
route	tetrateio.api.tsb.gateway.v2.Route Forward the request to the specified destination(s). One of route or redirect must be specified.	–
redirect	tetrateio.api.tsb.gateway.v2.Redirect Redirect the request to a different host or URL or both. One of route or redirect must be specified.	–

HttpServer

An HTTP server exposed in an ingress gateway.

Field	Description	Validation Rule
name	string REQUIRED A name assigned to the server. The name will be visible in the generated metrics. The name must be unique across all servers in a gateway.	string = { min_len: `1` }
port	uint32 REQUIRED The port where the server is exposed. Two servers with different protocols (HTTP and HTTPS) should not share the same port. Note that port 15443 is reserved for internal use.	uint32 = { not_in: `0,15443` }
hostname	string REQUIRED Hostname with which the service can be expected to be accessed by clients. NOTE: The hostname must be unique across all gateways in the cluster in order for multicluster routing to work.	string = { min_len: `1` }
tls	tetrateio.api.tsb.gateway.v2.ServerTLSSettings TLS certificate info. If omitted, the gateway will expose a plain text HTTP server.	–
authentication	tetrateio.api.tsb.gateway.v2.Authentication Configuration to authenticate clients.	–
authorization	tetrateio.api.tsb.gateway.v2.Authorization Configuration to authorize a request.	–
routing	tetrateio.api.tsb.gateway.v2.HttpRouting REQUIRED Routing rules associated with HTTP traffic to this service.	message = { required: `true` }
rateLimiting	tetrateio.api.tsb.gateway.v2.RateLimiting Configuration for rate limiting requests. This configuration is namespaced to a particular HttpServer	–

IngressGateway

IngressGateway configures a workload to act as an ingress gateway into the mesh.

Field	Description	Validation Rule
workloadSelector	tetrateio.api.tsb.types.v2.WorkloadSelector REQUIRED Specify the gateway workloads (pod labels and Kubernetes namespace) under the gateway group that should be configured with this gateway. There can be only one gateway for a workload selector in a namespace.	message = { required: `true` }
http	List of tetrateio.api.tsb.gateway.v2.HttpServer One or more HTTP or HTTPS servers exposed by the gateway. The server exposes configuration for TLS termination, request authentication/authorization, HTTP routing, etc.	–
tlsPassthrough	List of tetrateio.api.tsb.gateway.v2.TLSPassthroughServer One or more TLS servers exposed by the gateway. The server does not terminate TLS and exposes config for SNI based routing.	–

LocalAuthzRule

Bindings define the subjects that can access the resource a policy is attached to, and the conditions that need to be met for that access to be granted. A policy can have multiple bindings to configure different access controls for specific subjects.

Field	Description	Validation Rule
name	string REQUIRED A friendly name to identify the binding.	string = { min_len: `1` }
from	List of tetrateio.api.tsb.gateway.v2.Subject Subjects configure the actors (end users, other services) that are allowed to access the target resource.	–
to	List of tetrateio.api.tsb.gateway.v2.LocalAuthzRule.HttpOperation A set of HTTP rules that need to be satisfied by the HTTP requests to get access to the target resource.	–

HttpOperation

Field	Description	Validation Rule
paths	List of string The request path where the request is made against. E.g. ["/accounts"].	repeated = { items: `{string:{min_len:1}}` }
methods	List of string The HTTP methods that are allowed by this rule. E.g. ["GET", "HEAD"].	repeated = { items: `{string:{in:[GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS]}}` }

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.	–

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 Rate limit on the remote address of client.	–
header	tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitDimension.Header 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 conditon 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` }

Unit

Units of time.

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

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 Use Envoy and TSB's rateLimit server for ratelimiting HTTP Requests	–
externalService	tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings 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.	–

Route

One or more destinations in a local/remote cluster for the given request.

Field	Description	Validation Rule
host	string REQUIRED The destination service in `<namespace>/<fqdn>` format for `IngressGateway` resources. For `Tier1Gateway` resources, the destination must be in `<clusterName>/<namespace>/<fqdn>` format, where cluster name corresponds to a cluster name created in the management plane. The `fqdn` must be the fully qualified name of the destination service in a cluster.	string = { min_len: `1` }
port	uint32 The port on the service to forward the request to. Omit only if the destination service has only one port. When used for routing from Tier1 gateways, the port specified here will be used only if the Tier1 gateway is doing TLS passthrough.	–

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>`.	–

TLSMode

Name	Number	Description
DISABLED	0
SIMPLE	1
MUTUAL	2

StringMatch

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

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

Subject

A subject designates an actor (user, service, etc) that attempts to access a target resource. Subjects can be modeled with JWT tokens, service accounts, and decorated with attributes such as HTTP request headers, JWT token claims, etc. The fields that define a subject will be matched to incoming requests, to fully qualify where the request comes from, and to decide if the given request is allowed or not for the target resource. All the fields in a subject are evaluated as AND expressions.

Field	Description	Validation Rule
jwt	tetrateio.api.tsb.gateway.v2.Subject.JWTClaims JWT configuration to identity the subject.	–

JWTClaims

JWT based subject

JWT based subjects qualify a subject by matching against a JWT token present in the request. By default the token is expected to be present in the 'Authorization' HTTP header, with the 'Bearer" prefix.

Field	Description	Validation Rule
iss	string	–
sub	string	–
other	map <string , string > A set of arbitrary claims that are required to qualify the subject. E.g. "iss": "*@foo.com".

TLSPassthroughServer

A TLS server exposed in an ingress gateway. For TLS servers the gateways don't terminate connections and use SNI based routing.

Field	Description	Validation Rule
name	string REQUIRED A name assigned to the server. The name will be visible in the generated metrics. The name must be unique across all HTTP and TLS servers in a gateway.	string = { min_len: `1` }
port	uint32 REQUIRED The port where the server is exposed. Two servers with different protocols (HTTP and HTTPS) should not share the same port. Note that port 15443 is reserved for internal use.	uint32 = { not_in: `0,15443` }
hostname	string REQUIRED Hostname with which the service can be expected to be accessed by clients. Routing will be done based on SNI matches for this hostname. NOTE: The hostname must be unique across all gateways in the cluster in order for multicluster routing to work.	string = { min_len: `1` }
route	tetrateio.api.tsb.gateway.v2.Route REQUIRED Forward the connection to the specified destination.	message = { required: `true` }

Authentication​

JWT​

Authorization​

ExternalAuthzBackend​

LocalAuthz​

CorsPolicy​

ExternalRateLimitServiceSettings​

RateLimitDimension​

DestinationCluster​

HeaderValueMatch​

RemoteAddress​

RequestHeaders​

SourceCluster​

RateLimitRule​

HTTPRewrite​

Headers​

HeaderOperations​

HttpMatchCondition​

HttpModifyAction​

HttpRouting​

HttpRule​

HttpServer​

IngressGateway​

LocalAuthzRule​

HttpOperation​

RateLimitSettings​

RateLimitDimension​

Header​

RemoteAddress​

RateLimitRule​

RateLimitValue​

Unit​

RateLimiting​

Redirect​

Route​

ServerTLSSettings​

TLSMode​

StringMatch​

Subject​

JWTClaims​

TLSPassthroughServer​

Authentication

JWT

Authorization

ExternalAuthzBackend

LocalAuthz

CorsPolicy

ExternalRateLimitServiceSettings

RateLimitDimension

DestinationCluster

HeaderValueMatch

RemoteAddress

RequestHeaders

SourceCluster

RateLimitRule

HTTPRewrite

Headers

HeaderOperations

HttpMatchCondition

HttpModifyAction

HttpRouting

HttpRule

HttpServer

IngressGateway

LocalAuthzRule

HttpOperation

RateLimitSettings

RateLimitDimension

Header

RemoteAddress

RateLimitRule

RateLimitValue

Unit

RateLimiting

Redirect

Route

ServerTLSSettings

TLSMode

StringMatch

Subject

JWTClaims

TLSPassthroughServer