Skip to main content
logoTetrate Service BridgeVersion: 1.13.x

Shared Gateway

Alpha Feature

Shared Gateway feature in TSB is in Alpha stage and may undergo API changes in future releases. It is not recommended for production use.

In a service mesh deployment, the recommended architecture is to deploy separate Ingress and Egress gateways per namespace or Workspace. Gateways are lightweight, and this approach simplifies configuration and minimizes the impact of noisy neighbours and failures.

In some cases, particularly when organizations demand a multi tenant shared cluster with a large numbers of namespaces, a Shared Gateway approach is preferred.

Shared Gateway Responsibilities​

Platform teams and Application teams both have a role in configuring this gateway to publish applications. The Platform and Application responsibilities are separated as follows:

Platform Team​

Platform teams are typically responsible for managing the infrastructure and common services used by multiple application teams. Their responsibilities regarding gateway include:

  • Infrastructure Provisioning: Platform teams use the new MP Gateway Install resource to set up and configure the underlying kubernetes resources ( like service and deployment objects) that make up the shared gateway, including LoadBalancer services that provision cloud infrastructure components such as NLB, ALB, or equivalent load balancers.

  • Scaling & Monitoring: They manage the gateway's scalability, performance, and availability, ensuring it can handle traffic for all applications in the mesh.

  • Security Controls: Platform teams handle the setup of security policies like TLS termination, mTLS between services, and configure enhanced security mode for cross-namespace secret access.

  • Traffic Routing Logic: Platform teams control which application teams can reference shared gateway workloads using the SharedGatewayReferenceGrant resource.

  • Global Failover & Resilience: The platform team configures strategies for global failover and resiliency, including cross-zone or cross-region redundancy where applicable.

Application Team​

Each Application team, on the other hand, focuses on their specific services and how they interact with the gateway. Their responsibilities include:

  • Gateway Configurations: Application teams define Gateway resources in their own namespaces, specifying routing rules, hostnames, and traffic policies.

  • TLS Certificate Management: Teams manage their own TLS certificates and secrets within their namespaces, with no secret duplication required.

  • Service-Specific Traffic Management: Teams configure traffic splitting, fault injection, retries, or circuit-breaking rules for their specific services.

  • Application-Level Security: Application teams configure service-specific mTLS policies, access policies (using AuthorizationPolicy resources), or implement JWT-based authentication if required for their services.

  • Observability: Application teams have full visibility into their own traffic metrics, traces, and logs without exposure to other teams' data.

In essence, platform teams are responsible for building and maintaining the shared infrastructure, while application teams configure how their specific services leverage that infrastructure. Both teams need to collaborate closely, especially for troubleshooting, performance tuning, and policy enforcement

Shared Gateway Architecture​

Available in TSB 1.13.1+

The Platform team deploys a Shared Gateway instance on the kubernetes cluster with enhanced security mode, creates dedicated TSB Tenant, Workspace, and GatewayGroup resources, and grants access to application teams using the SharedGatewayReferenceGrant resource. Each Application team then creates their own TSB hierarchy (Tenant, Workspace, GatewayGroup) and deploys Gateway resources in their own namespaces. Their Gateway resources reference the platform team's shared gateway workload using a workloadSelector, and TSB safely generates the appropriate underlying configuration.

Shared Gateway Shared Ingress Gateway, publishing services from multiple application teams

This approach provides:

  • TSB validation of all configuration for correct multi-tenant operation
  • Complete autonomy for application teams with their own TSB hierarchy
  • Cross-namespace TLS secret references eliminating secret duplication
  • Fine-grained access control via SharedGatewayReferenceGrant
  • Isolated observability views for each application team
  • No shared workspace access required

Key Features​

  • Enhanced Security Mode: Cross-namespace TLS secret references without secret duplication
  • SharedGatewayReferenceGrant: Fine-grained access control for gateway workload references
  • Gateway Discovery: Application teams can discover available shared gateways via TSB UI, tctl, or APIs
  • Isolated Observability: Each team sees only their own traffic metrics and topology
  • Self-Service: Application teams operate independently within their own TSB hierarchy

Implementation Guide​

This implementation guide demonstrates how two application teams named Payment and Marketing can independently expose their services ( payment.tetrate.io and marketing.tetrate.io) through a single shared gateway workload deployed in the platform namespace. Each team will manage their own TLS certificates and secrets within their respective namespaces, demonstrating complete autonomy while leveraging shared infrastructure. By the end, both teams will have configured HTTPS endpoints with isolated configurations and cross-namespace TLS secret references.

