Skip to main content
logoTetrate Service BridgeVersion: 1.8.x

Gateway

The Gateway configuration combines the functionalities of both the existing Tier1Gateway and IngressGateway, providing a unified approach for configuring a workload as a gateway in the mesh. Each server within the Gateway is configured to route requests to either destination clusters or services, but configuring one server to route requests to a destination cluster and another server to route requests to a service is not supported. To ensure consistency and compatibility, the Gateway configuration requires that all servers within the gateway either forward traffic to other clusters, similar to a Tier1Gateway, or route traffic to specific services, similar to an IngressGateway.

The following example declares a 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. Here, the gateway is configured in a manner similar to an existing IngressGateway with HTTP server.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Gateway
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:
rules:
jwt:
- issuer: https://accounts.google.com
jwksUri: https://www.googleapis.com/oauth2/v3/certs
- issuer: "auth.mycompany.com"
jwksUri: https://auth.mycompany.com/oauth2/jwks
authorization:
external:
uri: https://company.com/authz
includeRequestHeaders:
- Authorization # forwards the header to the authorization service.
routing:
rules:
- route:
serviceDestination:
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

In the following example, the clients are authenticated using an external OIDC provider using AUTHORIZATION_CODE grant type. Once the client request is authenticated, it gets forwarded to the productpage service in the backend. The access_token generated after client authentication is set as Bearer in request headers. The state of authentication is stored in cookies.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Gateway
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:
oidc:
grantType: AUTHORIZATION_CODE
clientId: "my-client"
clientTokenSecret: "my-secret"
redirectUri: https://httpbin.example.com/bearer
provider:
issuer: https://accounts.google.com
authorizationEndpoint: https://accounts.google.com/v1/authorize
tokenEndpoint: https://accounts.google.com/v1/token
jwksUri: https://www.googleapis.com/oauth2/v3/certs
authorization:
external:
uri: https://company.com/authz
includeRequestHeaders:
- Authorization # forwards the header to the authorization service.
routing:
rules:
- route:
serviceDestination:
host: ns1/productpage.ns1.svc.cluster.local

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 declares a gateway running on pods with app: gateway labels in the ns1 namespace. The gateway exposes host movieinfo.com on ports 8080, 8443 and kafka.internal on port 9000. Traffic for these hosts at the ports 8443 and 9000 are TLS terminated and forwarded over Istio mutual TLS to the ingress gateways hosting movieinfo.com host on clusters c3 for matching prefix v1 and c4 for matching v2, and the internal kafka.internal service in cluster c3 respectively. The server at port 8080 is configured to receive plaintext HTTP traffic and redirect to port 8443 with "Permanently Moved" (HTTP 301) status code. Here, the gateway is configured in a manner similar to an existing Tier1Gateway with external servers.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Gateway
metadata:
name: tier1
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
http:
- name: movieinfo-plain
hostname: movieinfo.com # Plaintext and HTTPS redirect
port: 8080
routing:
rules:
- redirect:
authority: movieinfo.com
port: 8443
redirectCode: 301
scheme: https
uri: "/"
- name: movieinfo
hostname: movieinfo.com # TLS termination and Istio mTLS to upstream
port: 8443
tls:
mode: SIMPLE
secretName: movieinfo-secrets
routing:
rules:
- match:
- uri:
prefix: "/v1"
route:
clusterDestination:
clusters:
- name: c3 # the target gateway IPs will be automatically determined
weight: 100
- match:
- uri:
prefix: "/v2"
route:
clusterDestination:
clusters:
- name: c4 # the target gateway IPs will be automatically determined
weight: 100
authentication:
rules:
jwt:
- issuer: "auth.mycompany.com"
jwksUri: https://auth.mycompany.com/oauth2/jwks
- issuer: "auth.othercompany.com"
jwksUri: https://auth.othercompany.com/oauth2/jwks
authorization:
external:
uri: "https://auth.company.com"
includeRequestHeaders:
- authorization
tcp:
- name: kafka
hostname: kafka.internal
port: 9000
tls:
mode: SIMPLE
secretName: kafka-cred
route:
clusterDestination:
clusters:
- name: c3
weight: 100

