Quick Start

Deploy and expose your first API through Tetrate Gateway in 25 minutes

Prerequisites

Required Tools

• Kubernetes cluster access
• kubectl configured for your cluster
• helm installed

Cluster Onboarded to TSB

Your Kubernetes cluster must be registered in TSB and have the control plane installed. Follow the Control Plane Installation guide before proceeding.

Step 1: Install the Tetrate Hosted Agent

With the cluster onboarded, install the Hosted Agent into the namespace where your TSB Control plane is running, typically istio-system:

# Add the Tetrate Helm repository
helm repo add tetrate-tsb-helm 'https://charts.dl.tetrate.io/public/helm/charts/'

# Update Helm repositories
helm repo update

# Install the Tetrate Hosted Agent
helm upgrade --install tetrate-hosted-agent tetrate-tsb-helm/tetrate-hosted-agent --namespace istio-system

For advanced configuration options such as log level, custom tenant, or resource limits, see Configuring the Tetrate Agent.

Step 2: Deploy Sample Application

# Create namespace
kubectl create namespace api-broker

# Label namespace for workspace creation and sidecar injection
kubectl label namespace api-broker tetrate.io/rev=default istio-injection=enabled

# Deploy sample app
kubectl apply -n api-broker -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml

Why Label the Namespace?

The tetrate.io/rev=default label is required for the Tetrate Hosted Agent to create a workspace for this namespace. This is controlled by the agent.kubernetes.triggerLabels configuration. Alternative labels like istio-injection=enabled or istio.io/rev=default also work depending on your agent configuration.

Step 3: Expose API via Gateway

Option A: Basic HTTP Service Exposure (Recommended for Quick Start)

The simplest way to expose a service with automatic gateway creation:

apiVersion: v1
kind: Service
metadata:
  name: httpbin
  namespace: api-broker
  annotations:
    gateway.tetrate.io/host: "httpbin.example.com"
    gateway.tetrate.io/auto-deploy: "true"
spec:
  selector:
    app: httpbin
  ports:
  - port: 8000
    targetPort: 8000
    name: http

This configuration will:

• Create a gateway listening on port 80 (HTTP default)
• Route traffic from httpbin.example.com to your service
• Automatically create the gateway workload in tetrate-system namespace (via auto-deploy: "true")

Apply with kubectl patch:

kubectl patch service httpbin -n api-broker -p '{"metadata":{"annotations":{"gateway.tetrate.io/host":"httpbin.example.com","gateway.tetrate.io/auto-deploy":"true"}}}'

About auto-deploy

When gateway.tetrate.io/auto-deploy: "true" is set, the agent automatically creates a gateway.install resource which deploys the gateway workload. This is the simplest approach for getting started. For production workloads with custom HPA, resource limits, or fault tolerance requirements, see Option B.

Option B: HTTPS Service with TLS

To expose a service over HTTPS with TLS termination:

apiVersion: v1
kind: Service
metadata:
  name: httpbin
  namespace: api-broker
  annotations:
    gateway.tetrate.io/host: "httpbin.example.com"
    gateway.tetrate.io/protocol: "HTTPS"
    gateway.tetrate.io/tls-secret: "httpbin-tls"
    gateway.tetrate.io/auto-deploy: "true"
spec:
  selector:
    app: httpbin
  ports:
  - port: 8000
    targetPort: 8000
    name: http

First create the TLS secret:

# Generate a self-signed certificate (for testing)
openssl req -x509 -nodes -days 30 -newkey rsa:2048 \
  -keyout /tmp/tls.key -out /tmp/tls.crt \
  -subj "/CN=httpbin.example.com"

# Create TLS secret in tetrate-system namespace
kubectl create secret tls httpbin-tls \
  --cert=/tmp/tls.crt \
  --key=/tmp/tls.key \
  -n tetrate-system

Then apply the annotations:

kubectl patch service httpbin -n api-broker -p '{
  "metadata": {
    "annotations": {
      "gateway.tetrate.io/host": "httpbin.example.com",
      "gateway.tetrate.io/protocol": "HTTPS",
      "gateway.tetrate.io/tls-secret": "httpbin-tls",
      "gateway.tetrate.io/auto-deploy": "true"
    }
  }
}'

Option C: Custom Gateway (Production)

For production workloads requiring custom HPA, resource limits, fault tolerance, or cloud-specific load balancer settings, you should deploy a custom gateway.install resource first.

When to Use Custom Gateways

Scenario	auto-deploy	Custom Gateway
Quick Testing	✅ Recommended	❌ Overkill
Production Workloads	⚠️ Basic setup	✅ Recommended
High Availability	❌ Limited control	✅ Full control
Custom Scaling (HPA)	❌ Default only	✅ Custom settings
Fault Tolerance	❌ Basic	✅ Full configuration

Deploy Custom Gateway

apiVersion: install.tetrate.io/v1alpha1
kind: Gateway
metadata:
  name: external-gateway
  namespace: tetrate-system
