Ingress Gateway

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

DEPRECATION: The functionality provided by the IngressGateway is now provided in Gateway object, and using it is the recommended approach. The IngressGateway resource will be removed in future releases.

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: tse
  organization: tse
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:
          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: IngressGateway
metadata:
  name: ingress-bookinfo
  group: g1
  workspace: w1
  tenant: tse
  organization: tse
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 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: tse
  organization: tse
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

The following example customizes the Extensions to enable the execution of the specified WasmExtensions list and details custom properties for the execution of each extension.

apiVersion: gateway.tsb.tetrate.io/v2
kind: IngressGateway
metadata:
  name: ingress-bookinfo
  group: g1
  workspace: w1
  tenant: tse
  organization: tse
spec:
  workloadSelector:
  namespace: ns1
  labels:
    app: gateway
  extension:
  - fqn: hello-world # fqn of imported extensions in TSE config:
      foo: bar
  http:
  - name: bookinfo
    port: 80
    hostname: bookinfo.com
    routing:
      rules:
      - route:
        host: ns1/productpage.ns1.svc.cluster.local

`IngressGateway` also allows you to apply ModSecurity/Coraza compatible Web
Application Firewall rules to traffic passing through the gateway.

```yaml
apiVersion: gateway.xcp.tetrate.io/v2
kind: IngressGateway
metadata:
  name: waf-gw
    namespace: ns1
    labels:
      app: waf-gateway
  http:
  - name: bookinfo
    port: 9443
    hostname: bookinfo.com
  waf:
    rules:
      - Include @recommended-conf
      - SecResponseBodyAccess Off
      - Include @owasp_crs/*.conf

HttpRouting

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.HttpRule REQUIRED HTTP routes.	repeated = {   min_items: 1 }

HttpRule

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

HttpServer

An HTTP server exposed in an ingress 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 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.auth.v2.Authentication Configuration to authenticate clients.	–
authorization	tetrateio.api.tsb.auth.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. This configuration is namespaced to a particular HttpServer	–

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

Route

One or more destinations in a local/remote cluster for the given request.

Field	Description	Validation 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.	–

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 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 can share the same port only when both of them use TLS (either terminated at the gateway or pass-through)	uint32 = {   not_in: 0,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	–
route	tetrateio.api.tsb.gateway.v2.Route Forward the connection to the specified destination.	–

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 REQUIRED A name assigned to the server. The name will be visible in the generated metrics. The name must be unique across all HTTP, TCP and TLS 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. Routing will be done based on SNI matches for this hostname. NOTE: The hostname 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.Route REQUIRED Forward the connection to the specified destination.	message = {   required: true }