Skip to main content
Version: 1.4.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 port 8443. Traffic for this host is TLS terminated and forwarded over Istio mutual TLS to the ingress gateways hosting movieinfo.com host on clusters c3 and c4.

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
hostname: movieinfo.com # TLS termination and Istio mTLS to upstream
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

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 and bookinfo.com within the mesh. Traffic to movieinfo.com is load balanced across all clusters on vpc-02, while traffic to bookinfo.com 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
- 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

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.xcp.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.xcp.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
REQUIRED
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.

message = {
  required: true
}

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

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.