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
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
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
.
Field | Description | Validation Rule |
---|---|---|
workloadSelector | tetrateio.api.tsb.types.v2.WorkloadSelector | message = { |
http | List of tetrateio.api.tsb.gateway.v2.HTTP | – |
tls | List of tetrateio.api.tsb.gateway.v2.TLS | – |
tcp | List of tetrateio.api.tsb.gateway.v2.TCP | – |
wasmPlugins | List of tetrateio.api.tsb.types.v2.WasmExtensionAttachment | – |
waf | tetrateio.api.tsb.security.v2.WAFSettings | – |
configGenerationMetadata | tetrateio.api.tsb.types.v2.ConfigGenerationMetadata | – |
HTTP
HTTP
describes the properties of a HTTP server exposed on gateway.
Field | Description | Validation Rule |
---|---|---|
name | string | string = { |
port | uint32 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 | 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 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
| – |
routing | tetrateio.api.tsb.gateway.v2.HttpRoutingConfig | message = { |
rateLimiting | tetrateio.api.tsb.gateway.v2.RateLimiting | – |
transit | bool | – |
HttpRouteRule
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.RouteTo oneof _route_or_redirect | – |
redirect | tetrateio.api.tsb.gateway.v2.Redirect oneof _route_or_redirect | – |
disableExternalAuthorization | bool | – |
HttpRoutingConfig
HttpRoutingConfig
defines a list of HTTP route rules that determine how incoming requests are routed.
Field | Description | Validation Rule |
---|---|---|
corsPolicy | tetrateio.api.tsb.gateway.v2.CorsPolicy | – |
rules | List of tetrateio.api.tsb.gateway.v2.HttpRouteRule | repeated = { |
RouteTo
RouteTo defines the how the traffic has been forwarded for the given request.
One of ClusterDestination
or ServiceDestination
must be specified.
Field | Description | Validation Rule |
---|---|---|
clusterDestination | tetrateio.api.tsb.gateway.v2.RouteToClusters oneof _destination | – |
serviceDestination | tetrateio.api.tsb.gateway.v2.RouteToService oneof _destination | – |
RouteToClusters
RouteToClusters represents the clusters where the request needs to be routed to from the gateway.
Field | Description | Validation Rule |
---|---|---|
clusters | List of tetrateio.api.tsb.gateway.v2.ClusterDestination | – |
RouteToService
RouteToService represents the service running in clusters.
Field | Description | Validation Rule |
---|---|---|
host | string | string = { |
port | uint32 | uint32 = { |
tls | tetrateio.api.tsb.auth.v2.ClientTLSSettings | – |
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.
Field | Description | Validation Rule |
---|---|---|
name | string | string = { |
port | uint32
Valid scenarios (for same port, multiple services)
If the | 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.RouteTo | message = { |
transit | bool | – |
TLS
A TLS server exposed in a gateway. For TLS servers, the gateways do not 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.RouteTo | message = { |