Prerequisites​

Before implementing the shared gateway model, ensure:

  • TSB Version: 1.13.1 or higher installed and operational
  • RBAC Permissions: Appropriate roles assigned to platform and application teams
  • Namespace Setup: Platform namespace and application namespaces created
  • Certificate Management: Process for generating or obtaining TLS certificates established

Step 1: Enable Shared Gateway Feature​

Add the shared gateway overlay to Control Plane CR:

apiVersion: install.tetrate.io/v1alpha1
kind: ControlPlane
metadata:
  name: controlplane
  namespace: istio-system
spec:
  .
  .
  xcp:
    .
    .
    kubeSpec:
      overlays:
        - apiVersion: install.xcp.tetrate.io/v1alpha1
          kind: EdgeXcp
          name: edge-xcp
          patches:
            - path: spec.sharedGateway.enabled
              value: true

Step 2: Platform Team Setup​

Create a dedicated Tenant, Workspace & Group for platform team to manage shared gateway resources:

platform-config.yaml
  - apiVersion: api.tsb.tetrate.io/v2
    kind: Tenant
    metadata:
      name: platform
      organization: tetrate
    spec:
      displayName: platform
  - apiVersion: api.tsb.tetrate.io/v2
    kind: Workspace
    metadata:
      name: platform-ws
      organization: tetrate
      tenant: platform
    spec:
      namespaceSelector:
        names:
          - "c1/platform"
      displayName: platform-ws
  - apiVersion: gateway.tsb.tetrate.io/v2
    kind: Group
    metadata:
      name: platform-gg
      organization: tetrate
      tenant: platform
      workspace: platform-ws
    spec:
      displayName: platform Gateway Group
      namespaceSelector:
        names:
          - "c1/platform"
      configMode: BRIDGED
tctl apply -f platform-config.yaml

Step 3: Deploy Shared Gateway Instance​

The new Management Plane Gateway Install resource is used to deploy Kubernetes resources such as Services of type LoadBalancer, Deployments, HPA, etc to the target cluster and namespace. The Service resource with type: LoadBalancer will automatically provision cloud infrastructure components such as Network Load Balancers (NLB), Application Load Balancers (ALB), or equivalent load balancing services based on the cloud provider and annotations used.

When set on an Istio proxy, ISTIO_META_XCP_ISTIO_GATEWAY_SECURITY_MODE enables enhanced security mode in Istiod, enforcing stricter access control for cross-namespace secret references. In this mode, Istiod validates such references against ReferenceGrant resources to ensure that only explicitly authorized gateways can access secrets from other namespaces.

Important

Shared Gateway model can only be achieved using the MP Gateway Install Resource, Legacy k8s Gateway Install resource is not supported for Shared Gateway use-case

shared-gw-install.yaml
apiVersion: install.tetrate.io/v1alpha1
kind: Gateway
metadata:
  name: shared-ingress-gateway
  namespace: platform
  organization: tetrate
  tenant: platform
  workspace: platform-ws
  gatewayGroup: platform-gg
spec:
  type: UNIFIED
  targetCluster: c1
  targetNamespace: platform
  kubeSpec:
    deployment:
      labels:
        app: shared-ingress-gateway
        version: v1
      env:
        # Mandatory: Enables enhanced security mode in Istiod
        - name: ISTIO_META_XCP_ISTIO_GATEWAY_SECURITY_MODE
          value: enhanced
      hpaSpec:
        minReplicas: 2
        maxReplicas: 10
    service:
      type: LoadBalancer
      # Optional: Add cloud provider specific annotations
      annotations:
        # AWS NLB example
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
        service.beta.kubernetes.io/aws-load-balancer-scheme: "internet-facing"
tctl apply -f shared-gw-install.yaml

Step 4: Create SharedGatewayReferenceGrant​

The SharedGatewayReferenceGrant resource is a critical access control mechanism that allows platform teams to explicitly authorize which application teams can reference and use specific shared gateway workloads. This resource acts as a bridge between the platform team's infrastructure and application teams' configurations, enabling secure multi-tenancy by controlling which tenants, workspaces, or gateway groups are permitted to create Gateway configurations that reference the shared gateway workload via workloadSelector.

