Skip to main content
Version: 0.9.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, rate limiting, 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://internal.example.com. They are then rate limited based on the remote address of the client and the x-user-id header value 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.
rateLimiting:
domain: abc
failOpen: false
rateLimitServerUri: grpcs://company.com/ratelimitapi
actions:
- remoteAddress
- requestHeaders:
headerName: x-user-id
descriptorKey: userid
routing:
rules:
- route:
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.

Authentication

FieldDescriptionValidation Rule

jwt

tetrateio.api.tsb.gateway.v2.Authentication.JWT

JWT

FieldDescriptionValidation 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

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

FieldDescriptionValidation Rule

uri

string

includeRequestHeaders

List of string

LocalAuthz

Authorize the request in Envoy based on the JWT claims.

FieldDescriptionValidation Rule

rules

List of tetrateio.api.tsb.gateway.v2.LocalAuthzRule

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.

HTTPRewrite

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

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

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

repeated = {
  min_items: 1
}

LocalAuthzRule

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.

FieldDescriptionValidation 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

FieldDescriptionValidation 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]}}
}

RateLimitAction

RateLimitAction

RateLimitAction is a set of conditions to match HTTP requests that should be rate limited, and emit a set of keys and values that will then be passed on to the rate limit server. The server is expected to make a rate limit decision based on these keys and values.

FieldDescriptionValidation Rule

sourceCluster

tetrateio.api.tsb.gateway.v2.RateLimitAction.SourceCluster
Rate limit on source envoy cluster.

destinationCluster

tetrateio.api.tsb.gateway.v2.RateLimitAction.DestinationCluster
Rate limit on destination envoy cluster.

remoteAddress

tetrateio.api.tsb.gateway.v2.RateLimitAction.RemoteAddress
Rate limit on remote address of client.

requestHeaders

tetrateio.api.tsb.gateway.v2.RateLimitAction.RequestHeaders
Rate limit on the value of certain request headers.

headerValueMatch

tetrateio.api.tsb.gateway.v2.RateLimitAction.HeaderValueMatch
Rate limit on the existence of certain request headers.

DestinationCluster

Emit as attribute, the destination envoy cluster to which traffic is bound to. The key-value is ("destination_cluster", "<routed target cluster>")

NameNumberDescription

HeaderValueMatch

Emit as attribute, 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

descriptorValue

string
The value to use in the descriptor entry.

string = {
  min_bytes: 1
}

expectMatch

google.protobuf.BoolValue
If set to true, the action will append a descriptor entry when the request matches the headers. If set to false, the action will append a descriptor entry when the request does not match the headers. The default value is true.

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.

RemoteAddress

Emit as attribute, the remote address of the client, extracted from a trusted X-Forwarded-For header. The key-value is ("remote_address", "<trusted address from x-forwarded-for>")

NameNumberDescription

RequestHeaders

Emit as attribute, 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
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
}

skipIfAbsent

bool
If set to true, Envoy skips the descriptor while calling rate limiting service when header is not present in the request. By default it skips calling the rate limiting service if this header is not present in the request.

SourceCluster

Emit as attribute, the source envoy cluster (corresponding to the --service-cluster flag value set by Istio). The key-value is ("source_cluster", "<local service cluster>")

NameNumberDescription

RateLimiting

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, etc. The rate limit backend 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.

FieldDescriptionValidation Rule

domain

string
The rate limit domain to use when calling the rate limit service.

string = {
  min_bytes: 1
}

failOpen

google.protobuf.BoolValue
If the rate limit service is unavailable, the request will fail if failOpen is set to false. Defaults to true.

rateLimitServerUri

string
The URI at which the rate limit server can be reached.

string = {
  min_bytes: 1
}

actions

List of tetrateio.api.tsb.gateway.v2.RateLimitAction
A set of rate limit actions to perform for traffic to this server.

repeated = {
  min_items: 1
}

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.

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

TLSMode

NameNumberDescription

DISABLED

0

SIMPLE

1

MUTUAL

2

StringMatch

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

FieldDescriptionValidation Rule

exact

string
Exact string match.

prefix

string
Prefix-based match.

regex

string
ECMAscript style regex-based match.

Subject

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.

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

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