Skip to main content
Version: 1.5.x

Tier1 Gateway

Tier1Gateway configures a workload to act as a gateway that distributes traffic across one or more ingress gateways in other clusters.

NOTE: Tier1 gateways cannot be used to route traffic to the same cluster. A cluster with tier1 gateway cannot have any other gateways or workloads.

The following example declares a tier1 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 and c4 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.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Tier1Gateway
metadata:
name: tier1
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
externalServers:
- name: movieinfo-plain
hostname: movieinfo.com # Plaintext and HTTPS redirect
port: 8080
redirect:
authority: movieinfo.com
url: "/"
redirectCode: 301
port: 8443
scheme: https
- name: movieinfo
hostname: movieinfo.com # TLS termination and Istio mTLS to upstream
port: 8443
tls:
mode: SIMPLE
secretName: movieinfo-secrets
clusters:
- name: c3 # the target gateway IPs will be automatically determined
weight: 90
- name: c4
weight: 10
authentication:
jwt:
issuer: "auth.mycompany.com"
jwksUri: https://auth.company.com/oauth2/jwks
authorization:
external:
uri: "https://auth.company.com"
includeRequestHeaders:
- authorization
tcpExternalServers:
- name: kafka
hostname: kafka.internal
port: 9000
tls:
mode: SIMPLE
secretName: kafka-cred
clusters:
- name: c3
weight: 100

Tier1 gateways can also be 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 tier1 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.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Tier1Gateway
metadata:
name: tier1
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
internalServers: # forwarding gateway (HTTP traffic only)
- name: movieinfo
hostname: movieinfo.com
clusters:
- network: vpc-02 # the target gateway IPs will be automatically determined
authentication:
jwt:
issuer: "auth.mycompany.com"
jwksUri: https://auth.company.com/oauth2/jwks
authorization:
external:
uri: "https://auth.company.com"
includeRequestHeaders:
- authorization
- name: bookinfo
hostname: bookinfo.com # route to any ingress gateway exposing bookinfo.com
tcpInternalServers: # forwarding non-HTTP traffic within the mesh
- name: kafka
hostname: kafka.org-internal

NOTE: If two clusters have direct connectivity, declaring a tier1 internal server will have no effect.

Tier1 gateways can also be configured to expose hostnames in the TLS passthrough mode. Tier1 gateway will forward the pasthrough server traffic to any tier2 pass through servers exposing the same hostname. In other words, To be able to leverage passthrough at tier1, it is a MUST that passthrough is configured at t2 IngressGateway as well.

NOTE: A hostname like abc.com can only be exposed either in passthrough mode OR in terminating tls mode(External/Internal servers), not in both the modes.

apiVersion: gateway.tsb.tetrate.io/v2
kind: Tier1Gateway
metadata:
name: tier1-tls-gw
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
passthroughServers:
- name: nginx
port: 8443
hostname: nginx.example.com

The Tier1Gateway above will require the corresponding, at least one or more, IngressGateway(s), e.g.:

apiVersion: gateway.tsb.tetrate.io/v2
kind: IngressGateway
metadata:
name: tls-gw
group: g1
workspace: w1
tenant: mycompany
organization: myorg
spec:
workloadSelector:
namespace: ns1
labels:
app: gateway
tlsPassthrough:
- name: nginx
port: 443
hostname: nginx.example.com
route:
host: "ns1/my-nginx.default.svc.cluster.local"
port: 443

Whenever traffic is to be sent from one cluster to another, one or more of the following would have to be true for it to succeed:

  • Both clusters belong to the same network.
  • Destination cluster network is not named.
  • Organization Setting is set up to send traffic from source cluster to destination cluster.

ClusterDestination

FieldDescriptionValidation Rule

name

string
The name of the destination cluster. Only one of name or labels must be specified.

labels

map<string, string>
Labels associated with the cluster. Any cluster with matching labels will be selected as a target. Only one of name or labels must be specified.

network

string
The network associated with the destination clusters. In addition to name/label selectors, only clusters matching the selected networks will be used as a target. At least one of name/labels, and/or network must be specified.

weight

uint32
The weight for traffic to a given destination.

Tier1ExternalServer

Tier1ExternalServer describes the properties of a server exposed outside the mesh. Traffic arriving at a Tier1 external server is usually TLS terminated and then forwarded over Istio mTLS to all the lower tier2 clusters.

FieldDescriptionValidation 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 external servers in the gateway.

string = {
  min_len: 1
}

port

uint32
REQUIRED
The port where the server is exposed. Note that port 15443 is reserved.

uint32 = {
  not_in: 0,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. The gateway will terminate the TLS connection and forward it to the upstream ingress gateway using Istio mutual TLS on port 15443.

clusters

List of tetrateio.api.tsb.gateway.v2.ClusterDestination
The destination clusters that contain ingress gateways exposing the hostname. If omitted, traffic will be automatically load balanced across all tier2 clusters whose ingress gateways expose the above hostname. If redirect is configured then this field cannot be configured.

redirect

tetrateio.api.tsb.gateway.v2.Redirect
Redirect allows configuring HTTP redirect. When this is configured, the clusters field cannot be configured.

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

rateLimiting

tetrateio.api.tsb.gateway.v2.RateLimiting
Configuration for rate limiting requests. This configuration is namespaced to a Tier1ExternalServer

Tier1Gateway

Tier1Gateway configures a workload to act as a tier1 gateway into the mesh.

FieldDescriptionValidation 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
}

externalServers

