Guide Quick Reference Architecture Troubleshooting Teardown

Quickstart

Get from zero to a running LangSmith instance on OpenShift in under an hour.

Status: Coming Soon

The OCP Terraform module is under active development. The commands below reflect the planned fast-path deployment. Return to the full guide below for the current POC approach and architecture details.

# 1 — Unzip the Terraform modules provided by your LangChain SA
unzip ocp.zip
cd ocp

# 2 — Authenticate to your OpenShift cluster
oc login --token=<token> --server=<api-url>
oc whoami   # verify
oc version  # confirm cluster version

# 3 — Deploy infrastructure (Terraform)
cd infra/langsmith
terraform init
terraform apply

# 4 — Deploy LangSmith via Helm
helm repo add langchain https://langchain-ai.github.io/helm
helm repo update

helm install langsmith langchain/langsmith \
  -f langsmith-values.yaml \
  -n langsmith --create-namespace \
  --set config.langsmithLicenseKey="<license-key>"

# 5 — Verify pods are running
kubectl get pods -n langsmith

What gets deployed

Pass 1 sets up namespaces, RBAC, and operators (Crunchy PGO, Redis, cert-manager) with MinIO or ODF storage. Pass 2 installs the LangSmith Helm chart. Pass 3 adds Deployments (host-backend, listener, operator). Full Terraform automation will be published in a future release.

Professional Services — OpenShift OCP

LangSmith on OCP
Self-hosted deployment on OpenShift Container Platform.

Status: Coming Soon

The OCP Terraform module is under active development. The architecture and POC deployment guide are available. Full Terraform automation will be published in a future release.

Infrastructure

planned

LangSmith

planned

Deployments

planned

Infrastructure

Namespaces, RBAC, operators (Crunchy PGO, Redis, cert-manager), MinIO or ODF storage

Required

LangSmith

LangSmith Helm chart — traces, prompts, evaluations, org management

Required

LangSmith Deployments

LangSmith Deployments — deploy and manage LangGraph graphs from the UI

Optional

Prerequisites

Required tools

bash

# OpenShift CLI
# Download from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/
oc version   # verify

# Terraform (>= 1.5)
brew tap hashicorp/tap && brew install hashicorp/tap/terraform

# Helm (>= 3.12)
brew install helm

# kubectl (or use oc as a drop-in replacement)
brew install kubectl

Required access

Requirement	Notes
OpenShift 4.12+ or ROSA cluster	Cluster admin role required for initial setup
LangSmith license key	Contact your LangChain representative. Required for self-hosted deployments.
S3-compatible object storage	ODF (OpenShift Data Foundation), MinIO, or external S3. Blob payloads must not go into ClickHouse.

Authenticate to the cluster

bash

# Login to OpenShift
oc login --token=<token> --server=<api-url>

# Verify
oc whoami
oc version

Repository Layout

terraform/ocp/infra/
├── azure-host/          Terraform — provisions the Azure "baremetal" host VM (POC)
│   ├── main.tf          Resource group, VNet, NSG, NIC, VM, data disk
│   ├── variables.tf
│   ├── outputs.tf       Exposes public IP, SSH command, nip.io URLs
│   └── templates/
│       └── cloud-init.yaml
│
├── scripts/             Manual step-by-step install scripts (run after SSH)
│   ├── 00-check-prereqs.sh
│   ├── 01-setup-kvm.sh
│   ├── 02-install-ocp-tools.sh
│   ├── 03-generate-sno-iso.sh
│   ├── 04-deploy-sno.sh
│   └── 05-post-install.sh
│
└── langsmith/           (coming soon) Terraform for LangSmith on OCP

POC vs Production

The current azure-host/ module provisions a Single Node OpenShift POC on an Azure VM. Production deployments target ROSA or on-premises OpenShift 4.12+ clusters.

Configuration

Initialize Terraform (azure-host POC)

bash

cd terraform/ocp/infra/azure-host
terraform init
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your Azure subscription ID and public SSH key