Without a SharedGatewayReferenceGrant, application teams cannot discover or reference the shared gateway, ensuring that access is always explicit and controlled. This fine-grained authorization model allows platform teams to maintain centralized governance while enabling self-service capabilities for authorized application teams.

Grant access to application teams using the SharedGatewayReferenceGrant resource:

shared-gw-ref-grant.yaml
apiVersion: gateway.tsb.tetrate.io/v2
kind: SharedGatewayReferenceGrant
metadata:
  name: shared-ingress-gateway-ref-grant
  organization: tetrate
  tenant: platform
  workspace: platform-ws
  gatewayGroup: platform-gg
spec:
  gatewaySelectors:
  - nameSelector:
      name: shared-ingress-gateway
  from:
    fqn:
    - organizations/tetrate/tenants/payment/workspaces/payment-ws
    - organizations/tetrate/tenants/marketing/workspaces/marketing-ws
tctl apply -f shared-gw-ref-grant.yaml

Step 5: Application Team Setup​

Application teams now create their own complete TSB hierarchy and reference the shared gateway workload.

Discover Available Shared Gateways​

Application teams can discover shared gateways they have access to:

Using tctl CLI:​

tctl x sharedgateway list \
  --resource organizations/tetrate/tenants/payment/workspaces/payment-ws \
  -o yaml

Output:​

fqn: organizations/tetrate/tenants/platform/workspaces/platform-ws/gatewaygroups/platform-gg/installgateways/shared-ingress-gateway
workloadSelector:
  namespace: platform
  labels:
    app: shared-ingress-gateway
    version: v1

Payment Team Configuration​

Create TSB configurations for Tenant, Workspace & Group

payment-config.yaml
  - apiVersion: api.tsb.tetrate.io/v2
    kind: Tenant
    metadata:
      name: payment
      organization: tetrate
    spec:
      displayName: Payment
  - apiVersion: api.tsb.tetrate.io/v2
    kind: Workspace
    metadata:
      name: payment-ws
      organization: tetrate
      tenant: payment
    spec:
      namespaceSelector:
        names:
          - "c1/payment"
      displayName: payment-ws
  - apiVersion: gateway.tsb.tetrate.io/v2
    kind: Group
    metadata:
      name: payment-gg
      organization: tetrate
      tenant: payment
      workspace: payment-ws
    spec:
      displayName: Payment Gateway Group
      namespaceSelector:
        names:
          - "c1/payment"
      configMode: BRIDGED
tctl apply -f payment-config.yaml

Deploy Payment Applications:​

Deploy your application services in the payment namespace. For this example, we'll use bookinfo:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo.yaml -n payment

Create TLS Secret in Payment Namespace:​

Generate a self-signed certificate for bookinfo.tetrate.io

openssl req -x509 -newkey rsa:4096 -keyout bookinfo.key -out bookinfo.crt \
  -days 365 -nodes -subj "/CN=bookinfo.tetrate.io"

Create TLS secret in payment namespace

kubectl -n payment create secret tls bookinfo-tls-server-secret \
  --key bookinfo.key \
  --cert bookinfo.crt

Create Gateway Configuration:​

Note the critical elements:

  • Gateway uses payment team's own TSB hierarchy (not platform's)
  • References shared gateway workload via workloadSelector
  • TLS secret uses namespace-prefixed format: payment/bookinfo-tls-server-secret
bookinfo-gateway.yaml
  apiVersion: gateway.tsb.tetrate.io/v2
  kind: Gateway
  metadata:
    name: bookinfo-ingress-gateway
    organization: tetrate
    tenant: payment
    workspace: payment-ws
    gatewayGroup: payment-gg
  spec:
    displayName: Bookinfo Ingress
    workloadSelector:
      namespace: platform
      labels:
        app: shared-ingress-gateway
    http:
      - hostname: bookinfo.tetrate.io
        name: https-bookinfo-tetrate
        port: 443
        tls:
          mode: SIMPLE
          secretName: payment/bookinfo-tls-server-secret
        routing:
          rules:
            - route:
                serviceDestination:
                  host: "payment/productpage.payment.svc.cluster.local"
                  port: 9080
tctl apply -f bookinfo-gateway.yaml

Marketing Team Configuration​

Create TSB configurations for Tenant, Workspace & Group

