Skip to main content
logoTetrate Service ExpressVersion: Latest

Ingress Gateway

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.

DEPRECATION: The functionality provided by the IngressGateway is now provided in Gateway object, and using it is the recommended approach. The IngressGateway resource will be removed in future releases.

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: tse
organization: tse
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:
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: IngressGateway
metadata:
name: ingress-bookinfo
group: g1
workspace: w1
tenant: tse
organization: tse
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 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: tse
organization: tse
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

The following example customizes the Extensions to enable the execution of the specified WasmExtensions list and details custom properties for the execution of each extension.

apiVersion: gateway.tsb.tetrate.io/v2
kind: IngressGateway
metadata:
name: ingress-bookinfo
group: g1
workspace: w1
tenant: tse
organization: tse
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
extension:
- fqn: hello-world # fqn of imported extensions in TSE config:
foo: bar
http:
- name: bookinfo
port: 80
hostname: bookinfo.com
routing:
rules:
- route:
host: ns1/productpage.ns1.svc.cluster.local

`IngressGateway` also allows you to apply ModSecurity/Coraza compatible Web
Application Firewall rules to traffic passing through the gateway.

```yaml
apiVersion: gateway.xcp.tetrate.io/v2
kind: IngressGateway
metadata:
name: waf-gw
namespace: ns1
labels:
app: waf-gateway
http:
- name: bookinfo
port: 9443
hostname: bookinfo.com
waf:
rules:
- Include @recommended-conf
- SecResponseBodyAccess Off
- Include @owasp_crs/*.conf

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

extension

List of tetrateio.api.tsb.types.v2.WasmExtensionAttachment
Extensions specifies all the WasmExtensions assigned to this IngressGateway with the specific configuration for each extension. This custom configuration will override the one configured globally to the extension. Each extension has a global configuration including enablement and priority that will condition the execution of the assigned extensions.

waf

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

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.

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.

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
}