Skip to main content
logoTetrate Service BridgeVersion: 1.5.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 and http port 9090. The port 9090 is configured to receive plaintext traffic and send a redirect to the https port 9443 (site-wide HTTP -> HTTPS redirection). At 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-plaintext
port: 9090
hostname: bookinfo.com
routing:
rules:
- redirect:
authority: bookinfo.com
port: 9443
redirectCode: 301
scheme: https
- 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.

The following example illustrates defining non-HTTP servers (based on TCP) with TLS termination. Here, kafka.myorg.internal uses non-HTTP protocol and listens on port 9000. The clients have to connect with TLS with the SNI kafka.myorg.internal. The TLS is terminated at the gateway and the traffic is routed to kafka.infra.svc.cluster.local:8000.

If subsets are defined in the ServiceRoute referencing kafka.infra.svc.cluster.local service, then it is also considered while routing.

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
tcp:
- name: kafka-gateway
hostname: kafka.myorg.internal
port: 9000
tls:
mode: SIMPLE
secretName: kafka-cred
route:
host: kafka.infra.svc.cluster.local
port: 8000

CorsPolicy

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

FieldDescriptionValidation 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

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

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

FieldDescriptionValidation 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

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

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

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

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

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

FieldDescriptionValidation 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

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

FieldDescriptionValidation 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 oneof _route_or_redirect
Forward the request to the specified destination(s). One of route or redirect must be specified.

redirect

tetrateio.api.tsb.gateway.v2.Redirect oneof _route_or_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.

FieldDescriptionValidation 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.auth.v2.Authentication
Configuration to authenticate clients.

authorization

tetrateio.api.tsb.auth.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.

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

tcp

List of tetrateio.api.tsb.gateway.v2.TCPServer
One or more non-HTTP and non-passthrough servers which use TCP based protocols. This server also exposes configuration for terminating TLS

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.

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

FieldDescriptionValidation 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

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

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

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

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

FieldDescriptionValidation 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

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

Route

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

FieldDescriptionValidation 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

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

FileSource

File path configuration of TLS keys and certificates.

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

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

TCPServer

A TCP server exposed in an ingress gateway. A TCP server may be used for any TCP based protocol. This is also used for the special case of a non-HTTP protocol requiring TLS termination at the gateway

FieldDescriptionValidation 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, TLS passthrough and TCP servers in a gateway.

string = {
  min_len: 1
}

port

uint32
REQUIRED
The port where the server is exposed. Two servers with different protocols can share the same port only when both of them use TLS (either terminated at the gateway or pass-through)

uint32 = {
  not_in: 0,15443
}

hostname

string
REQUIRED
Hostname to identify the service. When TLS is configured, clients have to use this as the Server Name Indication (SNI) for the TLS connection. When TLS is not configured (opaque TCP), this is used to identify the service traffic for defining routing configs. Usually, this is configured as the DNS name of the service. For instance, if clients access a zookeeper cluster as zk-1.myorg.internal then the hostname could be specified as zk-1.myorg.internal. This also helps easier identification in the configs.

This is also used in multicluster routing. In the previous example, clients within the mesh can also use zk-1.myorg.internal to access this service (provided authorization policy allows it)

string = {
  min_len: 1
}

tls

tetrateio.api.tsb.gateway.v2.ServerTLSSettings
TLS certificate info to terminate the TLS connection

route

tetrateio.api.tsb.gateway.v2.Route
Forward the connection to the specified destination.

TLSPassthroughServer

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

FieldDescriptionValidation 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, TCP 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
}

Unit

Units of time.

FieldNumberDescription

UNKNOWN

0

SECOND

1

MINUTE

2

HOUR

3

DAY

4

TLSMode

FieldNumberDescription

DISABLED

0

SIMPLE

1

MUTUAL

2