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 either to destination clusters, such as a Tier1Gateway
,
or to specific services, like 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
This configuration defines a Gateway named egress-access
intended for egress traffic management.
It operates within the namespace ns
and targets pods labeled with app: egressgateway
.
The Gateway exposes three external hosts for egress access: example.com
, httpbin.org
, and apis.google.com
.
By default, egress access is denied for all three hosts. Users must explicitly define allow rules for traffic to pass through.
Clients in the cluster-1/client
namespace are granted access to the example.com
host.
Clients in the cluster-2/client
namespace can access httpbin.org
.
However, access to apis.google.com
is denied for all clients.
apiVersion: gateway.tsb.tetrate.io/v2
kind: Gateway
metadata:
name: egress-access
labels:
xcp.tetrate.io/workspace: egress-ws
xcp.tetrate.io/gatewayGroup: egress-gw-group
spec:
workloadSelector:
namespace: ns
labels:
app: egressgateway
http:
- name: example
hostname: "example.com"
routing:
rules:
- route:
serviceDestination:
host: "ns/example.com"
tls:
mode: SIMPLE
files:
caCertificates: "/etc/ssl/certs/ca-certificates.crt"
- name: httpbin
hostname: "httpbin.org"
routing:
rules:
- route:
serviceDestination:
host: "ns/httpbin.org"
tls:
mode: SIMPLE
files:
caCertificates: "/etc/ssl/certs/ca-certificates.crt"
- name: apis
hostname: "apis.google.com"
routing:
rules:
- route:
serviceDestination:
host: "ns/apis.google.com"
tls:
mode: SIMPLE
files:
caCertificates: "/etc/ssl/certs/ca-certificates.crt"
egressAuthorization:
- from:
mode: SERVICE_ACCOUNT
serviceAccounts:
- "cluster-1/client/*"
to:
- host:
exact: "example.com"
- from:
mode: SERVICE_ACCOUNT
serviceAccounts:
- "cluster-2/client/*"
to:
- host:
exact: "httpbin.org"
TSB provides ways to extend the bundled functionality that comes in with envoy
using the extensions
field.
The following example shows a Gateway configuration in which the kong's
response-transformer
plugin is being used.
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
extensions:
kong:
plugins:
- name: response-transformer
priority: 999
config:
inline:
remove:
json:
- example-field
- name: custom-header-adder
priority: 1000
config:
inline:
request_header_to_add: example-header
pluginSource:
configMap: cm-containing-this-plugin-in-gw-install-ns
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.
Field | Description | Validation Rule |
---|---|---|
mode | tetrateio.api.tsb.gateway.v2.AuthorizationSettings.Mode Deprecated: use | – |
serviceAccounts | List of string
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 = { |
resources | List of string
| – |
EgressAuthorizationSettings
EgressAuthorizationSettings define rules for allowing specific service accounts to access external hosts. By default, when a host is configured for egress access on the Gateway, access is denied.
Field | Description | Validation Rule |
---|---|---|
from | tetrateio.api.tsb.gateway.v2.AuthorizationSettings | – |
to | List of tetrateio.api.tsb.gateway.v2.EgressAuthorizationSettings.HostDetails | – |
identityMatch | tetrateio.api.tsb.types.v2.IdentityMatch | – |
HostDetails
List of external hosts details.
Field | Description | Validation Rule |
---|---|---|
host | tetrateio.api.tsb.gateway.v2.StringMatch
| – |
paths | List of string | repeated = { |
methods | List of string | repeated = { |
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 either to destination clusters, such as a Tier1Gateway
,
or to specific services, like 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 | – |
egressAuthorization | List of tetrateio.api.tsb.gateway.v2.EgressAuthorizationSettings | – |
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 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 Deprecated: use | – |
trafficMode | tetrateio.api.tsb.gateway.v2.TrafficMode
| – |
failoverSettings | tetrateio.api.tsb.types.v2.FailoverSettings | – |
openapi | tetrateio.api.tsb.gateway.v2.OpenAPI | – |
extensions | tetrateio.api.tsb.types.v2.Extensions | – |
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 | – |
directResponse | tetrateio.api.tsb.gateway.v2.HTTPDirectResponse oneof _route_or_redirect | – |
disableExternalAuthorization | bool | – |
extensions | tetrateio.api.tsb.types.v2.Extensions | – |
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 = { |
OpenAPI
OpenAPI configuration for the HTTP server.
Field | Description | Validation Rule |
---|---|---|
fqn | string | – |
validation | tetrateio.api.tsb.gateway.v2.OpenAPI.Validation | – |
Validation
Validation options for the OpenAPI document.
Field | Description | Validation Rule |
---|---|---|
enabled | bool | – |
allowUndefined | bool | – |
pathPrefix | string | – |
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 If the | 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 Deprecated: use | – |
trafficMode | tetrateio.api.tsb.gateway.v2.TrafficMode
| – |
failoverSettings | tetrateio.api.tsb.types.v2.FailoverSettings | – |
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 = { |
failoverSettings | tetrateio.api.tsb.types.v2.FailoverSettings | – |
Mode
A shortcut for defining the common authorization patterns.
Field | Number | Description |
---|---|---|
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. |
TrafficMode
Traffic mode defines the type of configuration that has been configured on a Gateway server.
Field | Number | Description |
---|---|---|
AUTO | 0 | AUTO mode indicates that the type of configuration is automatically detected from the underlying Gateway deployment. |
INGRESS | 1 | INGRESS mode specifies the configuration for managing incoming traffic into the mesh. In this mode, the Gateway server is responsible for handling incoming requests from external sources and routing them to appropriate services within the mesh. |
EGRESS | 2 | EGRESS mode specifies the configuration for managing outgoing traffic from the mesh to external destinations. In this mode, the Gateway server controls traffic leaving the mesh and enforces policies and security measures for accessing external services. |
TRANSIT | 3 | TRANSIT mode specifies that the Gateway is configured to facilitate transit traffic between different clusters within the mesh that are not directly reachable. This mode enables forwarding of traffic between clusters via the Gateway, allowing communication between services deployed in separate clusters. |