Planned variables (langsmith module)

hcl

# terraform/ocp/infra/langsmith/terraform.tfvars (coming soon)
kubeconfig_path    = "~/.kube/config"
kubeconfig_context = "default/api-<cluster>:<port>/<user>"

langsmith_license_key = "<license-key>"
langsmith_hostname    = "langsmith.apps.<cluster-domain>"

# Storage: "minio" | "odf" | "external-s3"
blob_storage_type     = "minio"

deploy_langsmith              = true
enable_langsmith_deployments  = false

Pass 1 — Required Infrastructure

What gets configured
Namespaces, RBAC, operators, storage classes, cert-manager, in-cluster backing services

Note
OCP cluster is assumed pre-existing. Pass 1 configures Kubernetes resources on top of it.

SCC — Security Context Constraints

OpenShift enforces SCCs more strictly than standard Kubernetes pod security. LangSmith pods may require the nonroot SCC or a custom SCC. This is handled automatically when the Terraform module is available.

POC — Single Node OpenShift on Azure (existing scripts)

bash

# 1. Provision Azure "baremetal" host
cd terraform/ocp/infra/azure-host
terraform apply

# 2. SSH to the host and run scripts in order
ssh <public-ip>
sudo bash /opt/scripts/00-check-prereqs.sh
sudo bash /opt/scripts/01-setup-kvm.sh
sudo bash /opt/scripts/02-install-ocp-tools.sh
sudo bash /opt/scripts/03-generate-sno-iso.sh
sudo bash /opt/scripts/04-deploy-sno.sh
sudo bash /opt/scripts/05-post-install.sh

Pass 1 — Infrastructure

The OCP cluster is assumed pre-existing (ROSA or on-premises OpenShift 4.12+). Pass 1 configures Kubernetes resources on top of it: namespaces, RBAC, operators (Crunchy PGO, Redis, cert-manager), and storage classes.

Status: Coming Soon

The OCP Terraform module (`terraform/ocp/infra/langsmith/`) is under active development. The steps below reflect the planned deployment model and current POC scripts.

POC — Single Node OpenShift on Azure

The current working path uses terraform/ocp/infra/azure-host/ to provision a simulated baremetal host, then runs setup scripts inside it.

Step 1: Provision the Azure host

cd terraform/ocp/infra/azure-host
terraform init
cp terraform.tfvars.example terraform.tfvars
# Edit: set your Azure subscription ID and public SSH key
terraform apply

Step 2: SSH to the host and run setup scripts in order

ssh <public-ip>

sudo bash /opt/scripts/00-check-prereqs.sh
sudo bash /opt/scripts/01-setup-kvm.sh
sudo bash /opt/scripts/02-install-ocp-tools.sh
sudo bash /opt/scripts/03-generate-sno-iso.sh
sudo bash /opt/scripts/04-deploy-sno.sh
sudo bash /opt/scripts/05-post-install.sh

Step 3: Verify cluster access

oc whoami
oc get nodes
oc get co   # check all cluster operators are Available

Planned production path (ROSA / on-prem OCP)

When the Terraform module is available, Pass 1 will run:

cd terraform/ocp/infra
terraform init
cp terraform.tfvars.example terraform.tfvars
# Edit: kubeconfig_path, langsmith_license_key, blob_storage_type

terraform apply

Planned variables:

kubeconfig_path    = "~/.kube/config"
kubeconfig_context = "default/api-<cluster>:<port>/<user>"

langsmith_license_key = "<license-key>"
langsmith_hostname    = "langsmith.apps.<cluster-domain>"

# Storage: "minio" | "odf" | "external-s3"
blob_storage_type = "minio"

SCC — Security Context Constraints

OpenShift enforces SCCs more strictly than standard Kubernetes pod security. LangSmith pods may require the `nonroot` SCC or a custom SCC. This is handled automatically when the Terraform module is available.

Pass 2 — Required LangSmith

What gets created
LangSmith Helm release in the langsmith namespace

