top of page
検索

Terraform で実現する Langfuse on Google Cloud

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

更新日：4 日前

はじめに

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

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

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


公式の Google Cloud システム構成

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

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


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

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

Langfuse コンポーネント

Google Cloud

プロダクト

主な目的・役割

Langfuse Web, Worker

Google Kubernetes Engine

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

Redis

Memorystore for Redis

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

Postgres - OLTP

Cloud SQL for PostgreSQL

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

ClickHouse - OLAP

Google Kubernetes Engine

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

Blob Storage

Google Cloud Storage

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

Terraformコードの提供形態

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


想定される構成図

これらのコンポーネントから想定される構成は以下のようになります。これは弊社が以前投稿した記事：Google CloudでLangfuse v3の構築手順（推奨設定/GKE）と同じ構成となっています。

システム構成図
システム構成図

本番運用を見据えたアーキテクチャ選択について

セルフホストする際のインストールパターンは多岐に渡り、使用する場面に合わせて選択するのが良いです。これらセルフホスティングのパターンについてはこちらの記事で解説しています。

公式 Terraform のシステム構成では、Langfuse Web, Langfuse Workder, ClickHouse に Google Kubernetes Engine (GKE) を使用した構築を選択しています。この選択の理由と、他の主要なホスティングオプションとの比較を以下に示します。

  • Google Kubernetes Engine (GKE)

  • 強み: 本番グレードのオートスケーリング、詳細なネットワーク制御、高可用性を実現します。将来的な機能拡張やデータ増大にも柔軟に対応できる、最も堅牢な選択肢です。

  • 考慮点: 高機能かつ柔軟である反面、運用コストは他の選択肢より高くなる傾向があり、Kubernetes の運用知識と管理スキルが求められます。

  • Cloud Run

  • 特性: サーバーレスで迅速なデプロイが可能であり、運用負荷とコストを抑えたい場合に適しています。オートスケーリングの機能も備わっています。

  • GKE との比較: GKEほどの高度なカスタマイズ性や、複数ポート利用といった要件への対応は限定的です。

  • Compute Engine (GCE)

  • 特性: docker compose コマンドにより簡単にデプロイ可能です。

  • GKE との比較: コンテナ化された Langfuse アプリケーションの運用（特にClickHouse のコンテナ）においては、GKE のようなオーケストレーション機能がないため、スケーリング、自己修復、ローリングアップデートといった運用効率で劣ります。


費用の概算

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

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


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

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

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

構築の大まかな流れ

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

  1. API を有効化します。

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

  3. terraform init をして、先に DNS 設定と GKE クラスターだけ apply します。

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

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


構築時の Tips と留意点 💡

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


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

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


リソースの削除保護について

デフォルト設定では、安全のために Cloud SQL インスタンスなどの主要リソースに削除保護 (deletion_protection = true) が有効になっていることがあります。検証目的などで頻繁にリソースの作成・削除を行いたい場合は、Langfuse の Terraform モジュールで明示的に指定することで、Terraform による削除が可能になります。

module "langfuse" {
  # ... 他の変数 ...
  deletion_protection = false
}

Cloud SQL インスタンスのコスト最適化

Terraform のデフォルト設定では、Cloud SQL インスタンスが比較的高性能なマシンタイプ（db-perf-optimized-N-2）でプロビジョニングされる場合があり、特に検証用途ではオーバースペックで料金が高額になる可能性があります。開発・検証環境など、そこまで高い性能を求めない場合は、Langfuse モジュールの設定で以下のようにマシンタイプやアベイラビリティタイプを調整することで、コストを大幅に抑えることができます。

module "langfuse" {
  # ... 他の変数 ...
  database_instance_tier              = "db-f1-micro"
  database_instance_availability_type = "ZONAL"
  database_instance_edition           = "ENTERPRISE"
}

Cloud DNS を別プロジェクトで管理している場合

Langfuse の Terraform 構成に Cloud DNS ゾーンやレコード作成が含まれている場合で、DNS 管理を別の Google Cloud プロジェクトで行っているケースでは、dns.tf ファイル内の "Create Cloud DNS zone" と "Create DNS A record for the load balancer" の2つのDNS 関連のリソース定義をコメントアウト、または削除する必要があります。terraform apply が完了後、コンソールで Aレコードを編集して HTTPS の方の Load Balancer のフロントエンドの IP アドレスにします。


GCS HMAC キー発行時の認証について

Google Cloud コンソールからはユーザーアカウントで HMAC キーを発行できますが、Terraform（サービスアカウント経由）でユーザーアカウントの HMAC キーを直接発行することはできません。サービスアカウント自身の HMAC キーを発行することは可能です。組織ポリシーでサービスアカウントから HMAC キーを発行を制限している場合は注意が必要です。


プロジェクトID・リージョン未設定エラーへの対処

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

export GOOGLE_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_REGION="YOUR_REGION"

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

provider "google" {
  project = "YOUR_PROJECT_ID"
  region  = "YOUR_REGION"
}

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

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

HTTPS ロードバランサーには2つのバックエンドがあります。これは、ポート3000でアクセスできるならポート指定するパスルール設定のようです。


まとめ

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

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

本記事でご紹介した Tips、特に Cloud SQL インスタンスのサイジング調整などは、コストを意識した運用を行う上で重要なポイントです。これらを参考に、ご自身のユースケースや予算に合わせて環境を最適化してください。

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

Comments

bottom of page