Annotation Reference

Complete reference of all annotations supported by the Tetrate Hosted Agent

Gateway Annotations (gateway.tetrate.io/*)

Gateway annotations are applied to Kubernetes Service objects to expose them via north-south (ingress) gateways.

Core Service Exposure

Annotation	Type	Default	Required	Description
gateway.tetrate.io/host	string	-	Yes	External hostname (supports comma-separated list, max 10)
gateway.tetrate.io/hosts	string	-	No	Alias for /host
gateway.tetrate.io/expose	string	local	No	Exposure mode: local, global, false
gateway.tetrate.io/path	string	/	No	URL path prefix for routing
gateway.tetrate.io/protocol	string	HTTP	No	Protocol: HTTP, HTTPS (TCP/TLS currently disabled)
gateway.tetrate.io/port	uint32	80 (HTTP), 443 (HTTPS)	No	External gateway port

Local Routing

Annotation	Type	Default	Description
gateway.tetrate.io/local-host	string	{service}.{namespace}.svc.cluster.local	Backend service hostname
gateway.tetrate.io/local-path	string	Same as path	Backend path (for path rewriting)
gateway.tetrate.io/local-protocol	string	Auto-detected	Backend service protocol
gateway.tetrate.io/local-port	uint32	First service port	Backend service port

Global Multi-Cluster Exposure

Annotation	Type	Default	Required	Description
gateway.tetrate.io/edge-cluster	string	-	Yes (if expose=global)	Single edge cluster name (use for single-cluster global exposure)
gateway.tetrate.io/edge-clusters	string	-	Yes (if expose=global)	Comma-separated edge cluster names with optional weights (use for multi-cluster)

note

Use either edge-cluster (singular) for exposing through a single edge cluster, or edge-clusters (plural) for multi-cluster exposure with optional weighted traffic distribution. Do not use both annotations together.

Weighted Traffic Distribution Format:

• "cluster1:70,cluster2:30" - Explicit weights (70% to cluster1, 30% to cluster2)
• "cluster1,cluster2" - Default weight 0 each (enables locality-based routing)
• "cluster1:70,cluster2" - Mixed (cluster1=70, cluster2=0)

Gateway Selection & Deployment

Annotation	Type	Default	Description
gateway.tetrate.io/gateway-namespace	string	tetrate-system	Namespace where gateway pods run
gateway.tetrate.io/gateway-name	string	gw-{host}	Override gateway name
gateway.tetrate.io/gateway-set	string	-	Gateway grouping identifier (future use)
gateway.tetrate.io/workload-selector	string	app=gateway	Pod label selector (format: key=value,key2=value2)
gateway.tetrate.io/auto-deploy	bool	false	Enable automatic gateway.install creation

TLS Configuration

Annotation	Type	Default	Required	Description
gateway.tetrate.io/tls-mode	string	SIMPLE	No	TLS mode: SIMPLE, MUTUAL, PASSTHROUGH
gateway.tetrate.io/tls-secret	string	-	Yes (HTTPS)	Kubernetes secret name with TLS cert/key
gateway.tetrate.io/tls-secret-namespace	string	Gateway namespace	No	Namespace of TLS secret (creates ReferenceGrant if different). Requires shared gateway functionality to be enabled.
gateway.tetrate.io/traffic-mode	string	AUTO	No	Traffic mode: AUTO, INGRESS, EGRESS, TRANSIT

HTTPS Redirect

Annotation	Type	Default	Description
gateway.tetrate.io/https-redirect	bool	true (for HTTPS)	Enable HTTP→HTTPS redirect
gateway.tetrate.io/https-redirect-port	uint32	Main port	Target HTTPS port for redirect
gateway.tetrate.io/http-port	uint32	80	Source HTTP port for redirect server

Authentication & Authorization

Annotation	Type	Default	Description
gateway.tetrate.io/jwt-issuers	YAML	-	JWT issuer configurations (list)
gateway.tetrate.io/oidc-enabled	bool	false	Enable OIDC authentication
gateway.tetrate.io/oidc-config	YAML	-	OIDC provider configuration
gateway.tetrate.io/authz-external	string (URL)	-	External authorization service URL

JWT Issuer YAML Format:

- issuer: "https://auth.example.com"
  jwksUri: "https://auth.example.com/.well-known/jwks.json"
  audiences: ["api.example.com"]

OIDC Config YAML Format:

grantType: "AUTHORIZATION_CODE"
clientId: "my-client-id"
clientTokenSecret: "my-secret"
redirectUri: "https://api.example.com/callback"
provider:
  issuer: "https://auth.example.com"
  authorizationEndpoint: "https://auth.example.com/oauth2/authorize"
  tokenEndpoint: "https://auth.example.com/oauth2/token"
  jwksUri: "https://auth.example.com/.well-known/jwks.json"

Rate Limiting & Policies

Annotation	Type	Default	Description
gateway.tetrate.io/rate-limits	YAML	-	Rate limiting rules (dimensions + limits)
gateway.tetrate.io/cors-policy	YAML	-	CORS policy configuration
gateway.tetrate.io/retry-policy	YAML	-	Retry policy configuration

Rate Limit YAML Format:

- dimensions:
  - remoteAddress:
      value: "*"
  limit:
    requestsPerUnit: 100
    unit: MINUTE

CORS Policy YAML Format:

allowOrigin: ["https://example.com"]
allowMethods: ["GET", "POST"]
allowHeaders: ["Content-Type", "Authorization"]
exposeHeaders: ["X-Custom-Header"]
maxAge: "86400s"
allowCredentials: true

Retry Policy YAML Format:

attempts: 3
perTryTimeout: "10s"
retryOn: "5xx,reset,connect-failure,refused-stream"

Advanced Features

Annotation	Type	Default	Description
gateway.tetrate.io/waf-enabled	bool	false	Enable Web Application Firewall (OWASP ModSecurity rules)
gateway.tetrate.io/extensions	YAML	-	Custom extensions (future use)
gateway.tetrate.io/custom-config	YAML	-	Custom configuration overrides
gateway.tetrate.io/cloud-annotations	YAML	-	Cloud provider LoadBalancer annotations
gateway.tetrate.io/gateway-status	JSON	-	Read-only - Gateway status written by agent

Cloud Annotations YAML Format (supports AWS, GCP, Azure):

# AWS
service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
service.beta.kubernetes.io/aws-load-balancer-internal: "true"

# GCP
cloud.google.com/load-balancer-type: "Internal"

# Azure
service.beta.kubernetes.io/azure-load-balancer-internal: "true"

---

Traffic Annotations (traffic.tetrate.io/*)

Traffic annotations are applied to Kubernetes Namespace objects to enable east-west (service-to-service) traffic management.

Important: traffic.tetrate.io/global Has Two Different Uses

The key traffic.tetrate.io/global is used in two different ways depending on the resource type:

Resource	Type	Key	Effect
Namespace	Annotation	traffic.tetrate.io/global: "true"	Enables namespace-level exposure (ALL services in namespace are exposed)
Service	Label	traffic.tetrate.io/global: "true"	Enables service-level exposure (only THIS service is exposed)

Key differences:

• On Namespace: Must be an annotation (metadata.annotations)
• On Service: Must be a label (metadata.labels)
• Using the wrong type (annotation on Service or label on Namespace) will have no effect

See East-West Traffic Management for detailed usage examples.

East-West Gateway Control

Annotation	Type	Default	Description
traffic.tetrate.io/global	bool	false	Enable namespace-level east-west exposure (all services)
traffic.tetrate.io/eastwest-gateway-deploy	bool	true	Auto-deploy east-west gateway.install resource
traffic.tetrate.io/eastwest-gateway-namespace	string	tetrate-system	Gateway namespace
traffic.tetrate.io/eastwest-gateway-name	string	east-west-gateway	Gateway resource name
traffic.tetrate.io/eastwest-gateway-workload-selector	string	app=east-west-gateway	Pod label selector
traffic.tetrate.io/eastwest-gateway-cloud-annotations	YAML	-	Cloud provider annotations for gateway LoadBalancer

Annotation Derivation Logic:

• Both provided: Use both independently (full control)
• Only gateway-name: Workload selector derived as app={gateway-name}
• Only workload-selector: Gateway name derived from app label in selector
• Neither provided: Defaults to gateway-name=east-west-gateway with app=east-west-gateway

---

Service Labels (East-West)

Service-level east-west exposure uses a label (not annotation):

Label	Applied To	Description
traffic.tetrate.io/global: "true"	Service	Expose this specific service cross-cluster

Important: This must be a label, not an annotation!

apiVersion: v1
kind: Service
metadata:
  name: payment-api
  namespace: payments
  labels:
    traffic.tetrate.io/global: "true"  # LABEL (not annotation)
spec:
  selector:
    app: payment-api
  ports:
  - port: 8080
    targetPort: 8080
    name: http

---

Workspace and Tenant Annotations (tetrate.io/*)

Workspace and tenant annotations are applied to Kubernetes Namespace objects to customize the TSB workspace and tenant used for that namespace.

Custom Workspace and Tenant

Annotation	Type	Default	Description
tetrate.io/workspace	string	ws-{namespace}	Custom workspace name
tetrate.io/tenant	string	TSB_TENANT env var	Custom tenant name (auto-created if needed)

Quick Start

Custom Workspace Name Only

Override the default ws-{namespace} workspace naming pattern:

apiVersion: v1
kind: Namespace
metadata:
  name: payments
  annotations:
    tetrate.io/workspace: "payment-services"  # Custom workspace instead of "ws-payments"
  labels:
    tetrate.io/rev: default
    istio-injection: enabled

Custom Tenant with Auto-Creation

Use a custom tenant instead of the default:

apiVersion: v1
kind: Namespace
metadata:
  name: payments
  annotations:
    tetrate.io/tenant: "production"  # Auto-creates tenant if needed
  labels:
    tetrate.io/rev: default
    istio-injection: enabled

Both Custom Workspace and Tenant

apiVersion: v1
kind: Namespace
metadata:
  name: payments
  annotations:
    tetrate.io/workspace: "payment-services"
    tetrate.io/tenant: "production"
  labels:
    tetrate.io/rev: default
    istio-injection: enabled

Workspace Sharing

Multiple namespaces can share the same workspace by using the same tetrate.io/workspace annotation value:

# Frontend namespace
apiVersion: v1
kind: Namespace
metadata:
  name: frontend
  annotations:
    tetrate.io/workspace: "shared-app"
  labels:
    tetrate.io/rev: default
---
# Backend namespace
apiVersion: v1
kind: Namespace
metadata:
  name: backend
  annotations:
    tetrate.io/workspace: "shared-app"
  labels:
    tetrate.io/rev: default

Both namespaces share the shared-app workspace, allowing unified traffic policies and service mesh configuration.

Tenant Auto-Creation

When using a custom tenant annotation:

1. Existence Check: Agent queries TSB API for the tenant
2. Auto-Creation: If tenant doesn't exist, creates it with:
   • deletionProtectionEnabled: true (prevents accidental deletion)
   • Standard tenant configuration
3. Workspace Creation: Creates workspace in the custom tenant

warning

Custom tenants have deletion protection enabled. To delete them manually in TSB, you must first disable deletion protection.

Edge Cases

Scenario	Behavior
No annotations	Uses default workspace (ws-{namespace}) and default tenant
Only tetrate.io/workspace	Custom workspace, default tenant
Only tetrate.io/tenant	Default workspace name (ws-{namespace}), custom tenant
Both annotations	Custom workspace and custom tenant
Namespace removes annotation	Falls back to defaults on next reconciliation
Namespace changes workspace annotation	Service moved to new workspace

---

Kubernetes Object Mapping

Annotation Prefix	Applied To	Creates
gateway.tetrate.io/*	Service	TSB Gateway, gateway.install, ReferenceGrant
traffic.tetrate.io/*	Namespace	TSB WorkspaceSettings, gateway.install
traffic.tetrate.io/global (label)	Service	Updates WorkspaceSettings exposedServices
tetrate.io/workspace	Namespace	TSB Workspace (custom name)
tetrate.io/tenant	Namespace	TSB Tenant (auto-created if needed)

Exposure Mode Comparison

Mode	Trigger	WorkspaceSettings Field	Behavior
Namespace-Level	Namespace annotation: traffic.tetrate.io/global: "true"	exposedServices: null (omitted)	All services exposed
Service-Level	Service label: traffic.tetrate.io/global: "true"	serviceLabels selector	Only labeled services exposed

---

TSB API Paths

Resource	API Path
Gateway	organizations/{org}/tenants/{tenant}/workspaces/{ws}/gatewaygroups/{cluster}-gateway-services/gateways/gw-{name}
Edge Gateway	organizations/{org}/tenants/{tenant}/workspaces/{ws}/gatewaygroups/{edge-cluster}-gateway-services/gateways/egw-{name}
WorkspaceSettings	organizations/{org}/tenants/{tenant}/workspaces/{ws}/settings/{ws}-settings

---

Quick Reference

Minimum Required (HTTP)

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

Minimum Required (HTTPS)

annotations:
  gateway.tetrate.io/host: "api.example.com"
  gateway.tetrate.io/protocol: "HTTPS"
  gateway.tetrate.io/tls-secret: "my-tls-secret"

Minimum Required (East-West Namespace)

# On Namespace
annotations:
  traffic.tetrate.io/global: "true"

Minimum Required (East-West Service)

# On Service
labels:
  traffic.tetrate.io/global: "true"