docs(self-hosted): add Terraform guides for AWS, GCP, and Azure#4187
Open
devfreddy-langchain wants to merge 10 commits into
Open
docs(self-hosted): add Terraform guides for AWS, GCP, and Azure#4187devfreddy-langchain wants to merge 10 commits into
devfreddy-langchain wants to merge 10 commits into
Conversation
Wave 0 of migrating Terraform deployment guides from langchain-ai/ps-ops-center into public docs as a peer to the existing Helm path. Adds an overview page covering provider choice, prereqs, two-pass model, deployment tiers, and an SA-package callout, plus a new "Deploy with Terraform" nav group under LangSmith > Platform setup > Self-hosted, positioned right after the cloud-provider landing pages so customers see the TF vs Helm choice up front. Cross-links from each cloud-provider landing page and the existing Helm install guide point at the new overview. Provider sub-pages and architecture diagrams land in subsequent waves; image assets are staged now to keep wave PRs small.
Wave 1 of the Terraform docs migration. Adds six AWS-specific pages under
the new "Deploy with Terraform" group:
- Prerequisites: tools, IAM permissions, AWS auth, license + domain.
- Quickstart: end-to-end EKS deploy walkthrough (Pass 1 infrastructure,
Pass 2 application via script-driven or Terraform-managed Helm), plus
optional Envoy Gateway ingress and private cluster + bastion patterns.
- Architecture: platform layers, services, IRSA, networking, ingress
options, TLS, module dependency graph, validated behaviors.
- Quick reference: make targets, kubectl, AWS CLI, Helm, Terraform.
- Troubleshooting: 16 known issues with fixes + diagnostic commands.
- Teardown: terraform destroy path + manual AWS CLI path when state is
lost, including IAM, VPC, and orphan cleanup.
Source content adapted from github.com/langchain-ai/terraform/modules/aws
(README, ARCHITECTURE, QUICK_REFERENCE, COMMANDS, SERVICES, TROUBLESHOOTING,
TEARDOWN) and from internal ps-ops-center/docs/content/aws/. Module paths
updated from the source docs' stale "terraform/aws/" references to the
current "modules/aws/" layout. Audience reframed from SA-zip delivery to
public self-serve via git clone.
The Wave 0 overview page now links its AWS provider card to the new
quickstart. Azure, GCP, and OpenShift land in subsequent waves.
Wave 2 of the Terraform docs migration. Adds five GCP-specific pages under
the new "Deploy with Terraform" group:
- Quickstart: end-to-end GKE deploy walkthrough covering all 5 passes
(infra, base, LangSmith Deployment, Agent Builder, Insights + Polly),
plus prereqs (tools, APIs, IAM, auth), sizing profiles, and key watchouts.
- Architecture: platform layers, module descriptions, deployment tiers
(light vs. production), traffic flow, Workload Identity, Secret Manager
integration, and the Terraform module graph.
- Quick reference: make targets, kubectl, gcloud, Helm, Terraform cheat
sheet plus add-on / sizing toggles.
- Troubleshooting: 14 known issues (APIs, GKE, Cloud SQL peering,
Memorystore, cert-manager, GCS, Envoy Gateway IP churn, Workload
Identity, langsmith-ksa, Helm pending-upgrade, Secret Manager).
- Teardown: terraform destroy path + manual gcloud path when state is
lost, including private service connection cleanup and VPC ordering.
Source adapted from github.com/langchain-ai/terraform/modules/gcp (README,
ARCHITECTURE, QUICK_REFERENCE, SERVICES, TROUBLESHOOTING, TEARDOWN) and from
internal ps-ops-center/docs/content/gcp/. Module paths updated from the
source docs' stale "gcp/" / "terraform/gcp/" references to the current
"modules/gcp/" layout. Audience reframed from SA-zip delivery to public
self-serve via git clone. The Wave 0 overview page now links its GCP card
to the new quickstart.
Wave 3 of the Terraform docs migration. Adds eleven Azure-specific pages
under the new "Deploy with Terraform" group:
- Quickstart: end-to-end AKS deploy walkthrough with prereqs and the
5-pass model overview.
- Pass 1: infrastructure provisioning (AKS, VNet, PostgreSQL, Redis,
Blob, Key Vault, cert-manager, KEDA, ingress).
- Pass 2: LangSmith Helm install (script-driven and Terraform paths).
- Pass 3: LangSmith Deployment (host-backend, listener, operator).
- Pass 4: Agent Builder.
- Pass 5: Insights + Polly.
- Architecture: platform layers, services, Workload Identity matrix,
networking, ingress options, secret flow.
- Quick reference: make targets, kubectl, az, Terraform, key watchouts.
- Variables: full input-variable reference.
- Troubleshooting: 25+ known issues including K8sVersion, vCPU quota,
Key Vault purge protection, DNS label, istio-addon, Workload Identity,
AGIC, Istio, encryption key gotchas, OOM, stuck HPAs.
- Teardown: 3-step procedure, Key Vault soft-delete handling.
Source adapted from github.com/langchain-ai/terraform/modules/azure
(README, ARCHITECTURE, QUICK_REFERENCE, SERVICES, INGRESS_CONTROLLERS,
TROUBLESHOOTING, TEARDOWN) and from internal ps-ops-center/docs/content/
azure/. Module paths updated from "terraform/azure/" to the current
"modules/azure/" layout. Audience reframed from SA-zip delivery to
public self-serve via git clone.
The Wave 0 overview page now links its Azure card to the new quickstart.
Also includes copy-edit polish across the AWS and GCP pages from the
same session for consistent voice.
Wave 4 of the Terraform docs migration. Adds eight OCP-specific pages
under the new "OpenShift (preview)" sub-group within "Deploy with
Terraform":
- Quickstart: planned production path (ROSA / on-prem OCP) plus the
current Single Node OpenShift on Azure POC.
- Pass 1: infrastructure setup (operators, RBAC, storage classes).
- Pass 2: Helm install with OpenShift Route vs Gateway API guidance.
- Architecture: SNO-on-Azure POC topology, nip.io DNS, planned
module layout, key differences from AKS/GKE/EKS, VM sizing.
- Quick reference: oc + kubectl + helm commands for OCP.
- Variables: planned Terraform variable reference (preview).
- Troubleshooting: SCC, Route vs Gateway API, ODF / MinIO storage.
- Teardown: planned 3-pass order plus POC Azure-host destroy.
Every OCP page carries a preview warning. The Wave 0 overview page now
links its OpenShift card to the new quickstart. Source adapted from
github.com/langchain-ai/terraform/modules/ocp (README, ARCHITECTURE,
QUICK_REFERENCE, TROUBLESHOOTING, TEARDOWN) and from internal
ps-ops-center/docs/content/ocp/. Includes additional copy-polish
across earlier waves' troubleshooting pages from the same session.
… guides Apply Vale prose cleanups to bring the new Azure and OpenShift guides in line with the AWS/GCP pages: replace `via` with `with`/`through`, convert "Known issues" intros to active voice, restructure passive constructions, drop wordy phrases (`Minimum version` → `Version`, drop `safely`), and lowercase "pass" in heading sentence case. CI-clean at the error level. Remaining warning-level findings are all defensible false positives (product-name headings like `PostgreSQL` / `Key Vault`, Terraform's `destroy` subcommand, "Let's Encrypt" product name, and technical compounds like `LTS-only`).
Contributor
|
Thanks for opening a docs PR, devfreddy-langchain! When it's ready for review, please add the relevant reviewers:
|
- Add lowercase `aks` to codespell ignore list (matches `module.aks` Terraform refs; uppercase `AKS` was already ignored but codespell is case-sensitive) - Replace `pre-select(ed/s)` with `preselect(ed/s)` to match the existing `prebuilt` style convention
…pages Restructures AWS and GCP Terraform guides to match the new ps-ops-center source layout. Both quickstarts shrink to rapid-path overviews that point at dedicated pass pages. AWS additions: pass-1 (infrastructure), pass-2 (LangSmith application, including Envoy Gateway and Terraform-managed paths), and a full variables reference page. GCP additions: pass-1 (infrastructure with preflight step), pass-2 (scripted and manual Helm paths), pass-3 (LangSmith Deployment plus Agent Builder, Insights, and Polly add-ons), and a full variables reference page. Nav updated to insert the new pages under each provider group.
…rminology Collapse each provider's quickstart, prerequisites, and per-pass walkthroughs into a single deploy.mdx so customers follow one continuous narrative instead of hopping between numbered pages. Delete OCP entirely (preview status no longer justified the maintenance overhead) and remove the teardown pages (standard terraform destroy patterns plus per-provider quick reference cover day-2 needs). Rename "Pass N" sections to descriptive headings (Infrastructure, LangSmith application, LangSmith Deployment add-on, etc.) across architecture, variables, troubleshooting, and quick-reference pages. Final shape per provider: deploy + architecture + variables + quick-reference + troubleshooting. Vale and broken-links checks pass.
Contributor
|
Mintlify preview branch generated: Site preview: https://langchain-5e9cc07a-preview-featse-1779998369-ad736a3.mintlify.app Preview links may take a few minutes to start working while the deployment finishes. Changed documentation pages (preview deep links):
Only the top 5 changed markdown files by diff size are listed. |
devfreddy-langchain
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why
Self-hosted enterprise customers using the public Terraform modules at github.com/langchain-ai/terraform have so far been pointed at provider READMEs. This PR brings those walkthroughs into the official docs so the in-product Terraform path matches the experience the Helm path has had.
Areas needing careful review
Test plan
make lint_prosepasses (verified locally: 0 errors across all 30 terraform docs)make broken-linkspasses/langsmith/self-host-terraform-{aws,gcp,azure,ocp}-quickstartURLs matchsrc/docs.jsonAI involvement
Drafted in collaboration with Claude Code (Opus 4.7). Author directed content and accuracy; Claude assisted with prose drafting, Vale lint cleanup passes, and consistency between provider sections.