marketing-config.yaml
  - apiVersion: api.tsb.tetrate.io/v2
    kind: Tenant
    metadata:
      name: marketing
      organization: tetrate
    spec:
      displayName: marketing
  - apiVersion: api.tsb.tetrate.io/v2
    kind: Workspace
    metadata:
      name: marketing-ws
      organization: tetrate
      tenant: marketing
    spec:
      namespaceSelector:
        names:
          - "c1/marketing"
      displayName: marketing-ws
  - apiVersion: gateway.tsb.tetrate.io/v2
    kind: Group
    metadata:
      name: marketing-gg
      annotations:
        tsb.tetrate.io/organization: tetrate
        tsb.tetrate.io/tenant: marketing
        tsb.tetrate.io/workspace: marketing-ws
    spec:
      displayName: marketing Gateway Group
      namespaceSelector:
        names:
          - "c1/marketing"
      configMode: BRIDGED
tctl apply -f marketing-config.yaml

Deploy Marketing Applications:​

Deploy your application services in the marketing namespace. For this example, we'll use httpbin:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml -n marketing

Create TLS Secret in Marketing Namespace:​

Generate a self-signed certificate for httpbin.tetrate.io

openssl req -x509 -newkey rsa:4096 -keyout httpbin.key -out httpbin.crt \
  -days 365 -nodes -subj "/CN=httpbin.tetrate.io"

Create TLS secret in marketing namespace

kubectl -n marketing create secret tls httpbin-tls-server-secret \
  --key httpbin.key \
  --cert httpbin.crt

Create Gateway Configuration:​

Note the critical elements:

  • Gateway uses marketing team's own TSB hierarchy (not platform's)
  • References shared gateway workload via workloadSelector
  • TLS secret uses namespace-prefixed format: marketing/httpbin-tls-server-secret
httpbin-gateway.yaml
  apiVersion: gateway.tsb.tetrate.io/v2
  kind: Gateway
  metadata:
    name: httpbin-ingress-gateway
    organization: tetrate
    tenant: marketing
    workspace: marketing-ws
    gatewayGroup: marketing-gg
  spec:
    displayName: HTTPBin Ingress
    workloadSelector:
      namespace: marketing
      labels:
        app: shared-ingress-gateway
    http:
      - hostname: httpbin.tetrate.io
        name: https-httpbin-tetrate
        port: 443
        tls:
          mode: SIMPLE
          secretName: marketing/httpbin-tls-server-secret
        routing:
          rules:
            - route:
                serviceDestination:
                  host: "marketing/httpbin.marketing.svc.cluster.local"
                  port: 9080
tctl apply -f httpbin-gateway.yaml

Verify TLS Secret Resolution​

You can verify cross-namespace secret resolution and the ownership separation are functioning correctly by running the below command.

istioctl pc secrets shared-ingress-gateway-6bcfbd548f-gqzqp.platform -n platform

RESOURCE NAME                                        TYPE           STATUS     VALID CERT     SERIAL NUMBER                                        NOT AFTER                NOT BEFORE
kubernetes://payment/bookinfo-tls-server-secret      CA             ACTIVE     true           69074691824052649136778808855554399193507165682      2026-10-17T08:51:05Z     2025-10-17T08:51:05Z
kubernetes://marketing/httpbin-tls-server-secret     CA             ACTIVE     true           603540839962420801129592134949166069872350233278     2026-10-17T08:51:24Z     2025-10-17T08:51:24Z

Output shows that the shared gateway workload (shared-ingress-gateway) running in platform namespace has dynamically fetched TLS certs defined by app teams ( payment and marketing) in their own namespaces, and the envoy SDS (Secret Discovery Service) has correctly propagated these secrets into the gateway Envoy.

Verify Traffic​

Export $GATEWAY_IP

export GATEWAY_IP=$(kubectl -n platform get service shared-ingress-gateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

Verify bookinfo.tetrate.io by providing --carcert bookinfo.crt from payment namespace

curl -v \
  --resolve "bookinfo.tetrate.io:443:$GATEWAY_IP" \
  --cacert bookinfo.crt \
  "https://bookinfo.tetrate.io/api/v1/products/1/reviews"

Verify httpbin.tetrate.io by providing --carcert httpbin.crt from marketing namespace

curl -v \
  --resolve "httpbin.tetrate.io:443:$GATEWAY_IP" \
  --cacert httpbin.crt \
  "https://httpbin.tetrate.io/get"

Verify gateway topology from TSB UI

Shared Gateway Topology