Install the complete Agent Router data plane in one command.
Steps performed:
1. Load and validate the identity (service-account) file
2. Optionally sync images and the serve-helm OCI chart to a private registry (--image-sync)
3. Optionally create a Kubernetes dockerconfigjson pull secret (--image-pull-secret-stdin)
4. Generate Helm values and deploy via "helm upgrade --install"
5. Wait for pods to become ready (disable with --no-wait)
helm and kubectl are downloaded automatically on first run if not already present
(on supported platforms: darwin/arm64 and linux/amd64). Before rendering manifests
or touching the cluster, tetrate runs preflight checks (Helm 3+, kubectl, and for live
installs cluster connectivity). Set TETRATE_SKIP_PREFLIGHT=1 or use --skip-preflight
to bypass these checks (e.g. in constrained CI).
On an interactive terminal, if you omit --enable-otel-collector, tetrate asks (before
Helm install) whether to enable the in-cluster OpenTelemetry collector and prompts
for the OTLP endpoint and optional settings (GCP Workload Identity is asked only when
the OTLP auth header uses berglas sm://). Prompts read from /dev/tty when available
so Helm install is not blocked by stdin buffering. Skipped in CI, pipes, when using
--image-pull-secret-stdin, or when you pass --enable-otel-collector explicitly.
A second wizard asks whether to set HTTP_PROXY / HTTPS_PROXY / NO_PROXY env on the
controller, controller-worker, and data-plane Envoy pods. It runs before values are
generated, so --print-helm-values also reflects the wizard answers. Skipped when any
of --http-proxy / --https-proxy / --no-proxy is passed explicitly, in CI/pipes, or
when --image-pull-secret-stdin has already consumed stdin.
Examples:
# Sync images to the registry, then install
tetrate agentrouter dataplane install identity.json --image-sync acme.registry.com
# Install only: use images already in this registry (no copy step)
tetrate agentrouter dataplane install identity.json --image-registry acme.registry.com
# Sync images only; exit before install
tetrate agentrouter dataplane install identity.json --image-sync acme.registry.com --sync-only
# Apply CRDs only; exit before namespaces / Helm install
tetrate agentrouter dataplane install identity.json --crds-only
# Mirror-to-mirror sync: pull from an existing mirror (--image-registry),
# push to a new one (--image-sync). The source override only applies when
# --image-sync is also set.
tetrate agentrouter dataplane install identity.json \
--image-registry acme.registry.com \
--image-sync acme1.registry.com --sync-only
# Print generated Helm values without deploying
tetrate agentrouter dataplane install identity.json --print-helm-values
# Print all Kubernetes resources for a GitOps workflow (no cluster access needed)
tetrate agentrouter dataplane install identity.json --print-resources
# Full workflow: sync + pull secret + install
echo "user:password" | tetrate agentrouter dataplane install identity.json \
--image-sync acme.registry.com \
--image-pull-secret-stdin
# Optional: deploy the in-cluster OTEL collector (requires endpoint; headers/WI optional).
# Use --otel-collector-otlp-tls-insecure=false when the OTLP server uses TLS with verification.
# customer_id is added to collector metrics from identity customerId unless --customer overrides.
tetrate agentrouter dataplane install identity.json --image-registry REGISTRY \
--enable-otel-collector \
--otel-collector-endpoint 'https://otel.example.com:4317'
Safe to re-run: yes, with conditions -- the CRD apply, both namespaces, the
image-pull secret and the Helm release all converge, and a re-run carries
the existing release's observability and toleration values forward. But if a
previous run's Helm step was interrupted mid-operation, clear the stuck
release first (`helm status`, then `helm rollback` or `helm uninstall`) --
this command cannot do that for you.
Usage:
tare serve install <identity-file> [flags]
Flags:
Main:
--disable-hpa Disable HPA for all supported components
--disable-pdb Disable PDBs for all supported components
--drain-timeout-seconds int EnvoyProxy.spec.shutdown.drainTimeout (seconds). Maximum time Envoy waits for in-flight requests (long LLM streams) to finish before SIGKILL. Drives the Pod's terminationGracePeriodSeconds. (default 300)
--ha Deploy the data-plane Envoy proxy with HA-safe defaults (HPA min 2, PDB min 1). Pass --ha=false for single-replica lab/CI installs (pre-ADR-041 behavior). (default true)
--no-wait Return after Helm finishes; do not wait for pods to be ready (overrides --wait)
--wait Wait for pods to be ready after deploy (default true; use --no-wait to disable) (default true)
Registry:
--image-pull-secret-name string With --image-pull-secret-stdin: name for the created secret (default: tars-image-pull-secret). Without: reference an existing secret by this name
--image-pull-secret-stdin Read 'user:password' from stdin and create a Kubernetes dockerconfigjson pull secret
--image-sync string Sync images and the serve-helm OCI chart to this registry before install; sets --image-registry to this destination after the sync (unless --image-registry was used to override the source)
--include-manage-images With --image-sync/--print-images: also mirror the images the management-plane charts deploy from the mirror (app, auth, dashboard, bootstrapper and the manage CronJobs and Jobs). Off by default — a data plane never runs these, so requiring them would break a registry meant only to serve data-plane installs/upgrades. Does not affect the image precheck. tetrate agentrouter manage install has no image-sync path of its own yet, so this is currently the only way to mirror the management-plane tier.
--skip-image-precheck Skip the image-completeness precheck that runs before image sync / install (also TETRATE_SKIP_IMAGE_PRECHECK=1)
--sync-only Sync images (requires --image-sync) then exit without deploying
--upgrade-src-registry string Override the self-upgrade SOURCE registry (TARS_UPGRADE_SRC_REGISTRY on controller/worker; default registry.tetrate.ai). The destination is always --image-registry. For e2e/staging/air-gapped that mirror release images to a private registry.
Telemetry:
--enable-otel-collector Deploy the in-cluster OpenTelemetry collector and egress ALS (requires --otel-collector-endpoint)
--otel-collector-endpoint string OTLP endpoint for telemetry export (required with --enable-otel-collector)
--otel-collector-image-repository string Short image repository under global.imageRegistry (default: otel-collector-berglas)
--otel-collector-image-tag string Override otel-collector-berglas image tag (default: embedded manifest)
--otel-collector-otlp-tls-insecure Set otelCollector.exporters.otlp.tls.insecure (when true, skip TLS verification) (default true)
--otel-collector-workload-identity-email string GCP service account email for Workload Identity (collector ServiceAccount annotation)
--otel-exporter-auth-headers string Authorization header value for OTLP export (plain or sm:// for berglas)
Networking:
--forward-proxy-address string Explicit override for envoy's LLM-egress forward proxy (EGRESS_FORWARD_PROXY_ADDRESS on the ai-gateway-controller). Default: auto-derived from --http-proxy. Pass a different host:port to point envoy at a separate egress proxy; pass --forward-proxy-address="" to disable the LLM tunnel while keeping --http-proxy on for the controller/worker (Fiserv-style topology where the LLM is reachable in-VNet but the management plane needs a proxy).
--forward-proxy-no-proxy strings Host-name suffixes to exempt from envoy's LLM forward-proxy egress (comma-separated, e.g. .openai.azure.com,.privatelink.openai.azure.com). Only effective when the forward proxy is active. Case-insensitive; leading dot tolerated. Use for in-VNet LLM endpoints reachable directly (Azure Private Endpoint, GCP PSC, private DNS) while keeping the proxy on for other LLM endpoints.
--http-proxy string Outbound HTTP_PROXY env for controller/worker/Envoy pods (e.g. http://10.10.2.4:8888). Omit on a TTY to be prompted interactively (skipped in CI/pipes). Envoy itself does not honour HTTP_PROXY directly; by default the ai-gateway-controller derives EGRESS_FORWARD_PROXY_ADDRESS (host:port) from this and the eaigw extension server tunnels every LLM-bound upstream through it via HTTP CONNECT. Use --forward-proxy-address to override or disable that auto-derive.
--https-proxy string Outbound HTTPS_PROXY env for controller/worker/Envoy pods (e.g. http://10.10.2.4:8888). Omit on a TTY to be prompted (defaults to --http-proxy when left blank in the wizard).
--no-proxy string Outbound NO_PROXY env for controller/worker/Envoy pods (e.g. .svc,.cluster.local,10.0.0.0/8). Omit on a TTY to be prompted (skip with Enter).
--upgrade-manifest-base-url string Override the self-upgrade release-manifest base URL (TARS_UPGRADE_MANIFEST_BASE_URL on controller/worker; default https://tare.tetrate.ai/tools/tags). For e2e/staging/air-gapped.
--upgrade-manifest-certificate-identity-regexp string Override the trusted Sigstore certificate identity regexp for a private release workflow
--upgrade-manifest-certificate-oidc-issuer string Override the trusted Sigstore certificate OIDC issuer for a private release workflow
Inspect:
--crds-only Apply CRDs to the cluster then exit; skip namespaces, pull secret, Helm install, and wait. Cannot be combined with --sync-only, --image-sync, --image-pull-secret-stdin, or any --print-* flag.
--print-helm-values Print generated Helm values to stdout without deploying
--print-images Print the list of images and exit; combine with --image-sync to show src→dst pairs
--print-resources Print all Kubernetes resource manifests via helm template to stdout without applying
Output:
--parallel int Number of images to sync concurrently (1 = serial, recommended 2-4) (default 3)
--progress string Image-sync progress display: auto|tty|plain|none (default "auto")
--stall-threshold duration Flag image sync as stalled after this duration of zero throughput; escalate at 2x (default 30s)
Other:
--argocd-namespace string Namespace where ArgoCD Applications live; pre-check uses this to detect mixed-deployment (default: argocd). Set to empty string to disable the check.
--clear-tolerations Drop the data plane's pod tolerations instead of carrying them forward on a re-run over an existing release. Omitting --toleration preserves whatever that release holds, so this is the only way to remove them; the pods it moves may not be schedulable anywhere else. No effect on a fresh install. Conflicts with --toleration.
--context string kubeconfig context to act on (default: the current context)
--enable-metrics-server Install a Kubernetes metrics-server (off by default). Enable only on clusters that lack one — managed Kubernetes (GKE/EKS/AKS) ships its own, and a second instance fights over the cluster-singleton metrics API. Gives tetrate agentrouter doctor live CPU/RAM; without it the doctor falls back to pod requests/limits.
--enable-semantic-router Enable the semantic-router guardrail provider (off by default; heavyweight — PVC, multi-Gi memory, model downloads). Renders the semanticrouter + semanticrouter-aux workloads. Per-workload nodeSelector/tolerations/affinity are set via the dashboard "Build install values" form; the global --toleration flag also applies to these pods.
--force-gateway-api-crds Apply the Gateway API CRDs bundled with this chart even when the cluster already serves them, overriding the Gateway API version-floor check (also TETRATE_FORCE_GATEWAY_API_CRDS=1). Use only where tetrate manages the Gateway API CRDs on this cluster: where a managed addon owns them (GKE, EKS, AKS), the apply takes field ownership that the addon's reconciler will take back. It applies the bundled CRDs only when the cluster is at or below the version this build requires; it will not downgrade a cluster that is ahead.
--gateway-hostname stringArray Hostname this data plane serves, optionally with a port (repeatable; the first is the address the console prints). Without it the data plane keeps the address the management plane stores for it. --gateway-hostname="" alone declares that it serves no hostname.
--ignore-argocd Proceed even when ArgoCD manages the system namespace (mixed-deployment override; see ADR 046 §12.13).
--ignore-flux Proceed even when a Flux HelmRelease manages the system namespace (mixed-deployment override).
--kubeconfig string Path to the kubeconfig file (default: $KUBECONFIG, then ~/.kube/config)
--smoke-api-key string Inference API key for the post-apply data plane smoke tests. Prefer TETRATE_API_KEY — a key passed here lands in shell history and the process list. Mint one from the management-plane dashboard. Without it, only the credential-free auth check runs.
--smoke-mcp-route string MCP route path to establish a post-apply session against (e.g. /mcp/<profile-id>). Omit to skip.
--smoke-model string Model to send a real post-apply request to (e.g. gpt-4o-mini). Requires --smoke-api-key. Spends a few tokens on the named model to prove inference and streaming work end to end. Omit to skip.
--smoke-timeout duration Per-request timeout for the post-apply data plane smoke tests. (default 30s)
--toleration helm upgrade --install Pod toleration applied to every data-plane component that schedules on tainted nodes: egress envoy, redis, ratelimit, the label-namespace Job, tareDoctor CronJob, and the configMonitor CronJob (when enabled). Repeatable. Format: key[=value]:effect[:tolerationSeconds]. Examples: --toleration nodepool:NoSchedule (Exists operator), --toleration nodepool=workload:NoSchedule (Equal operator). effect ∈ NoSchedule|PreferNoSchedule|NoExecute. Default: empty (no toleration rendered). On a re-run over an existing release (install is helm upgrade --install), omitting this flag carries the release's existing tolerations forward; pass --clear-tolerations to drop them. Per-component overrides are dashboard-only — use the "Build install values" form to taint a single component differently from the rest.
-y, --yes Skip the confirmation prompt; required when there is no terminal to prompt on