Advanced Configuration

Understand the full power of the Hosted Agent to support a range of scenarios

Path Rewriting

Transform external paths to internal paths:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/external/api/v2"      # External path
  gateway.tetrate.io/local-path: "/api"            # Rewrite to internal path

Cross-Namespace TLS Secrets

When TLS secrets are stored in a namespace different from the gateway deployment (e.g., managed by cert-manager), you can use tls-secret-namespace to reference them. This requires shared gateway functionality to be enabled. See annotation reference for details.

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/tls-secret: "wildcard-cert"
  gateway.tetrate.io/tls-secret-namespace: "cert-manager"  # Secret's namespace

The agent automatically:

1. Prefixes the secret name with the namespace: cert-manager/wildcard-cert
2. Creates a ReferenceGrant in the secret's namespace to allow gateway access:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: wildcard-cert-tetrate-system-secret-grant
  namespace: cert-manager
spec:
  from:
  - group: networking.istio.io
    kind: Gateway
    namespace: tetrate-system
  to:
  - group: ""
    kind: Secret
    name: wildcard-cert

Custom Port Configuration

Override default ports:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/port: "8443"                  # External port
  gateway.tetrate.io/local-port: "9090"            # Internal service port

Multiple Hosts Support

A single service can be exposed on multiple hostnames simultaneously by providing comma-separated host values. This is useful for scenarios like:

• Multi-environment access: Same service accessible via api.example.com, test-api.example.com
• Domain aliasing: Service available under multiple brand domains
• Migration scenarios: Supporting old and new domain names during transitions

Basic Multiple Hosts

apiVersion: v1
kind: Service
metadata:
  name: api-service
  namespace: production
  annotations:
    gateway.tetrate.io/host: "api.example.com, test-api.example.com"
    gateway.tetrate.io/protocol: "HTTPS"
    gateway.tetrate.io/path: "/api/v1"
spec:
  selector:
    app: api-service
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Result: This creates two separate TSB Gateway objects:

• Gateway for api.example.com/api/v1 → api-service.production:8080
• Gateway for test-api.example.com/api/v1 → api-service.production:8080

Multiple Hosts with Different Environments

apiVersion: v1
kind: Service
metadata:
  name: multi-env-service
  namespace: apps
  annotations:
    gateway.tetrate.io/host: "prod.example.com, staging.example.com, dev.example.com"
    gateway.tetrate.io/protocol: "HTTPS"
    gateway.tetrate.io/tls-secret: "multi-env-tls"
spec:
  selector:
    app: multi-env-service
  ports:
  - port: 80
    targetPort: 8080
    name: http

Multiple Hosts Features

• Automatic Whitespace Handling: Spaces around host names are automatically trimmed
• Individual Validation: Each host is validated independently for proper hostname format
• Separate Gateway Objects: Each host gets its own TSB Gateway configuration
• Shared Configuration: All hosts use the same path, protocol, and security settings
• Security Limits: Maximum 10 hosts per service (configurable)
• Collision Detection: Each host is checked separately for conflicts with other services

Important Notes

Performance Considerations

• Each host creates a separate TSB Gateway object, so 5 hosts = 5 API calls to TSB
• Consider TSB API rate limits when using many hosts across multiple services

Security Limits

• Maximum 10 hosts per service annotation
• Excess hosts beyond the limit are silently truncated with a warning log
• Each host undergoes full RFC-compliant hostname validation

Backward Compatibility

• Single hosts continue to work exactly as before: gateway.tetrate.io/host: "api.example.com"
• Existing services are not affected by this change

HTTPS Redirect Configuration

Configure HTTP to HTTPS redirection behavior:

# Default behavior (enabled for HTTPS protocol)
annotations:
  gateway.tetrate.io/host: "secure.example.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/tls-secret: "secure-tls"
  # gateway.tetrate.io/https-redirect: "true"  # Default: auto-enabled for HTTPS
  
# Custom port configuration
annotations:
  gateway.tetrate.io/host: "bookinfo.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/tls-secret: "bookinfo-certs"
  gateway.tetrate.io/https-redirect: "true"
  gateway.tetrate.io/http-port: "8080"           # HTTP redirect server port
  gateway.tetrate.io/https-redirect-port: "8443" # HTTPS destination port

# Disable redirect (serve both HTTP and HTTPS independently)  
annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/tls-secret: "api-tls"
  gateway.tetrate.io/https-redirect: "false"     # Disable automatic redirect

Custom Gateway Selection

Use specific gateway workloads:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/workload-selector: "app=custom-gateway,tier=edge"
  gateway.tetrate.io/gateway-namespace: "custom-gateways"
  gateway.tetrate.io/gateway-name: "my-custom-gateway"

Cloud Provider Load Balancer Configuration

Configure cloud-specific load balancer settings dynamically:

AWS Load Balancer Configuration

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/cloud-annotations: |
    service.beta.kubernetes.io/aws-load-balancer-attributes: load_balancing.cross_zone.enabled=true
    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
    service.beta.kubernetes.io/aws-load-balancer-type: external
    service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp

Google Cloud Load Balancer Configuration

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/cloud-annotations: |
    cloud.google.com/neg: '{"ingress":true}'
    cloud.google.com/backend-config: '{"default": "backend-config"}'
    cloud.google.com/load-balancer-type: "Internal"

Azure Load Balancer Configuration

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/cloud-annotations: |
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"
    service.beta.kubernetes.io/azure-load-balancer-internal-subnet: "subnet-name"
    service.beta.kubernetes.io/azure-dns-label-name: "myapp"

The cloud-annotations are dynamically applied to the Kubernetes Gateway Service, allowing you to configure cloud-specific load balancer settings without modifying the agent code.

Automatic Gateway Deployment Creation

When you specify a custom workload-selector, the agent can automatically create gateway.install resources if they don't exist:

Enabling Auto-Deployment (Default: Disabled)

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/workload-selector: "app=edge-gateway"  # Will create gateway.install if missing
  gateway.tetrate.io/auto-deploy: "true"  # Explicitly enable (not default)

Disabling Auto-Deployment

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/workload-selector: "app=existing-gateway"  # Must already exist
  gateway.tetrate.io/auto-deploy: "false"  # Disable auto-creation

Custom Gateway Deployments

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/workload-selector: "app=custom-gateway,tier=edge,version=v2"
  gateway.tetrate.io/gateway-namespace: "edge-system"

This configuration will:

1. Check if a gateway.install resource with labels app=custom-gateway,tier=edge,version=v2 exists in edge-system namespace
2. If not found and auto-deploy is true (not default, must be explicitly enabled), create a gateway.install resource named custom-gateway
3. Configure the TSB Gateway to target this gateway workload
4. The gateway.install resource automatically creates the necessary deployment with TSB-managed images

Note: The auto-deployment feature creates gateway.install resources which handle the underlying deployment creation automatically through TSB's gateway installation system.