List of tetrateio.api.tsb.gateway.v2.Tier1ExternalServer
One or more servers exposed by the gateway externally.

internalServers

List of tetrateio.api.tsb.gateway.v2.Tier1InternalServer
One or more servers exposed by the gateway internally for cross cluster forwarding.

passthroughServers

List of tetrateio.api.tsb.gateway.v2.Tier1PassthroughServer
One or more tls passthrough servers exposed by the gateway externally.

tcpExternalServers

List of tetrateio.api.tsb.gateway.v2.Tier1TCPExternalServer
One or more tcp servers exposed by the gateway externally.

tcpInternalServers

List of tetrateio.api.tsb.gateway.v2.Tier1TCPInternalServer
One or more tcp servers exposed by the gateway for mesh internal traffic.

Tier1InternalServer

Tier1InternalServer describes the properties of a server exposed within the mesh, for the purposes of forwarding traffic between two clusters that cannot otherwise directly reach each other. Traffic arriving at a Tier1 internal server should be over Istio mTLS. After TLS termination and metrics extraction, it is forwarded to tier2 clusters based on the selection criteria.

FieldDescriptionValidation 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 internal servers in the gateway.

string = {
  min_len: 1
}

hostname

string
REQUIRED
Hostname with which the service can be expected to be accessed by sidecars in the mesh.

string = {
  min_len: 1
}

clusters

List of tetrateio.api.tsb.gateway.v2.ClusterDestination
The destination clusters that contain ingress gateways exposing the hostname. If omitted, traffic will be automatically load balanced across all tier2 clusters whose ingress gateways expose the above hostname.

authentication

tetrateio.api.tsb.auth.v2.Authentication
Authentication is used to configure the authentication of end-user credentials like JWT.

authorization

tetrateio.api.tsb.auth.v2.Authorization
Authorization is used to configure authorization of end user and traffic.

Tier1PassthroughServer

Tier1PassthroughServer describes the properties of a server exposed to the external world. Traffic arriving at a Tier1 passthrough server is not TLS terminated and rather forwarded over to all the lower tier2 clusters.

FieldDescriptionValidation 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 external servers in the gateway.

string = {
  min_len: 1
}

port

uint32
REQUIRED
The port where the server is exposed. Note that port 15443 is reserved.

uint32 = {
  not_in: 0,15443
}

hostname

string
REQUIRED
Hostname with which the service can be expected to be accessed by clients.

string = {
  min_len: 1
}

clusters

List of tetrateio.api.tsb.gateway.v2.ClusterDestination
The destination clusters that contain ingress gateways exposing the hostname on passthrough servers. If omitted, traffic will be automatically load balanced across all tier2 clusters whose ingress gateways expose the above hostname.

Tier1TCPExternalServer

Tier1TCPExternalServer is used to describe the properties of a TCP server (used for opaque TCP or non-HTTP protocols) exposed to the external world. If the protocol is known to be HTTP, then please use externalServers as it allows using HTTP-specific features.

Caveat - Currently, we don't support multicluster routing when Tier2 gateway settings are specified in the direct mode for TCP services. So please use the bridged mode.

FieldDescriptionValidation Rule

name

string
REQUIRED
A name assigned to the server. This name is used in the generated metrics. The name must be unique across all TCP servers in the gateway

string = {
  min_len: 1
}

port

uint32
REQUIRED
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 1. Using plaintext and TLS (passthrough/termination) 2. Mixing multiple protocols without TLS (HTTP and non-HTTP protocols like Kafka, Zookeeper etc) 3. Multiple non-HTTP protocols without TLS

Valid scenarios (for same port, multiple services) 1. Multiple protocols (HTTP, non-HTTP) with TLS passthrough/termination 2. Multiple HTTP services 3. Single non-HTTP service without TLS

Note on service port - If a service is exposed on port 6789 in the tier1 gateway, then it must be exposed on the same port with the same hostname (without wildcard) in the tier2 gateway as well.

uint32 = {
  not_in: 0,15443
}

hostname

string
REQUIRED
Although hostname or authority does not make sense in the non-HTTP context, this is used to define the routing rules. Wildcard hostnames are not yet supported.

string = {
  min_len: 1
}

clusters

List of tetrateio.api.tsb.gateway.v2.ClusterDestination
The destination clusters contain ingress gateways exposing the service.

tls

tetrateio.api.tsb.gateway.v2.ServerTLSSettings
TLS certificate information to terminate TLS. If passthrough is required, then please use passthroughServers to specify them.

Tier1TCPInternalServer

Tier1TCPInternalServer is used to describe the properties of a TCP server which is used exclusively within the mesh.

FieldDescriptionValidation Rule

name

string
REQUIRED
A name assigned to the server. This name is used in the generated metrics. The name must be unique across all TCP servers in the gateway.

hostname

string
REQUIRED
The name of the service used. Although hostname or authority does not make sense in the non-HTTP context, this is used for the multicluster routing purposes. Consider the case where there are two non-HTTP services listening on the same port 6000, but are hosted on different workloads. Here, the service name is used to distinguish between the two for routing to the correct workload. We do not support wildcard hostnames yet. The ports are determined automatically by the cluster updates of the remote edge clusters. Suppose there is a service called foo.com and the remote cluster says that it exposes ports 8080 and 8443, then we can route east-west traffic for both the ports through this server. The changes to the port or protocol settings are picked up automatically.

string = {
  min_len: 1
}

clusters

List of tetrateio.api.tsb.gateway.v2.ClusterDestination
The destination clusters contain ingress gateways exposing the service.