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 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.HTTP One or more HTTP or HTTPS servers exposed by the gateway. The server exposes configuration for TLS termination, request authentication/authorization, HTTP routing, rate limiting, etc.	–
tls	List of tetrateio.api.tsb.gateway.v2.TLS 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.TCP One or more non-HTTP and non-passthrough servers which use TCP based protocols. This server also exposes configuration for terminating TLS.	–
wasmPlugins	List of tetrateio.api.tsb.types.v2.WasmExtensionAttachment WasmPlugins specifies all the WasmExtensionAttachment assigned to this Gateway with the specific configuration for each plugin. This custom configuration will override the one configured globally to the plugin. Each plugin has a global configuration including priority that will condition the execution of the assigned plugins.	–
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.	–

HTTP

HTTP describes the properties of a HTTP server exposed on gateway.

Field	Description	Validation 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 The port where the server is exposed at the gateway workload(pod). If the k8s service, which is fronting the workload pod, has TargetPort as 8443 for the Port 443, this could be configured as 8443 or 443. 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 transit flag is set to true, populating the port will lead to an error, as the server is considered internal to the mesh. TSB will automatically configure mTLS port(15443) for east-west multicluster traffic.	uint32 = {   lte: 65535   not_in: 15443 }
hostname	string REQUIRED Hostname with which the service can be expected to be accessed by clients.	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. If the transit flag is set to true, populating the tls will lead to an error, as the server is considered internal to the mesh. Gateway uses Istio mutual TLS to secure the connection for forwarding the traffic.	–
authentication	tetrateio.api.tsb.auth.v2.Authentication Authentication is used to configure the authentication of end-user credentials like JWT. It is highly recommended to configure this with TLS	–
authorization	tetrateio.api.tsb.auth.v2.Authorization Authorization is used to configure authorization of end users. It is highly recommended to configure this with TLS 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 disableExternalAuthorization on individual HTTP route rules.	–
routing	tetrateio.api.tsb.gateway.v2.HttpRoutingConfig REQUIRED Routing rules associated with HTTP traffic to this server.	message = {   required: true }
rateLimiting	tetrateio.api.tsb.gateway.v2.RateLimiting Configuration for rate limiting requests. This configuration is namespaced to a particular HttpServer.	–
transit	bool If set to true, the server is configured to be exposed within the mesh. This configuration enables forwarding traffic between two clusters that are not directly reachable.	–

HttpRouteRule

A single HTTP rule.

Field	Description	Validation 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.RouteTo 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.	–
disableExternalAuthorization	bool If set to true, external authorization is disabled on this route when the hostname is configured with external authorization.	–

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 Cross origin resource request policy settings for all routes.	–
rules	List of tetrateio.api.tsb.gateway.v2.HttpRouteRule REQUIRED HTTP routes.	repeated = {   min_items: 1 }

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 RouteToClusters represents the clusters where the request needs to be routed to from the gateway.	–
serviceDestination	tetrateio.api.tsb.gateway.v2.RouteToService oneof _destination RouteToService represents the service running in clusters.	–

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 The destination clusters that contain ingress gateways exposing the hostname.	–

RouteToService

RouteToService represents the service running in clusters.

Field	Description	Validation Rule
host	string REQUIRED The destination service in \<namespace\>/\<fqdn\>.	string = {   pattern: ^[^/]+/[^/]+$ }
port	uint32 The port on the service to forward the request to. Omit only if the destination service has only one port.	uint32 = {   lte: 65535   not_in: 15443 }
tls	tetrateio.api.tsb.auth.v2.ClientTLSSettings The ClientTLSSettings specifies how the gateway workload should establish connections to external services. This setting is intended for external services specifically. For normal mesh services, this should not be used, and the settings should be applied to the corresponding traffic/security groups instead.	–

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 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 The port where the server is exposed. Note that the port 15443 is reserved. Also beware of the conflict among the services using different protocols on the same port. The conflict occurs in the following scenarios Using plaintext and TLS (passthrough/termination) Mixing multiple protocols without TLS (HTTP and non-HTTP protocols like Kafka, Zookeeper etc) Multiple non-HTTP protocols without TLS Valid scenarios (for same port, multiple services) Multiple protocols (HTTP, non-HTTP) with TLS passthrough/termination Multiple HTTP services Single non-HTTP service without TLS If the transit flag is set to true, populating the port will lead to an error, as the server is considered internal to the mesh. TSB will automatically configure mTLS port(15443) for east-west multicluster traffic.	uint32 = {   lte: 65535   not_in: 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. If the transit flag is set to true, populating the tls will lead to an error, as the server is considered internal to the mesh. Gateway uses Istio mutual TLS to secure the connection for forwarding the traffic.	–
route	tetrateio.api.tsb.gateway.v2.RouteTo REQUIRED Forward the connection to the specified destination.	message = {   required: true }
transit	bool If set to true, the server is configured to be exposed within the mesh. This configuration enables forwarding traffic between two clusters that are not directly reachable.	–

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 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 (HTTP and HTTPS) should not share the same port. Note that port 15443 is reserved for internal use.	uint32 = {   lte: 65535   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:port" 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.RouteTo REQUIRED Forward the connection to the specified destination.	message = {   required: true }