Skip to main content
logoTetrate Service BridgeVersion: next

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

Tetrate Management Plane Access​

You will need:

  • Management Plane URL (e.g., https://<MP_ADDRESS>/)
  • Username and password
  • Organization name

Step 1: Connect to Tetrate Management Plane​

Download tctl CLI​

# Quick one-line installation (Linux & macOS)
curl -sL https://charts.dl.tetrate.io/public/raw/files/get-tctl.sh | bash

Configure tctl Connection​

# Configure connection (replace placeholders with your values)
tctl config clusters set default --bridge-address <MP_ADDRESS>:443
tctl config users set default --username <USERNAME> --password <PASSWORD> --org <ORGANIZATION>

# Verify connection
tctl version

Step 2: Onboard Your Cluster​

One-Command Installation​

# Replace 'my-cluster' with your desired cluster name
curl -s https://charts.dl.tetrate.io/public/raw/files/onboard-cluster.sh | bash -s my-cluster

Expected Output​

[INFO] Starting Tetrate cluster onboarding for: my-cluster
[SUCCESS] Prerequisites check passed
[SUCCESS] Cluster service account registered
[SUCCESS] Configuration template generated
[SUCCESS] Configuration patches applied
[SUCCESS] Helm repository updated
[SUCCESS] Tetrate Control Plane installed
[SUCCESS] Tetrate Hosted Agent installed
[SUCCESS] Tetrate cluster onboarding completed for 'my-cluster'
Already Have a Cluster Onboarded?

If your cluster is already onboarded to Tetrate but the Hosted Agent is not installed, see Configuring the Tetrate Agent for agent installation instructions, then proceed to Step 3.

Step 3: 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 4: Expose API via Gateway​

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: secure-app
  namespace: production
  annotations:
    gateway.tetrate.io/host: "secure.example.com"
    gateway.tetrate.io/protocol: "HTTPS"
    gateway.tetrate.io/tls-secret: "secure-app-tls"
    gateway.tetrate.io/auto-deploy: "true"
spec:
  selector:
    app: secure-app
  ports:
  - port: 8080
    targetPort: 8080
    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=secure.example.com"

# Create TLS secret in tetrate-system namespace
kubectl create secret tls secure-app-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": "secure.example.com",
      "gateway.tetrate.io/protocol": "HTTPS",
      "gateway.tetrate.io/tls-secret": "secure-app-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
Scenarioauto-deployCustom 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

Step 1: 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

Step 2: 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: secure.example.com" https://$GATEWAY_ENDPOINT/get

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

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

Next Steps​

FeatureDescription
Basic UsageLearn common annotation patterns
Advanced ConfigurationPath rewriting, multiple hosts, custom ports
Security Use CasesAdd authentication and authorization
Traffic ManagementConfigure routing and load balancing
East-West TrafficCross-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?​