Skip to main content
Understand what the AWS Terraform modules provision and how the pieces fit together, so you can size, secure, and customize your LangSmith deployment before running make apply. Use this page as a reference while planning a rollout or troubleshooting an existing one. It covers:
  • Platform layers and application core services.
  • AWS managed services, IRSA roles, and cluster infrastructure.
  • Network topology, ingress options, and TLS/DNS strategies.
  • LangSmith Deployment add-on.
  • Module dependency graph and opt-in security modules.
If you are ready to install, start with the deployment walkthrough.

Platform layers

LangSmith on AWS deploys in two stages with one optional add-on. The infrastructure stage provisions the cloud foundation. The application stage installs the LangSmith Helm chart. The LangSmith Deployment add-on is opt-in and adds the host-backend, listener, and operator services for managing LangGraph applications from the UI. LangSmith on AWS service layout

Component to storage mapping

Application core services

These pods run on every deployment. All write logs and metrics; the busier components (backend, queue, ingest-queue) scale horizontally.
In-cluster ClickHouse is dev/POC only (single pod, no replication, no backups). For production use LangChain Managed ClickHouse or a self-managed external cluster.
SmithDB is LangSmith’s purpose-built observability backend, available for self-hosted starting with chart v16 (see self-hosted support). The AWS modules provision ClickHouse by default. Setting enable_smithdb = true also provisions SmithDB’s dependencies: a dedicated metastore RDS PostgreSQL instance (with smithdb_metastore_source = "create", the default), an S3 object-store bucket, an IRSA role, and Karpenter NodePools for NVMe instance-store nodes. ClickHouse stays enabled on chart v16 and v17. See SmithDB in the deployment guide.

One-time jobs

The Helm chart runs three jobs at install and upgrade time:

LangSmith Deployment add-on

When enable_deployments = true, three additional services are installed and a LangGraphPlatform CRD is registered. Each deployment the user creates in the LangSmith UI produces a Kubernetes Deployment in the langsmith namespace, managed by the operator.

AWS managed services

When postgres_source = "external" and redis_source = "external" (the recommended production setting), Terraform provisions the following AWS managed services. When Fleet, LangSmith Chat, or Insights use external storage, they share the RDS instance and the Redis cluster. An in-cluster Job creates each feature’s logical database, and each feature gets its own Redis DB index: 1 for Fleet, 2 for LangSmith Chat, 3 for Insights. DB 0 belongs to the main install.

RDS PostgreSQL

  • Default size: db.t3.large, private subnets, port 5432.
  • Defaults: PostgreSQL 16, storage encrypted, 10GB autoscaling to 100GB, 7-day backups, deletion protection on, IAM database authentication enabled.
  • Holds orgs, users, projects, API keys, settings.
  • Secret flow: setup-env.sh stores the password at SSM /langsmith/{base_name}/postgres-password and passes it to Terraform, which sets it on the instance and writes the connection_url into the langsmith-postgres Kubernetes Secret.

ElastiCache Redis

  • Default size: cache.m6g.xlarge, private subnets, TLS port 6379.
  • Redis 7.1, a single cache node, encryption at rest and in transit.
  • Trace ingestion queue, pub/sub, short-lived cache.
  • Secret flow: setup-env.sh stores the auth token at SSM /langsmith/{base_name}/redis-auth-token and passes it to Terraform, which sets it on the replication group and writes the connection_url into the langsmith-redis Kubernetes Secret.

Sandbox JuiceFS Redis

When enable_sandboxes = true, Terraform provisions a second, dedicated ElastiCache Redis ({base_name}-jfs-redis, default cache.m6g.large, noeviction parameter group, 7-day snapshots) for the JuiceFS sandbox filesystem. It also adds a sandbox-host managed node group (default m5d.metal, tainted sandbox.langsmith.com/host).

S3 bucket

  • Trace payloads: large inputs and outputs, attachments.
  • IRSA via langsmith_irsa_role (no static keys). VPC Gateway Endpoint, no public internet.
  • Encrypted with SSE-S3, or SSE-KMS when s3_kms_key_arn is set. Public access is blocked, and the bucket policy grants the LangSmith IRSA role access through the VPC endpoint.
  • Prefixes: ttl_s/ (short TTL) and ttl_l/ (long TTL).
  • The S3 bucket is always required, regardless of tier. Disabling blob storage breaks the cluster on large payloads.

SSM Parameter Store

  • Centralized secret store for all LangSmith secrets.
  • Flow: source infra/scripts/setup-env.sh writes secrets to SSM. The ESO ClusterSecretStore reads them and projects a langsmith-config Kubernetes Secret that the Helm chart mounts via config.existingSecretName.
  • Prefix: /langsmith/{name_prefix}-{environment}/.

Cluster infrastructure

Two Terraform modules install the cluster-level services LangSmith depends on. The eks module installs the AWS-integration controllers through eks-blueprints-addons and the EBS CSI driver as an EKS add-on; the k8s-bootstrap module installs the workload dependencies and the ingress gateways (see Ingress options):

IRSA roles

IRSA replaces static credentials. IAM trusts the EKS cluster’s OIDC issuer; service accounts in langsmith, kube-system, external-secrets, cert-manager, and (with SmithDB) karpenter are annotated with role ARNs and pods receive temporary credentials via the EKS token webhook.

Network topology

VPC and private endpoints