This example used to forward mesh internal traffic for Gateway hosts from one cluster to another. This form of forwarding will work only if the two clusters cannot reach each other directly (e.g., they are on different VPCs that are not peered). The following example declares a gateway running on pods with app: gateway labels in the ns1 namespace. The gateway exposes hosts movieinfo.com, bookinfo.com, and a non-HTTP server called kafka.org-internal within the mesh. Traffic to movieinfo.com is load balanced across all clusters on vpc-02, while traffic to bookinfo.com and kafka.org-internal is load balanced across ingress gateways exposing bookinfo.com on any cluster. Traffic from the source (sidecars) is expected to arrive on the tier1 gateway over Istio mTLS. Here, the gateway is configured in a manner similar to an existing Tier1Gateway with internal servers.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Gateway
metadata:
name: tier1
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
http: # forwarding gateway (HTTP traffic only)
- name: movieinfo
transit: true # server marked as internal
hostname: movieinfo.com
routing:
rules:
- route:
clusterDestination:
clusters:
- labels:
network: vpc-02 # the target gateway IPs will be automatically determined
authentication:
rules:
jwt:
- issuer: "auth.mycompany.com"
jwksUri: https://auth.company.com/oauth2/jwks
- issuer: "auth.othercompany.com"
jwksUri: https://auth.othercompany.com/oauth2/jwks
authorization:
meshInternalAuthz:
external:
uri: "https://auth.company.com"
includeRequestHeaders:
- authorization
- name: bookinfo
transit: true # server marked as internal
hostname: bookinfo.com # route to any ingress gateway exposing bookinfo.com
routing:
rules:
- route:
clusterDestination:
clusters:
tcp: # forwarding non-HTTP traffic within the mesh
- name: kafka
transit: true # server marked as internal
hostname: kafka.org-internal
route:
clusterDestination:
clusters:

