LangSmith on AWS

Self-hosted deployment on EKS, managed with Terraform.

terraform/aws/
├── infra/              ← Terraform root — run terraform from here
│   ├── main.tf         ← Wires all sub-modules, IRSA + ESO role setup
│   ├── variables.tf    ← All configurable inputs with defaults
│   ├── scripts/        ← setup-env.sh, set-kubeconfig.sh, preflight.sh, quickstart.sh, quickdeploy.sh, secrets-status.sh
│   └── modules/
│       ├── vpc/        ← VPC, subnets (5 private / 3 public), NAT, route tables
│       ├── eks/        ← EKS cluster, node groups, addons, IRSA role, GP3 storage class
│       ├── postgres/   ← RDS PostgreSQL, subnet group, security group, IAM auth
│       ├── redis/      ← ElastiCache Redis, subnet group, security group
│       ├── storage/    ← S3 bucket, VPC endpoint, bucket policy (VPC-only access)
│       ├── alb/        ← Pre-provisioned ALB (opt-in; ALB access logs opt-in)
│       ├── cloudtrail/ ← CloudTrail trail + S3 bucket (opt-in)
│       ├── waf/        ← WAFv2 Web ACL attached to ALB (opt-in)
│       ├── firewall/   ← AWS Network Firewall — FQDN egress filter (opt-in)
│       └── k8s-bootstrap/ ← Namespace, KEDA, cert-manager, ESO, Envoy Gateway (opt-in)
└── helm/
    ├── scripts/        ← init-values.sh, deploy.sh, apply-eso.sh, tls.sh, uninstall.sh
    └── values/
        ├── examples/   ← Reference templates (sizing, addons, Envoy Gateway, dataplane)
        │   ├── langsmith-values-ingress-envoy-gateway.yaml  ← Gateway API overlay
        │   ├── langsmith-values-dataplane.yaml              ← langgraph-dataplane chart values
        │   └── dataplane-rbac.yaml                          ← RBAC for dataplane namespace
        └── ...         ← Active base + overrides + sizing/addon files

# Resource naming — all resources are named {name_prefix}-{environment}-*
name_prefix = "acme"          # short identifier, lowercase, no spaces
environment = "production"    # or "dev", "staging", etc.

# AWS region
region = "us-west-2"

# TLS mode: "none" (HTTP), "acm" (ACM cert on ALB/NGINX), or "letsencrypt" (cert-manager DNS-01 for Istio/Envoy)
tls_certificate_source = "none"

# VPC — set create_vpc = false to use an existing VPC
create_vpc = true
# vpc_id             = "vpc-xxxxxxxx"        # if create_vpc = false
# private_subnet_ids = ["subnet-xx", ...]    # if create_vpc = false
# public_subnet_ids  = ["subnet-xx", ...]    # if create_vpc = false

# EKS
eks_cluster_version = "1.31"
eks_managed_node_groups = {
  default = {
    name           = "node-group-default"
    instance_types = ["m5.4xlarge"]
    min_size       = 3
    max_size       = 10
  }
}

# RDS PostgreSQL
postgres_instance_type = "db.t3.large"
postgres_storage_gb    = 10

# ElastiCache Redis
redis_instance_type = "cache.m6g.xlarge"

# Gateway mode — pick ONE (all false = ALB native, simplest)
# enable_nginx_ingress = true   # ALB → NGINX controller → pods
# enable_envoy_gateway = true   # ALB → Envoy proxy:10080 → HTTPRoutes (split dataplane)
# enable_istio_gateway = true   # ALB → Istio:80 → VirtualService (mTLS mesh)

# TLS: "none" (HTTP), "acm" (ACM cert on ALB), "letsencrypt" (cert-manager DNS-01)
tls_certificate_source = "none"
# langsmith_domain = "langsmith.example.com"  # auto-provisions Route 53 zone + ACM cert

# Sizing + addon flags
sizing_profile     = "production"
# enable_deployments   = true
# enable_agent_builder = true
# enable_insights      = true
# enable_polly         = true

# backend.tf
terraform {
  backend "s3" {
    bucket = "your-terraform-state-bucket"
    key    = "langsmith/aws/terraform.tfstate"
    region = "us-west-2"
  }
}

cd terraform/aws

# Generate terraform.tfvars interactively (re-run safe — Enter accepts current values)
make quickstart

# Prompts for license key and admin password; auto-generates salt and JWT secret.
# Stores all secrets in SSM Parameter Store — sourced (not executed) to export TF_VAR_*
source infra/scripts/setup-env.sh

