Skip to main content
logoTetrate Service BridgeVersion: next

Best Practices

Best Practices when configuring services with the Tetrate Hosted Agent

1. Use Specific Paths​

Instead of using root path /, use specific paths for better organization:

# Good
gateway.tetrate.io/path: "/api/v1/users"

# Avoid
gateway.tetrate.io/path: "/"

2. Implement Security Layers​

Always use HTTPS for production services and implement appropriate authentication:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/tls-secret: "api-tls"
  gateway.tetrate.io/jwt-issuers: |
    - issuer: "https://auth.example.com"
      jwksUri: "https://auth.example.com/.well-known/jwks.json"

3. Use Rate Limiting​

Protect your services from abuse and ensure fair usage:

annotations:
  gateway.tetrate.io/rate-limits: |
    - dimensions:
        - remoteAddress:
            value: "*"
      limit:
        requestsPerUnit: 100
        unit: MINUTE

4. Monitor Gateway Status​

Regularly check the gateway status annotation for any issues:

# Watch for status changes - services with host annotation
kubectl get services -A -o json | jq -r '.items[] | select(.metadata.annotations."gateway.tetrate.io/host" != null and .metadata.annotations."gateway.tetrate.io/host" != "") | "\(.metadata.namespace)/\(.metadata.name): \(.metadata.annotations."gateway.tetrate.io/gateway-status")"'

5. Use Cloud-Specific Load Balancer Settings​

Configure cloud provider annotations for optimal performance:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/cloud-annotations: |
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
    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"

6. Plan for Multi-Cluster​

If deploying across multiple clusters, use consistent naming and paths:

# Cluster 1
annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/cluster1/api"

# Cluster 2  
annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/path: "/cluster2/api"

7. Document Your Configuration​

Keep track of exposed services and their configurations:

annotations:
  gateway.tetrate.io/host: "api.example.com"
  # Description: Main API gateway for user service
  # Owner: platform-team@example.com
  # SLA: 99.9% uptime