With create_vpc = true, the module builds a 10.0.0.0/16 VPC across up to three availability zones, and works in two-AZ regions such as us-west-1. It uses /21 private and public subnets and a single NAT gateway. The module creates one VPC endpoint, an S3 gateway endpoint. When you bring a VPC without NAT or internet egress (create_vpc = false), create com.amazonaws.<region>.ecr.api and com.amazonaws.<region>.ecr.dkr interface endpoints with private DNS enabled, attached to a security group that allows TCP 443 from the VPC CIDR, so nodes can pull images. Set alb_existing_security_group_id, postgres_existing_security_group_id, redis_existing_security_group_id, or bastion_existing_security_group_id to attach a security group you manage. Terraform attaches it but never writes rules to it.

Default ingress (ALB and Envoy Gateway)

Envoy Gateway split dataplane

With the default Envoy Gateway, the ALB forwards to the Envoy proxy pods on port 10080 through a TargetGroupBinding on the internal ClusterIP Envoy Service (port 80). The ALB terminates TLS. Agent pods can run in a separate langsmith-agents namespace: Both langsmith and langsmith-agents attach to the shared langsmith-gateway through an HTTPRoute with allowedRoutes: All.

Egress path with Network Firewall

When create_firewall = true, all outbound internet traffic from private subnets is inspected before reaching the NAT gateway:
Pod-to-pod, pod-to-RDS, and pod-to-ElastiCache traffic uses the local VPC route and never touches the firewall.

Ingress options

Four mutually exclusive ingress options ship with the modules. The Terraform-managed ALB fronts Envoy Gateway, NGINX, and Istio. In ALB Ingress mode, the AWS Load Balancer Controller provisions its own ALB and the Terraform ALB goes unused. The choice determines whether split dataplane (agent pods in a separate namespace) is supported. Envoy is on unless you set enable_istio_gateway or enable_nginx_ingress. Set enable_envoy_gateway = false explicitly to use ALB Ingress.

Why ALB Ingress cannot support split dataplane

Standard Kubernetes Ingress is namespace-scoped. The ALB controller routes only to services in the same namespace as the Ingress resource. Agent pods in langsmith-agents are invisible to an Ingress in langsmith. Envoy Gateway and Istio both support cross-namespace routing via the Kubernetes Gateway API.

ALB in front of Envoy Gateway

In the default layout, the ALB handles TLS and DNS, with Envoy Gateway behind it. Optional WAF attaches to the ALB:
The ALB target group forwards to the Envoy proxy pods on port 10080. No values overlay is needed; make init-values writes the gateway settings.

TLS and DNS

The tls_certificate_source variable controls the certificate strategy:

Why ACM versus cert-manager

ACM certificates are non-exportable. AWS attaches them directly to the ALB, which makes ACM the right choice when TLS terminates at the ALB. With the module’s gateways, TLS still terminates at the ALB, so ACM works with Envoy, Istio, and NGINX. cert-manager is only needed when you want TLS to terminate inside the cluster. The letsencrypt source is a reference implementation for the ALB path: it installs cert-manager with a Let’s Encrypt HTTP-01 ClusterIssuer bound to the ALB ingress class. For in-cluster TLS on Istio, set create_cert_manager_irsa = true instead, which uses a DNS-01 ClusterIssuer validated through Route 53. HTTP-01 (via ALB) and DNS-01 (via Route 53) are mutually exclusive. In production, swap the ClusterIssuer for any cert-manager-compatible issuer. With create_cert_manager_irsa = true, the Terraform module provisions the cert-manager IRSA role and Route 53 permissions. Only the ClusterIssuer manifest changes between issuers.

Auto-provisioned DNS

When langsmith_domain is set and acm_certificate_arn is empty, Terraform activates the dns module which creates:
  • A Route 53 public hosted zone for the domain, or, with dns_create_zone = false and dns_existing_zone_id, records in an existing public zone (the exact zone or a parent zone; no NS delegation needed).
  • An ACM certificate with DNS validation records. Add a *.<domain> SAN with dns_include_wildcard_san = true.
  • A Route 53 alias record pointing the domain to the Terraform-managed ALB. In ALB Ingress mode that ALB goes unused, so point the domain at the Ingress hostname yourself (kubectl get ingress -n langsmith).
Staged deploy pattern: Set langsmith_domain with tls_certificate_source = "none" first. Terraform creates the hosted zone and certificate without blocking on validation. Delegate the NS records at your registrar, then flip to tls_certificate_source = "acm" in a later apply. Terraform blocks until the certificate validates and wires it into the HTTPS listener.

Bring your own certificate

Set acm_certificate_arn directly to skip the dns module. For TLS that terminates inside the cluster, create a Kubernetes TLS Secret manually and reference it in the Gateway or VirtualService.

Module dependency graph

Opt-in security modules

Default resource sizes

terraform.tfvars.production, terraform.tfvars.dev, and terraform.tfvars.minimum change these sizes. Production uses db.r6g.xlarge. Dev uses m5.2xlarge nodes with db.t3.medium and cache.t3.medium. Minimum uses m5.xlarge with db.t3.small and cache.t3.small. sizing_profile (production, production-large, dev, minimum, or default) selects the matching Helm sizing overlay; default leaves chart defaults in place. For production sizing recommendations, see the scaling guide and the AWS deployment guide.

Validated behaviors and known constraints

These constraints were validated during the April 2026 gateway permutation test run.

Verification commands