top of page
検索

Terraform で実現する Langfuse on AWS

  • 執筆者の写真: 駿作 髙木
    駿作 髙木
  • 4 日前
  • 読了時間: 6分

はじめに

本記事では、この Langfuse 環境を AWS 上に構築する方法について解説します

2025/05/22 に Langfuse の公式ドキュメントにおいて、AWS 向けの Terraform 構成が公開されました。この公式ドキュメントに記載された手順をベースとし、実際に環境を構築する際の具体的なステップや留意点、さらに実運用を見据えたポイントなどを、弊社の知見を交えながらご紹介します。

本記事の Google Cloud バージョンはこちら


公式の AWS システム構成

Langfuse 環境を AWS 上に Terraform で構築するにあたり、最も信頼できる情報源は Langfuse の公式ドキュメントです。公式で AWS 向けの Terraform 構成が提供開始され、これにより導入のハードルが大きく下がりました。

まず、Langfuse 公式サイトの AWS 向けセルフホスティングガイドをご確認いただくことを強く推奨します。この公式ガイドには、Terraform で環境構築する手順が載っています。


主要コンポーネントとAWS プロダクトのマッピング

公式ドキュメントで推奨されている構成、および Langfuse の一般的なコンポーネントが AWS のどのプロダクトに対応するかを以下にまとめます。

Langfuse

コンポーネント

AWS プロダクト

主な目的・役割

Langfuse Web, Worker

Amazon Elastic Kubernetes Service (以下EKS)

Langfuseサーバーのコンテナをホスティングします。

Redis

Amazon ElastiCache

キャッシュ・キューに使用します。

Postgres - OLTP

Amazon Aurora PostgreSQL

認証情報などトランザクションデータを格納するストレージです。

ClickHouse - OLAP

コンピュート: EKS ストレージ: Amazon EFS

トレースなどを格納するストレージです。

Blob Storage

Amazon S3

生のイベントやマルチモーダルファイルを保管します。

Terraformコードの提供形態

Langfuse の GitHub リポジトリには、これらの AWS リソースを効率的にプロビジョニングするための Terraform 設定ファイル群（HCL コード）が提供されています。ユーザーは提供されたコードをベースに、ドメインや構成オプションを指定することで、推奨構成を迅速にデプロイできます。


構成図

GitHub リポジトリにある構成図は以下のとおりです。この構成は本番環境を想定した最低限のコンポーネントになっていると考えます。

システム構成図　引用：langfuse-terraform-aws
システム構成図　引用：langfuse-terraform-aws

費用の概算

最低限のランニングコストを試算しました。（リンク）

月額約 450$ となっています。


Terraform での環境構築で知っておきたい Tips 集

Langfuse の公式ドキュメントには、AWS 上に Terraform を用いて環境を構築するための手順が詳細に記載されています。基本的にはこのドキュメントに従って進めることで、迷うことなく環境をセットアップできるでしょう。

本セクションでは、実際に構築する過程で気づいた点や、よりスムーズに進めるための Tips などをまとめてご紹介します。

構築の大まかな流れ

公式ドキュメントで提供されている Terraform コードを利用した構築は、主に以下のステップで進められます。

  1. API を有効化します。

  2. 設定 HCL ファイルを用意します。ドメインを指定します。

  3. terraform init をして、先に DNS 設定だけ apply します。

  4. 全てのリソースを apply します。

所要時間: 全体のデプロイには、環境にもよりますが 20 分〜 60 分程度かかります。


構築時の Tips と留意点 💡

実際に公式ドキュメントの手順に沿って構築を進める中で、いくつか留意しておくと良い点や、カスタマイズのヒントがありました。


既知の問題について

弊社で何回か試したときは、ステップ4で以下のエラーが出て apply 失敗しました。

