Basic Usage

Learn the various ways to use the Tetrate Hosted Agent to expose services

Prerequisites

Before using these annotations, ensure your namespace is labeled for workspace creation and sidecar injection:

kubectl label namespace <your-namespace> tetrate.io/rev=default istio-injection=enabled

The tetrate.io/rev=default label is required for the Tetrate Hosted Agent to create a workspace and manage gateways for services in that namespace. This is controlled by the agent.kubernetes.triggerLabels configuration.

Required Annotations

Only one annotation is required to expose a service:

Annotation	Description	Example
gateway.tetrate.io/host	External hostname	"api.example.com"
gateway.tetrate.io/expose	Exposure mode (optional)	"local", "false", "global"

Service Exposure Modes:

• local (default) - Exposes service locally through the gateway (equivalent to previous "true")
• false - Explicitly disables gateway exposure
• global - Global multi-cluster exposure via edge clusters with optional weighted traffic distribution

Default Behavior:

• Services are automatically exposed in "local" mode when gateway.tetrate.io/host annotation is present
• No need to explicitly set gateway.tetrate.io/expose: "local" - it's the default
• Values are case-insensitive: "Local", "LOCAL", "local" all work
• Backward Compatibility: Old boolean value "true" still works and maps to "local" with deprecation warning

Controlling Service Exposure

Example 1: Default Local Exposure

apiVersion: v1
kind: Service
metadata:
  name: api-service
  namespace: default
  annotations:
    gateway.tetrate.io/host: "api.example.com"
    # gateway.tetrate.io/expose: "local"  # Optional - this is the default
spec:
  selector:
    app: api-service
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Example 2: Explicitly Disable Exposure

apiVersion: v1
kind: Service
metadata:
  name: internal-service
  namespace: default
  annotations:
    gateway.tetrate.io/host: "internal.example.com"  # Host defined but exposure disabled
    gateway.tetrate.io/expose: "false"  # Explicitly disable exposure
spec:
  selector:
    app: internal-service
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Example 3: Global Multi-Cluster Exposure

apiVersion: v1
kind: Service
metadata:
  name: global-service
  namespace: default
  annotations:
    gateway.tetrate.io/host: "global.example.com"
    gateway.tetrate.io/expose: "global"
    gateway.tetrate.io/edge-clusters: "us-west-1,eu-west-1"  # Required for global exposure
spec:
  selector:
    app: global-service
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Example 4: Global Exposure with Weighted Traffic Distribution

apiVersion: v1
kind: Service
metadata:
  name: weighted-global-service
  namespace: default
  annotations:
    gateway.tetrate.io/host: "global.example.com"
    gateway.tetrate.io/expose: "global"
    gateway.tetrate.io/edge-clusters: "us-west-1:70,eu-west-1:30"  # 70% US, 30% EU
spec:
  selector:
    app: global-service
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Example 5: Migration from Boolean (Backward Compatible)

apiVersion: v1
kind: Service
metadata:
  name: legacy-service
  namespace: default
  annotations:
    gateway.tetrate.io/host: "legacy.example.com"
    gateway.tetrate.io/expose: "true"  # Old boolean - still works, maps to "local"
spec:
  selector:
    app: legacy-service
  ports:
  - port: 8080
    targetPort: 8080
    name: http

Default Behavior

When you use minimal annotations, the system applies these defaults:

• Protocol: HTTP (port 80)
• Path: / (root path)
• Gateway Namespace: tetrate-system
• Workload Selector: app=gateway
• TLS Mode: SIMPLE (for HTTPS)
• Traffic Mode: AUTO

Path-Based Routing

You can expose services on specific paths:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/v1/users"

Multiple services can share the same hostname with different paths:

# User Service
annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/v1/users"

# Product Service  
annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/v1/products"

# Order Service
annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/v1/orders"

The system automatically handles path-based routing with longest-prefix-wins strategy.