Duration
~10 minutes

bash

helm repo add langchain https://langchain-ai.github.io/helm
helm repo update

helm install langsmith langchain/langsmith \
  -f langsmith-values.yaml \
  -n langsmith --create-namespace \
  --set config.langsmithLicenseKey="<license-key>" \
  --set config.hostname="langsmith.apps.<cluster-domain>"

OpenShift Route vs Gateway API

OpenShift Routes are the default ingress mechanism on OCP. The Gateway API (via OpenShift Gateway API or Istio) is available on OCP 4.13+. Configure ingress.type in Helm values accordingly.

Pass 2 — LangSmith

Deploy the LangSmith Helm chart into the langsmith namespace.

Duration: ~10 minutes.

Add the Helm repo

helm repo add langchain https://langchain-ai.github.io/helm
helm repo update

Install LangSmith

helm install langsmith langchain/langsmith \
  -f langsmith-values.yaml \
  -n langsmith --create-namespace \
  --set config.langsmithLicenseKey="<license-key>" \
  --set config.hostname="langsmith.apps.<cluster-domain>"

Verify

kubectl get pods -n langsmith
kubectl get svc -n langsmith

OpenShift Route vs Gateway API

# langsmith-values.yaml — Route-based ingress (default for OCP)
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: "openshift-default"

For Gateway API (OCP 4.13+ with OpenShift Gateway API or Istio):

ingress:
  enabled: false
gateway:
  enabled: true

OpenShift Route vs Gateway API

OpenShift Routes are the default ingress mechanism on OCP. The Gateway API is available on OCP 4.13+. Configure `ingress.type` in Helm values accordingly — check your cluster version before choosing.

Pass 3 — Optional LangSmith Deployments

What gets created
LangSmith Deployments — deploy and manage LangGraph graphs from the UI

Duration
~5 minutes

bash

# Remove LGP deployments before teardown
kubectl delete lgp --all -n langsmith
kubectl delete crd lgps.apps.langchain.ai

# Enable via Helm upgrade
helm upgrade langsmith langchain/langsmith \
  -n langsmith \
  --reuse-values \
  --set langsmithDeployments.enabled=true

Architecture Overview

The current POC runs Single Node OpenShift (SNO) inside a KVM guest on an Azure "baremetal" VM. All traffic is port-forwarded from the Azure public IP through firewalld to the SNO node.

Your Laptop
    │
    │  SSH (22) · API (6443) · HTTPS (443) · HTTP (80)
    ▼
