Configuring the Tetrate Agent

Configure the Agent's installation and operations to fine-tune its behavior

Prerequisites

Before installing the Tetrate Hosted Agent, ensure you have:

• Kubernetes cluster with TSB installed
• ControlPlane object in istio-system namespace
• Valid cluster-service-account secret with organization information
• Tenant default within TSB Hierarchy (or customize via configuration)

Installation

Add the Tetrate Helm Repository

# 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 Using Helm

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

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

Install with Custom Values

# Install with custom configuration
helm upgrade --install tetrate-hosted-agent tetrate-tsb-helm/tetrate-hosted-agent \
  --namespace istio-system \
  --create-namespace \
  --set agent.logLevel=debug \
  --set agent.reconciliationInterval=300s \
  --set agent.tsb.auth.tenant=my-tenant

Install with Values File

# Create custom values file
cat > my-values.yaml <<EOF
agent:
  logLevel: "debug"
  reconciliationInterval: "300s"
  tsb:
    auth:
      tenant: "my-tenant"
  resources:
    requests:
      memory: "256Mi"
      cpu: "200m"
    limits:
      memory: "1Gi"
      cpu: "1000m"
EOF

# Install with values file
helm upgrade --install tetrate-hosted-agent tetrate-tsb-helm/tetrate-hosted-agent \
  --namespace istio-system \
  --create-namespace \
  -f my-values.yaml

Helm Configuration Reference

Agent Configuration

Parameter	Description	Default
agent.image.registry	Image registry	containers.dl.tetrate.io
agent.image.repository	Image repository	"" (empty)
agent.image.tag	Image tag	1.2.9
agent.image.pullPolicy	Image pull policy	Always
agent.replicaCount	Number of replicas	1
agent.logLevel	Log level (debug/info/warn/error)	info
agent.metricsPort	Metrics server port	8080
agent.reconciliationInterval	Drift detection interval	180s

TSB Authentication

Parameter	Description	Default
agent.tsb.auth.controlPlaneName	ControlPlane object name	controlplane
agent.tsb.auth.controlPlaneNamespace	ControlPlane namespace	istio-system
agent.tsb.auth.organization	TSB organization (auto-discovered if empty)	""
agent.tsb.auth.tenant	TSB tenant name	default
agent.tsb.insecureSkipVerify	Skip TLS verification (testing only)	false

Kubernetes Configuration

Parameter	Description	Default
agent.kubernetes.triggerLabels	Labels that trigger workspace creation	["tetrate.io/rev", "istio.io/rev", "istio-injection=enabled"]
agent.kubernetes.namespaceFilter	Optional namespace filter	""

Resource Limits

Parameter	Description	Default
agent.resources.requests.memory	Memory request	128Mi
agent.resources.requests.cpu	CPU request	100m
agent.resources.limits.memory	Memory limit	512Mi
agent.resources.limits.cpu	CPU limit	500m

Advanced Configuration

Parameter	Description	Default
agent.nodeSelector	Node selector for pod scheduling	kubernetes.io/arch: amd64
agent.tolerations	Pod tolerations	[]
agent.affinity	Pod affinity rules	{}
agent.extraEnvs	Additional environment variables	[]
agent.extraVolumes	Additional volumes	[]
agent.extraVolumeMounts	Additional volume mounts	[]

Service Configuration

Parameter	Description	Default
service.type	Service type	ClusterIP
service.port	Service port	8080
metricsService.enabled	Enable metrics service	true
metricsService.annotations	Prometheus scrape annotations	See values.yaml

Security Configuration

Parameter	Description	Default
serviceAccount.create	Create service account	true
rbac.create	Create RBAC resources	true
agent.podSecurityContext.runAsNonRoot	Run as non-root	true
agent.podSecurityContext.runAsUser	Run as user ID	65534

High Availability

Parameter	Description	Default
autoscaling.enabled	Enable HPA	false
autoscaling.minReplicas	Minimum replicas	1
autoscaling.maxReplicas	Maximum replicas	10
autoscaling.targetCPUUtilizationPercentage	Target CPU utilization	80
podDisruptionBudget.enabled	Enable PDB	false
podDisruptionBudget.minAvailable	Minimum available pods	1

Environment Variables

The agent can also be configured directly via environment variables:

Environment Variable	Description	Default
CONTROLPLANE_NAME	ControlPlane object name	controlplane
CONTROLPLANE_NAMESPACE	ControlPlane object namespace	istio-system
TSB_ORGANIZATION	TSB organization (auto-discovered)	-
TSB_TENANT	TSB tenant name	default
RECONCILIATION_INTERVAL	Drift detection interval	180s
LOG_LEVEL	Log level (debug/info/warn/error)	info
METRICS_PORT	Metrics server port	8080
TRIGGER_LABELS	Comma-separated trigger labels	tetrate.io/rev,istio.io/rev,istio-injection=enabled

Monitoring Agent Health

Health Endpoints

The agent exposes several endpoints for monitoring:

Endpoint	Description
GET /health	Agent health status
GET /ready	Agent readiness status
GET /metrics	Prometheus metrics

Debug Endpoints

For troubleshooting, additional debug endpoints are available:

Endpoint	Description
GET /debug/gateways	Gateway infrastructure status
GET /debug/annotation-gateways	Detailed gateway routing information
GET /debug/tsb-api-objects	Raw TSB API payloads
GET /debug/workspaces	Workspace management status
GET /debug/services	Service management status

Checking Agent Status

# Port-forward to the agent
kubectl port-forward -n istio-system deployment/tetrate-hosted-agent 8080:8080

# Basic health check
curl http://localhost:8080/health

# Readiness check
curl http://localhost:8080/ready

# Prometheus metrics
curl http://localhost:8080/metrics

# Check gateway status
curl http://localhost:8080/debug/annotation-gateways | jq '.serviceStatuses'

# View TSB API payloads
curl http://localhost:8080/debug/tsb-api-objects | jq '.gateways[]'

Prometheus Integration

The metrics service is configured for automatic Prometheus scraping:

metricsService:
  enabled: true
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "8080"
    prometheus.io/path: "/metrics"

Upgrading

To upgrade an existing installation:

# Update Helm repositories first
helm repo update

# Upgrade with new values
helm upgrade tetrate-hosted-agent tetrate-tsb-helm/tetrate-hosted-agent \
  --namespace istio-system \
  -f my-values.yaml

# Or upgrade with inline values
helm upgrade tetrate-hosted-agent tetrate-tsb-helm/tetrate-hosted-agent \
  --namespace istio-system \
  --set agent.image.tag=1.3.0

Uninstalling

To remove the agent:

helm uninstall tetrate-hosted-agent --namespace istio-system

note

Uninstalling the agent will not remove TSB resources (workspaces, gateways) that were created by the agent. These must be cleaned up separately if needed.