terraform apply
...
╷
│ Warning: Helm release "" was created but has a failed status. Use the `helm` command to investigate the error, correct it, then run Terraform again.
│ 
│   with module.langfuse.helm_release.langfuse,
│   on ../../langfuse.tf line 121, in resource "helm_release" "langfuse":
│  121: resource "helm_release" "langfuse" {
│ 
╵
╷
│ Error: context deadline exceeded
│ 
│   with module.langfuse.helm_release.langfuse,
│   on ../../langfuse.tf line 121, in resource "helm_release" "langfuse":
│  121: resource "helm_release" "langfuse" {
│ 
╵

これは公式ドキュメントで既知の問題として対処法が示されています。以下のコマンドを実行後に再び apply すれば成功します。

# Connect your kubectl to the EKS cluster
aws eks update-kubeconfig --name langfuse
 
# Restart the CoreDNS and ClickHouse containers
kubectl --namespace kube-system rollout restart deploy coredns
kubectl --namespace langfuse delete pod langfuse-clickhouse-shard0-{0,1,2} langfuse-zookeeper-{0,1,2}

設定ファイルのテンプレート活用

公式ドキュメントには設定ファイルの記述例がありますが、リポジトリ内の examples/quickstart/quickstart.tf に類似の構成ファイルが含まれている場合があります。こちらを参考にしたり、コピーして自身の環境に合わせて修正したりすると、設定ファイル作成の手間を省けることがあります。


Aurora と ElastiCache のコスト最適化

Terraform のデフォルト設定では、Aurora の容量や ElastiCache のインスタンス数が多い状態でプロビジョニングされる場合があり、特に検証用途では料金が高額になる可能性があります。開発・検証環境など、そこまで高い性能や障害耐性を求めない場合は、Langfuse モジュールの設定で以下のように調整することで、コストを大幅に抑えることができます。

module "langfuse" {
  # ... 他の変数 ...
  postgres_max_capacity   = 1.0
  cache_instance_count = 1
}

アクセスキー・リージョン未設定エラーへの対処

terraform apply 実行時などに、「アクセスキーが設定されていない」や「リージョンが設定されていない」といったエラーメッセージが表示されることがあります。これは、AWS プロバイダが対象のプロジェクトやリージョンを認識できていない場合に発生します。以下の環境変数を設定するか、Terraform のプロバイダ設定で明示的に指定してください。

export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
export AWS_REGION="YOUR_REGION"

  または、プロバイダブロックに記述します。

provider "aws" {
  access_key = "YOUR_ACCESS_KEY_ID"
  secret_key = "YOUR_SECRET_ACCESS_KEY"
  region     = "YOUR_REGION"
}

ロードバランサー周りの設定

Terraform で構築された環境でのロードバランサーは HTTP と HTTPS の2つのリスナーがあります。HTTP リスナーは HTTP から HTTPS へリダイレクトするためのものです。

HTTPS リスナーからターゲットグループへアクセスし、ポート3000に設定して Langfuse Web へリクエストをルーティングします。


まとめ

本記事では、公式ドキュメントおよび Terraform コードを利用して、AWS 上に Langfuse を構築する手順と、その過程で得られた実践的な Tips をご紹介しました。

公式に提供されている Terraform 構成を活用することで、EKS、Aurora といった AWS のマネージドサービス群を効率的かつ再現性高くプロビジョニングできることをご確認いただけたかと思います。特に、インフラ構成をコードで管理する Infrastructure as Code (IaC) のアプローチは、環境構築の迅速化だけでなく、構成変更の追跡やチーム内での共有を容易にし、属人化を防ぐ上でも大きなメリットがあります。

Langfuse は活発に開発が続けられており、LLM アプリケーション開発の効率化と品質向上に寄与する機能が今後も追加されていくことが期待されます。本記事が、皆様の AWS 上での Langfuse 導入、そして LLM を活用したイノベーション推進のお役に立てれば幸いです。ぜひ、公式ドキュメントと合わせてご活用いただき、実際の開発プロジェクトでお試しください。


Comentarios

bottom of page