The following example illustrates defining non-HTTP server (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: Gateway
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:
serviceDestination:
host: kafka.infra.svc.cluster.local
port: 8000

This is an example of configuring a gateway for TLS. The gateway will forward the passthrough server traffic to clusters c1 and c2. It is essential to configure TLS on the same hostname at c1 and c2 as well. Here, the gateway is configured similarly to an existing Tier1Gateway with passthrough servers.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Gateway
metadata:
name: tier1-tls-gw
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
tls:
- name: nginx
port: 8443
hostname: nginx.example.com
route:
clusterDestination:
clusters:
- name: c1 # the target gateway IPs will be automatically determined
weight: 90
- name: c2
weight: 10

AuthorizationSettings

AuthorizationSettings define the set of service accounts in one or more namespaces allowed to access a workload (and hence its sidecar) in the mesh.

FieldDescriptionValidation Rule

mode

tetrateio.api.tsb.gateway.v2.AuthorizationSettings.Mode
REQUIRED
A shortcut for specifying the set of allowed callers.

serviceAccounts

List of string
When the mode is SERVICE_ACCOUNT, serviceAccounts specify the allowed set of service accounts (and the workloads using them). Must be in the \<namespace\>/\<service-account-name\> format.

  • ./* indicates all service accounts in the namespace where the sidecar resides.

  • ns1/* indicates all service accounts in the ns1 namespace.

  • ns1/svc1-sa indicates svc1-sa service account in ns1 namespace.

Namespace should be a valid Kubernetes namespace, which follows RFC 1123 Label Names rules. Service account should be a valid Kubernetes service account, which follows DNS Subdomain Names rules.

repeated = {
  items: {string:{pattern:^\\./\\*$|^[^.*]+/[*]{1}$|^[^.*]+/[^*]+$}}
}

EgressAuthorizationSettings

EgressAuthorizationSettings is primarily used to define rules specifying which service accounts can access a set of external hosts from within the mesh.

FieldDescriptionValidation Rule

from

tetrateio.api.tsb.gateway.v2.AuthorizationSettings
Specifies the source workloads or service accounts for this authorization rule.

to

List of tetrateio.api.tsb.gateway.v2.EgressAuthorizationSettings.HostDetails
REQUIRED
The set of hostnames exposed on the Gateway through which external hosts can be accessed.

HostDetails

List of external hosts details.

FieldDescriptionValidation Rule

host

string
External host. Users will onboard external service into the mesh via service entry, and the same service will be exposed on the Gateway for egress access.

string = {
  min_len: 1
  not_in:
}

paths

List of string
The request paths allowed for access, e.g., ["/accounts", "/info*", "/user/profile/*"]. Exact and prefix-based regular matches are supported. If not set, any path is allowed.

repeated = {
  items: {string:{min_len:1}}
}

methods

List of string
The HTTP methods allowed by this rule, e.g., ["GET", "HEAD"]. If not set, any method is allowed.

repeated = {
  items: {string:{in:[GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS]}}
}

Gateway

The Gateway configuration combines the functionalities of both the existing Tier1Gateway and IngressGateway, providing a unified approach for configuring a workload as a gateway in the mesh.

Each server within the Gateway is configured to route requests to either destination clusters or services, but configuring one server to route requests to a destination cluster and another server to route requests to a service is not supported.

To ensure consistency and compatibility, the Gateway configuration requires that all servers within the gateway either forward traffic to other clusters, similar to a Tier1Gateway, or route traffic to specific services, similar to an IngressGateway.

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.HTTP
One or more HTTP or HTTPS servers exposed by the gateway. The server exposes configuration for TLS termination, request authentication/authorization, HTTP routing, rate limiting, etc.

tls

List of tetrateio.api.tsb.gateway.v2.TLS
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.TCP
One or more non-HTTP and non-passthrough servers which use TCP based protocols. This server also exposes configuration for terminating TLS.

wasmPlugins

List of tetrateio.api.tsb.types.v2.WasmExtensionAttachment
WasmPlugins specifies all the WasmExtensionAttachment assigned to this Gateway with the specific configuration for each plugin. This custom configuration will override the one configured globally to the plugin. Each plugin has a global configuration including priority that will condition the execution of the assigned plugins.

waf

tetrateio.api.tsb.security.v2.WAFSettings
WAF settings to be enabled for traffic passing through the HttpServer.

egressAuthorization

List of tetrateio.api.tsb.gateway.v2.EgressAuthorizationSettings
EgressAuthorizationSettings contains rules specifying which service accounts can access specific external hosts from within the mesh. Users will onboard external services into the mesh via service entry, and the same services will be exposed on the Gateway for egress access.

configGenerationMetadata

tetrateio.api.tsb.types.v2.ConfigGenerationMetadata
Metadata values that will be add into the Istio generated configurations. When using YAML APIs liketctl or gitops, put them into the metadata.labels or metadata.annotations instead. This field is only necessary when using gRPC APIs directly.

HTTP

HTTP describes the properties of a HTTP server exposed on 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
The port where the server is exposed at the gateway workload(pod). If the k8s service, which is fronting the workload pod, has TargetPort as 8443 for the Port 443, this could be configured as 8443 or 443.

Two servers with different protocols (HTTP and HTTPS) should not share the same port. Note that port 15443 is reserved for internal use.

If the transit flag is set to true, populating the port will lead to an error, as the server is considered internal to the mesh. TSB will automatically configure mTLS port(15443) for east-west multicluster traffic.

uint32 = {
  lte: 65535
  not_in: 15443
}

hostname

string
REQUIRED
Hostname with which the service can be expected to be accessed by clients.

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. If the transit flag is set to true, populating the tls will lead to an error, as the server is considered internal to the mesh. Gateway uses Istio mutual TLS to secure the connection for forwarding the traffic.

authentication

tetrateio.api.tsb.auth.v2.Authentication
Authentication is used to configure the authentication of end-user credentials like JWT. It is highly recommended to configure this with TLS

authorization

tetrateio.api.tsb.auth.v2.Authorization
Authorization is used to configure authorization of end users. It is highly recommended to configure this with TLS

If external authorization is configured, authorization is evaluated for each HTTP path by default. Users can exclude authorization on specific paths by setting the flag disableExternalAuthorization on individual HTTP route rules.

routing

tetrateio.api.tsb.gateway.v2.HttpRoutingConfig
REQUIRED
Routing rules associated with HTTP traffic to this server.

message = {
  required: true
}

rateLimiting

tetrateio.api.tsb.gateway.v2.RateLimiting
Configuration for rate limiting requests. This configuration is namespaced to a particular HttpServer.

transit

bool
If set to true, the server is configured to be exposed within the mesh. This configuration enables forwarding traffic between two clusters that are not directly reachable.

HttpRouteRule

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

directResponse

tetrateio.api.tsb.gateway.v2.HTTPDirectResponse oneof _route_or_redirect
Return a fixed response. One of route, redirect, or direct_response must be specified.

disableExternalAuthorization

bool
If set to true, external authorization is disabled on this route when the hostname is configured with external authorization.

HttpRoutingConfig

HttpRoutingConfig defines a list of HTTP route rules that determine how incoming requests are routed.

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.HttpRouteRule
REQUIRED
HTTP routes.

repeated = {
  min_items: 1
}

RouteTo

RouteTo defines the how the traffic has been forwarded for the given request. One of ClusterDestination or ServiceDestination must be specified.

FieldDescriptionValidation Rule

clusterDestination

tetrateio.api.tsb.gateway.v2.RouteToClusters oneof _destination
RouteToClusters represents the clusters where the request needs to be routed to from the gateway.

serviceDestination

tetrateio.api.tsb.gateway.v2.RouteToService oneof _destination
RouteToService represents the service running in clusters.

RouteToClusters

RouteToClusters represents the clusters where the request needs to be routed to from the gateway.

FieldDescriptionValidation Rule

clusters

List of tetrateio.api.tsb.gateway.v2.ClusterDestination
The destination clusters that contain ingress gateways exposing the hostname.

RouteToService

RouteToService represents the service running in clusters.

FieldDescriptionValidation Rule

host

string
REQUIRED
The destination service in \<namespace\>/\<fqdn\>.

string = {
  pattern: ^[^/]+/[^/]+$
}

port

uint32
The port on the service to forward the request to. Omit only if the destination service has only one port.

uint32 = {
  lte: 65535
  not_in: 15443
}

tls

tetrateio.api.tsb.auth.v2.ClientTLSSettings
The ClientTLSSettings specifies how the gateway workload should establish connections to external services. This setting is intended for external services specifically. For normal mesh services, this should not be used, and the settings should be applied to the corresponding traffic/security groups instead.

TCP

A TCP server exposed in a 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
The port where the server is exposed. Note that the port 15443 is reserved. Also beware of the conflict among the services using different protocols on the same port. The conflict occurs in the following scenarios

  1. Using plaintext and TLS (passthrough/termination)
  2. Mixing multiple protocols without TLS (HTTP and non-HTTP protocols like Kafka, Zookeeper etc)
  3. Multiple non-HTTP protocols without TLS

Valid scenarios (for same port, multiple services)

  1. Multiple protocols (HTTP, non-HTTP) with TLS passthrough/termination
  2. Multiple HTTP services
  3. Single non-HTTP service without TLS

If the transit flag is set to true, populating the port will lead to an error, as the server is considered internal to the mesh. TSB will automatically configure mTLS port(15443) for east-west multicluster traffic.

uint32 = {
  lte: 65535
  not_in: 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. If the transit flag is set to true, populating the tls will lead to an error, as the server is considered internal to the mesh. Gateway uses Istio mutual TLS to secure the connection for forwarding the traffic.

route

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

message = {
  required: true
}

transit

bool
If set to true, the server is configured to be exposed within the mesh. This configuration enables forwarding traffic between two clusters that are not directly reachable.

TLS

A TLS server exposed in a gateway. For TLS servers, the gateways do not 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, 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 (HTTP and HTTPS) should not share the same port. Note that port 15443 is reserved for internal use.

uint32 = {
  lte: 65535
  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:port" 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.RouteTo
REQUIRED
Forward the connection to the specified destination.

message = {
  required: true
}

Mode

A shortcut for defining the common authorization patterns.

FieldNumberDescription

UNSET

0

Represents an unset or default mode.

NAMESPACE

1

The workload allows traffic from any other authenticated workload in its own namespace.

GROUP

2

The workload allows traffic from any other authenticated workload in the security group.

WORKSPACE

3

The workload allows traffic from any other authenticated workload in the workspace.

CLUSTER

4

The workload allows traffic from any other authenticated workload in the cluster.

SERVICE_ACCOUNT

5

The workload allows traffic from service accounts defined explicitly.