make init
make plan
make apply

# Sets kubeconfig to the EKS cluster
make kubeconfig

# Verify cluster access
kubectl get nodes
kubectl get pods -n kube-system

cd terraform/aws

# Reads Terraform outputs and generates Helm values with
# RDS endpoint, Redis endpoint, S3 bucket, IRSA role ARN, and regional S3 API URL
make init-values

# Applies ESO ClusterSecretStore + ExternalSecret (syncs SSM → K8s secret),
# then runs helm upgrade --install
make deploy

# infra/terraform.tfvars
sizing_profile = "production"         # multi-replica with HPA (recommended)
sizing_profile = "production-large"   # high-volume (~50 users, ~1000 traces/sec)
sizing_profile = "dev"                # single-replica, minimal resources (dev/CI/demos)
sizing_profile = "default"            # chart defaults (no sizing overlay applied)

# Re-generate values after changing sizing_profile:
make init-values && make deploy

kubectl get pods -n langsmith
kubectl get ingress -n langsmith

# infra/terraform.tfvars
enable_deployments = true

cd terraform/aws
make init-values   # copies langsmith-values-agent-deploys.yaml with correct TLS setting
make deploy

# Generate a Fernet key
KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

# Store in SSM — replace <name_prefix> and <environment> with your terraform.tfvars values
aws ssm put-parameter \
  --region <region> \
  --name "/langsmith/<name_prefix>-<environment>/agent-builder-encryption-key" \
  --value "$KEY" \
  --type SecureString

# infra/terraform.tfvars
enable_agent_builder = true   # requires enable_deployments = true

cd terraform/aws
make init-values   # copies langsmith-values-agent-builder.yaml
make deploy

# Agent Builder pods (appear after bootstrap job completes — ~5 min)
kubectl get pods -n langsmith | grep -E "agent-builder|lg-"

# Bootstrap job status
kubectl get jobs -n langsmith | grep bootstrap

KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

aws ssm put-parameter \
  --region <region> \
  --name "/langsmith/<name_prefix>-<environment>/insights-encryption-key" \
  --value "$KEY" \
  --type SecureString

# infra/terraform.tfvars
enable_insights   = true
clickhouse_source = "external"

# Fill in after obtaining your ClickHouse credentials:
# clickhouse_host = "<clickhouse-hostname>"
# clickhouse_port = 9440   # native protocol (TLS)
# clickhouse_tls  = true

cd terraform/aws
make init-values   # copies langsmith-values-insights.yaml with your ClickHouse config
make deploy

# Insights deploys a Clio pod on first invocation from the UI
kubectl get pods -n langsmith | grep clio

cd terraform/aws

make quickstart              # generates terraform.tfvars interactively
source infra/scripts/setup-env.sh   # creates SSM secrets + exports TF_VAR_* (must be sourced)
make init && make plan && make apply   # ~20–25 min
make kubeconfig
make init-values
make deploy

make status            # full deployment health check
make deploy            # re-deploy after changing Helm values or upgrading chart
make init-values       # re-generate values after Terraform changes
make apply-eso         # re-sync ESO secrets without redeploying
make ssm               # manage SSM Parameter Store secrets interactively
make kubeconfig        # refresh cluster credentials

# infra/terraform.tfvars — set flags, then: make init-values && make deploy
enable_deployments   = true   # required for Agent Builder and Polly
enable_agent_builder = true   # requires enable_deployments = true
enable_insights      = true
enable_polly         = true   # requires enable_deployments = true + Polly entitlement
enable_usage_telemetry = false  # extended usage telemetry (optional)

# infra/terraform.tfvars — pick ONE:
enable_nginx_ingress = true    # ALB → NGINX → pods (ACM TLS at ALB)
enable_envoy_gateway = true    # ALB → Envoy proxy:10080 → HTTPRoutes (split dataplane)
enable_istio_gateway = true    # ALB → Istio:80 → VirtualService (mTLS, DNS-01 TLS)

make quickstart      # wizard adds gateway selection (Section 6)
make apply           # re-installs gateway controller via k8s-bootstrap
make init-values     # regenerates values overlay for new gateway mode
make deploy

# infra/terraform.tfvars — all opt-in, all default false:
alb_access_logs_enabled = true    # ALB traffic logs → S3
create_cloudtrail       = true    # AWS API audit trail
create_waf              = true    # WAFv2 on ALB (~$10/mo)
create_firewall         = true    # AWS Network Firewall FQDN egress (~$0.40/hr)
create_bastion          = true    # SSM/SSH bastion for private EKS access