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

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

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

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

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

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