┌─────────────────────────────────────────────────────┐
│  Azure VM  (Standard_D16s_v5 · 16 vCPU / 64 GB)   │
│  "Simulated Baremetal Host"                         │
│                                                     │
│  ┌──────────────────────────────────────────────┐  │
│  │  KVM Guest: sno-master                       │  │
│  │  12 vCPU / 48 GB RAM / 400 GB disk           │  │
│  │  IP: 192.168.126.10 (virbr1 NAT bridge)      │  │
│  │                                              │  │
│  │  Single Node OpenShift 4.14                  │  │
│  │  ├── Pass 1 — In-cluster backing services    │  │
│  │  │   ├── Crunchy PGO   → PostgreSQL          │  │
│  │  │   ├── Redis          → in-cluster Redis   │  │
│  │  │   ├── MinIO          → S3-compat storage  │  │
│  │  │   └── cert-manager   → TLS (Let's Encrypt)│  │
│  │  ├── Pass 2 — LangSmith Base Platform        │  │
│  │  │   └── Helm chart (langsmith namespace)    │  │
│  │  └── Pass 3 — LangSmith Deployments          │  │
│  │      └── LangGraph Platform (optional)       │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  firewalld port-forward:                           │
│    :6443 → 192.168.126.10:6443  (API)             │
│    :443  → 192.168.126.10:443   (HTTPS / console) │
│    :80   → 192.168.126.10:80    (HTTP / ACME)     │
└─────────────────────────────────────────────────────┘

DNS: nip.io (zero-config)

The POC uses nip.io — the public IP is embedded in the domain name, no DNS setup required.

Public IP: <public-ip>
Base domain: <ip-dashes>.nip.io

API server:  https://api.sno-langsmith.<ip-dashes>.nip.io:6443
OCP console: https://console-openshift-console.apps.sno-langsmith.<ip-dashes>.nip.io
LangSmith:   https://langsmith.apps.sno-langsmith.<ip-dashes>.nip.io

Key differences from AKS / GKE / EKS

Concern	AKS / GKE / EKS	OCP
Ingress	NGINX / Envoy / ALB	OpenShift Route or Gateway API
Security context	Standard pod security	SCC (Security Context Constraints)
Storage	Cloud-native CSI	ODF / Rook-Ceph or in-cluster MinIO
Identity	Workload Identity / IRSA	OpenShift service account tokens
Operators	Helm-only	OLM (Operator Lifecycle Manager)
DNS	Cloud DNS / external-dns	nip.io (POC) / custom domain (prod)

Variable Reference

The Terraform module variables are planned. The following are indicative based on the deployment model.

Variable	Default	Description
`kubeconfig_path`	required	Path to kubeconfig file
`kubeconfig_context`	`""`	Kubernetes context to use
`langsmith_license_key`	required	LangSmith license key
`langsmith_hostname`	required	FQDN for the LangSmith UI
`blob_storage_type`	`minio`	`minio`, `odf`, or `external-s3`
`deploy_langsmith`	`true`	Deploy LangSmith Helm chart (Pass 2)
`enable_langsmith_deployments`	`false`	Enable LangSmith Deployments (Pass 3)

Variable Reference

The OCP Terraform module is planned. The following variables are indicative based on the deployment model.

Variable	Default	Description
`kubeconfig_path`	required	Path to kubeconfig file
`kubeconfig_context`	`""`	Kubernetes context to use
`langsmith_license_key`	required	LangSmith license key
`langsmith_hostname`	required	FQDN for the LangSmith UI
`blob_storage_type`	`minio`	`minio`, `odf`, or `external-s3`
`deploy_langsmith`	`true`	Deploy LangSmith Helm chart (Pass 2)
`enable_langsmith_deployments`	`false`	Enable LangSmith Deployments (Pass 3)

Key differences from AKS / GKE / EKS

Concern	AKS / GKE / EKS	OCP
Ingress	NGINX / Envoy / ALB	OpenShift Route or Gateway API
Security context	Standard pod security	SCC (Security Context Constraints)
Storage	Cloud-native CSI	ODF / Rook-Ceph or in-cluster MinIO
Identity	Workload Identity / IRSA	OpenShift service account tokens
Operators	Helm-only	OLM (Operator Lifecycle Manager)
DNS	Cloud DNS / external-dns	nip.io (POC) / custom domain (prod)

Quickstart

LangSmith on OCPSelf-hosted deployment on OpenShift Container Platform.

Prerequisites

Required tools

Required access

Authenticate to the cluster

Repository Layout

Configuration

Initialize Terraform (azure-host POC)

Planned variables (langsmith module)

Pass 1 — Required Infrastructure

POC — Single Node OpenShift on Azure (existing scripts)

Pass 1 — Infrastructure

POC — Single Node OpenShift on Azure

Step 1: Provision the Azure host

Step 2: SSH to the host and run setup scripts in order

Step 3: Verify cluster access

Planned production path (ROSA / on-prem OCP)

Pass 2 — Required LangSmith

Pass 2 — LangSmith

Add the Helm repo

Install LangSmith

Verify

OpenShift Route vs Gateway API

Pass 3 — Optional LangSmith Deployments

Architecture Overview

DNS: nip.io (zero-config)

Key differences from AKS / GKE / EKS

Variable Reference

Variable Reference

Key differences from AKS / GKE / EKS

LangSmith on OCP
Self-hosted deployment on OpenShift Container Platform.