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
Field | Description | Validation Rule |
---|---|---|
allowOrigin | List of string | – |
allowMethods | List of string | – |
allowHeaders | List of string | – |
exposeHeaders | List of string | – |
maxAge | google.protobuf.Duration | – |
allowCredentials | google.protobuf.BoolValue | – |
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.
Field | Description | Validation Rule |
---|---|---|
domain | string | string = { |
failClosed | bool | – |
rateLimitServerUri | string | string = { |
rules | List of tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitRule | repeated = { |
timeout | google.protobuf.Duration | – |
tls | tetrateio.api.tsb.auth.v2.ClientTLSSettings | – |
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
Field | Description | Validation Rule |
---|---|---|
sourceCluster | tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.SourceCluster oneof _dimension_specifier | – |
destinationCluster | tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.DestinationCluster oneof _dimension_specifier | – |
remoteAddress | tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RemoteAddress oneof _dimension_specifier | – |
requestHeaders | tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.RequestHeaders oneof _dimension_specifier | – |
headerValueMatch | tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension.HeaderValueMatch oneof _dimension_specifier | – |
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.
Field | Description | Validation Rule |
---|---|---|
headers | map<string, tetrateio.api.tsb.gateway.v2.StringMatch> | map = { |
descriptorValue | string | string = { |
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.
Field | Description | Validation Rule |
---|---|---|
headerName | string | string = { |
descriptorKey | string | string = { |
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
Field | Description | Validation Rule |
---|---|---|
dimensions | List of tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings.RateLimitDimension | repeated = { |
HTTPRewrite
Configuration for an URL rewrite rule.
Field | Description | Validation Rule |
---|---|---|
uri | string | – |
authority | string | – |
Headers
Header manipulation rules.
Field | Description | Validation Rule |
---|---|---|
request | tetrateio.api.tsb.gateway.v2.Headers.HeaderOperations | – |
response | tetrateio.api.tsb.gateway.v2.Headers.HeaderOperations | – |
HeaderOperations
HeaderOperations Describes the header manipulations to apply.
Field | Description | Validation Rule |
---|---|---|
set | map<string, string> | – |
add | map<string, string> | – |
remove | List of string | – |
HttpMatchCondition
A single match clause to match all aspects of a request.
Field | Description | Validation Rule |
---|---|---|
uri | tetrateio.api.tsb.gateway.v2.StringMatch | – |
headers | map<string, tetrateio.api.tsb.gateway.v2.StringMatch> | – |
HttpModifyAction
HTTP path/url/header modification.
Field | Description | Validation Rule |
---|---|---|
rewrite | tetrateio.api.tsb.gateway.v2.HTTPRewrite | – |
headers | tetrateio.api.tsb.gateway.v2.Headers | – |
HttpRouting
Field | Description | Validation Rule |
---|---|---|
corsPolicy | tetrateio.api.tsb.gateway.v2.CorsPolicy | – |
rules | List of tetrateio.api.tsb.gateway.v2.HttpRule | repeated = { |
HttpRule
A single HTTP rule.
Field | Description | Validation Rule |
---|---|---|
match | List of tetrateio.api.tsb.gateway.v2.HttpMatchCondition | – |
modify | tetrateio.api.tsb.gateway.v2.HttpModifyAction | – |
route | tetrateio.api.tsb.gateway.v2.Route oneof _route_or_redirect | – |
redirect | tetrateio.api.tsb.gateway.v2.Redirect oneof _route_or_redirect | – |
HttpServer
An HTTP server exposed in an ingress gateway.
Field | Description | Validation Rule |
---|---|---|
name | string | string = { |
port | uint32 | uint32 = { |
hostname | string | string = { |
tls | tetrateio.api.tsb.gateway.v2.ServerTLSSettings | – |
authentication | tetrateio.api.tsb.auth.v2.Authentication | – |
authorization | tetrateio.api.tsb.auth.v2.Authorization | – |
routing | tetrateio.api.tsb.gateway.v2.HttpRouting | message = { |
rateLimiting | tetrateio.api.tsb.gateway.v2.RateLimiting | – |
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 | message = { |
http | List of tetrateio.api.tsb.gateway.v2.HttpServer | – |
tlsPassthrough | List of tetrateio.api.tsb.gateway.v2.TLSPassthroughServer | – |
tcp | List of tetrateio.api.tsb.gateway.v2.TCPServer | – |
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 | repeated = { |
failClosed | bool | – |
timeout | google.protobuf.Duration | – |
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 oneof _dimension_specifier | – |
header | tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitDimension.Header oneof _dimension_specifier | – |
Header
RateLimit based on certain headers
Field | Description | Validation Rule |
---|---|---|
name | string | string = { |
value | tetrateio.api.tsb.gateway.v2.StringMatch | – |
RemoteAddress
RateLimit based on the client's remote address, extracted from the trusted X-Forwarded-For header.
Field | Description | Validation Rule |
---|---|---|
value | string | string = { |
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 | repeated = { |
limit | tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitValue | message = { |
RateLimitValue
RateLimitValue specifies the values that will be used to determine the rate limit.
Field | Description | Validation Rule |
---|---|---|
requestsPerUnit | uint32 | – |
unit | tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitValue.Unit | enum = { |
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 oneof _ratelimit_specifier | – |
externalService | tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings oneof _ratelimit_specifier | – |
Redirect
Field | Description | Validation Rule |
---|---|---|
uri | string | – |
authority | string | – |
redirectCode | uint32 | – |
port | uint32 | – |
scheme | string | – |
Route
One or more destinations in a local/remote cluster for the given request.
Field | Description | Validation Rule |
---|---|---|
host | string | string = { |
port | uint32 | – |
ServerTLSSettings
Field | Description | Validation Rule |
---|---|---|
mode | tetrateio.api.tsb.gateway.v2.ServerTLSSettings.TLSMode | – |
secretName | string | – |
files | tetrateio.api.tsb.gateway.v2.ServerTLSSettings.FileSource | – |
FileSource
File path configuration of TLS keys and certificates.
Field | Description | Validation Rule |
---|---|---|
serverCertificate | string | – |
privateKey | string | – |
caCertificates | string | – |
StringMatch
Describes how to match a given string in HTTP headers. Match is case-sensitive.
Field | Description | Validation Rule |
---|---|---|
exact | – | |
prefix | – | |
regex | string oneof _match_type | – |
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
Field | Description | Validation Rule |
---|---|---|
name | string | string = { |
port | uint32 | uint32 = { |
hostname | string This is also used in multicluster routing. In the previous example, clients within the mesh
can also use | string = { |
tls | tetrateio.api.tsb.gateway.v2.ServerTLSSettings | – |
route | tetrateio.api.tsb.gateway.v2.Route | – |
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 | string = { |
port | uint32 | uint32 = { |
hostname | string | string = { |
route | tetrateio.api.tsb.gateway.v2.Route | message = { |
Unit
Units of time.
Field | Number | Description |
---|---|---|
UNKNOWN | 0 | |
SECOND | 1 | |
MINUTE | 2 | |
HOUR | 3 | |
DAY | 4 |
TLSMode
Field | Number | Description |
---|---|---|
DISABLED | 0 | |
SIMPLE | 1 | |
MUTUAL | 2 |