spec:
  type: UNIFIED
  kubeSpec:
    service:
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
        service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
        service.beta.kubernetes.io/aws-load-balancer-target-group-attributes: preserve_client_ip.enabled=true
    deployment:
      env:
      - name: ISTIO_META_XCP_ISTIO_GATEWAY_SECURITY_MODE
        value: enhanced
      hpaSpec:
        maxReplicas: 10
        metrics:
        - resource:
            name: cpu
            target:
              averageUtilization: 75
              type: Utilization
          type: Resource
        minReplicas: 3
      strategy:
        rollingUpdate:
          maxUnavailable: 1
        type: RollingUpdate

Configure Service to Use Custom Gateway

apiVersion: v1
kind: Service
metadata:
  name: httpbin
  namespace: api-broker
  annotations:
    gateway.tetrate.io/host: "httpbin.example.com"
    gateway.tetrate.io/workload-selector: "app=external-gateway"
    gateway.tetrate.io/gateway-namespace: "tetrate-system"
    # auto-deploy NOT needed - using existing gateway
spec:
  selector:
    app: httpbin
  ports:
  - port: 8000
    targetPort: 8000
    name: http

note

When using a custom gateway with workload-selector, do not set auto-deploy: "true". The gateway workload must already exist. If it doesn't, you'll get a "gateway not found" error.

Get Your API Endpoint

# For auto-deployed gateway (Options A & B):
export GATEWAY_ENDPOINT=$(kubectl get svc gateway -n tetrate-system -o jsonpath='{.status.loadBalancer.ingress[0]}' | jq -r '.ip // .hostname')

# For custom gateway (Option C):
# export GATEWAY_ENDPOINT=$(kubectl get svc external-gateway -n tetrate-system -o jsonpath='{.status.loadBalancer.ingress[0]}' | jq -r '.ip // .hostname')

# Display access information
echo "Your API is available at: http://$GATEWAY_ENDPOINT/"
echo ""
echo "Test endpoints (requires Host header):"
echo "  GET:     curl -H 'Host: httpbin.example.com' http://$GATEWAY_ENDPOINT/get"
echo "  Headers: curl -H 'Host: httpbin.example.com' http://$GATEWAY_ENDPOINT/headers"
echo "  Status:  curl -H 'Host: httpbin.example.com' http://$GATEWAY_ENDPOINT/status/200"

Verification

Test HTTP Endpoints

# Basic GET Request
curl -H "Host: httpbin.example.com" http://$GATEWAY_ENDPOINT/get

# Alternative using --resolve (no Host header needed)
curl --resolve httpbin.example.com:80:$GATEWAY_ENDPOINT http://httpbin.example.com/get

# Headers Inspection
curl -H "Host: httpbin.example.com" http://$GATEWAY_ENDPOINT/headers

# Status Check
curl -H "Host: httpbin.example.com" http://$GATEWAY_ENDPOINT/status/200

# POST with JSON Data
curl -X POST -H "Host: httpbin.example.com" -H "Content-Type: application/json" \
     http://$GATEWAY_ENDPOINT/post -d '{"test": "data"}'

Test HTTPS Endpoints (If TLS Configured)

# Secure GET Request
curl -k -H "Host: httpbin.example.com" https://$GATEWAY_ENDPOINT/get

# Alternative using --resolve
curl -k --resolve httpbin.example.com:443:$GATEWAY_ENDPOINT https://httpbin.example.com/get

# Secure Headers Inspection
curl -k -H "Host: httpbin.example.com" https://$GATEWAY_ENDPOINT/headers

Next Steps

Feature	Description
Basic Usage	Learn common annotation patterns
Advanced Configuration	Path rewriting, multiple hosts, custom ports
Security Use Cases	Add authentication and authorization
Traffic Management	Configure routing and load balancing
East-West Traffic	Cross-cluster service communication

Troubleshooting

Gateway Not Found Error

If you see "gateway not found" errors when using Option C (custom gateway):

# Verify the custom gateway exists
kubectl get gateway.install -n tetrate-system external-gateway

# If missing, either:
# 1. Deploy the gateway.install resource first, OR
# 2. Add auto-deploy: "true" to use automatic gateway creation

Service Not Responding

# Verify pod is running
kubectl get pods -n api-broker

# Check annotations are applied
kubectl get svc httpbin -n api-broker -o jsonpath='{.metadata.annotations}' | jq .

# Check gateway status annotation for errors
kubectl get svc httpbin -n api-broker -o jsonpath='{.metadata.annotations.gateway\.tetrate\.io/gateway-status}' | jq .

Gateway Service Not Created

# For auto-deployed gateway (Options A & B):
kubectl get svc gateway -n tetrate-system

# For custom gateway (Option C):
kubectl get svc external-gateway -n tetrate-system

Workspace Not Created

# Verify namespace has the trigger labels
kubectl get namespace api-broker --show-labels

# If missing, add the labels
kubectl label namespace api-broker tetrate.io/rev=default istio-injection=enabled

Need More Help?

• Check the Troubleshooting Guide for detailed debugging steps
• Review agent logs: kubectl logs -n istio-system deployment/tetrate-hosted-agent
• See Annotation Reference for all available options