llms.txt × Claude Code で ScalarDB Cluster のローカル検証環境を自動構築する

ScalarDB Cluster をローカルの Kubernetes（minikube）環境にデプロイする作業は、PostgreSQL のセットアップ、TLS 証明書の生成、Kubernetes Secret の作成、Helm Chart の設定など、多くのステップを伴います。この記事では、セットアップ手順を llms.txt 形式のドキュメントにまとめ、Claude Code に読み込ませることで、環境構築を自動化した実践例を紹介します。

構築した環境の全体像は以下の通りです。

• ScalarDB Cluster 3.17.0（TLS + 認証有効）
• Envoy（gRPC ロードバランサー）
• PostgreSQL（バックエンド DB）
• SQL CLI / Schema Loader / Java Client SDK

対象読者

• ScalarDB Cluster のローカル検証環境を構築したいエンジニア
• Claude Code を使ったインフラ構築の自動化に興味がある方
• Helm Chart を使った Kubernetes デプロイの実践例を探している方

---

背景・目的

ScalarDB Cluster は、複数のマイクロサービスにまたがる分散トランザクションを実現するデータベースミドルウェアです。本番環境では Kubernetes 上にデプロイして利用するケースが多く、ローカルでの検証環境構築にも Kubernetes（minikube）+ Helm Chart を使用します。

しかし、公式ドキュメントに沿って手作業で構築すると、以下のような課題があります。

• 手順が多い: Prerequisites の確認から Helm デプロイ、クライアントツールのセットアップまで 10 以上のステップがある
• 環境依存のトラブル: macOS Apple Silicon 特有のメモリ制限やパス設定の問題が発生しやすい
• べき等性の担保: 途中で失敗した場合のリトライや、既存リソースとの競合処理を考慮する必要がある

そこで、セットアップ手順全体を llms.txt 形式でドキュメント化し、Claude Code に実行させるアプローチを試みました。

---

llms.txt とは

llms.txt は、Web サイトや製品の情報を LLM（大規模言語モデル）が効率的に読み取れるようにするための標準的なテキスト形式です。人間向けのドキュメントとは異なり、以下の特徴を持ちます。

• 構造化されたプレーンテキスト: Markdown ベースで、LLM が文脈を正確に理解しやすい
• べき等なコマンド群: 繰り返し実行しても安全なコマンドで構成される
• パラメータの明示: 変数やデフォルト値が明確に定義されている
• エラーハンドリングの組み込み: 各ステップに期待される結果と失敗時の対処が記載されている

今回は ScalarDB Cluster のセットアップ手順を llms.txt 形式でまとめた scalardb-cluster-llms.txtを作成しました。

https://github.com/wfukatsu/LLMStxt/blob/main/scalardb-cluster-llms.txt

llms.txt の構成

作成した scalardb-cluster-llms.txt は、以下のセクションで構成されています。

セクション	内容
MODE SELECTION	実行モード（FULL_INSTALL / UNINSTALL / VERIFY 等）の選択
GLOBAL PARAMETERS	環境変数・デフォルト値・必須パラメータの定義
PREREQUISITES	Homebrew, Docker Desktop, minikube 等の事前準備（Step P-1〜P-10）
INSTALL PROCEDURE	PostgreSQL, TLS 証明書, Secret, Helm デプロイ（Step 1〜8）
UNINSTALL PROCEDURE	完全削除の手順（Step U-0〜U-8）
VERIFY PROCEDURE	ヘルスチェック手順
TROUBLESHOOTING	よくある問題と対処法
ARCHITECTURE REFERENCE	システム構成図・コンテナレジストリマッピング

特に重要なのは、各ステップに 期待される結果（Expected）と 失敗時の対処（On failure）を組み込んでいる点です。

### Step P-9: minikube クラスタ起動

# Apple Silicon では docker driver を使用
minikube start \
  --driver=docker \
  --cpus=${MINIKUBE_CPUS} \
  --memory=${MINIKUBE_MEMORY}

- **Expected**: `kubernetes.io/arch=arm64` がノードラベルに含まれること
- **On failure**: "minikube の起動に失敗しました。Docker Desktop が起動していることを確認してください。"

これにより、Claude Code は各ステップの成否を判断し、失敗時には自律的にトラブルシューティングを行えます。

---

実際の構築手順

前提条件

今回のテスト環境は以下の通りです。

項目	値
マシン	macOS Apple Silicon (M シリーズ)
ScalarDB Cluster バージョン	3.17.0
Kubernetes	minikube v1.38.1 (docker driver)
Helm	v4.1.1
Java	OpenJDK 17.0.18 (Temurin, aarch64)

Claude Code への指示

Claude Code で scalardb-cluster-llms.txt を読み込ませ、以下のように指示するだけで構築が始まります。

@scalardb-cluster-llms.txt を読み込んで、FULL_INSTALL モードで実行してください

Claude Code はドキュメントの内容を解析し、以下を自動的に判断・実行します。

1. 必須パラメータの確認: ライセンスキーやバージョンなど、未設定のパラメータをユーザーに問い合わせ
2. Prerequisites のチェック: 各ツールのインストール状況を確認し、不足分をインストール
3. べき等な実行: 既にインストール済みのコンポーネントはスキップ
4. エラー検知と対処: 失敗時にはドキュメント記載のトラブルシューティングを参照して自律的に対応

Step 1: Prerequisites（環境準備）

Claude Code は各ツールの存在チェックから開始します。今回のテスト環境では、Docker Desktop と Java (JDK) 以外のほとんどのツールを brew install で自動インストールしました。

# Claude Code が実行したコマンド例
brew install minikube
brew install helm
brew install cfssl
brew install gradle

Docker Desktop と JDK のインストールには sudo が必要
brew install --cask docker や brew install --cask temurin@17 は sudo を要求するため、Claude Code の非対話ターミナルからは実行できません。この場合、Claude Code はユーザーに別ターミナルからの直接実行を案内します。

Step 2: minikube クラスタの起動

minikube start \
  --driver=docker \
  --cpus=4 \
  --memory=7000 \
  --kubernetes-version=stable

メモリ設定の注意点
llms.txt ではデフォルト 8192MB を指定していますが、Docker Desktop のメモリ上限（今回は 7836MB）を超える場合があります。Claude Code はエラーメッセージから上限値を読み取り、自動的に 7000MB に調整して再試行しました。

Step 3: PostgreSQL デプロイ

Bitnami の Helm Chart を使用して PostgreSQL をデプロイします。

helm repo add bitnami https://charts.bitnami.com/bitnami
helm install postgresql-scalardb-cluster bitnami/postgresql \
  --set auth.postgresPassword=postgres \
  --set primary.persistence.enabled=false \
  -n default

Step 4: TLS 証明書の生成

cfssl を使用して自己署名 CA 証明書と、Envoy / ScalarDB Cluster 用のサーバー証明書を生成します。

# CA 証明書の生成
cfssl gencert -initca ca.json | cfssljson -bare ca

# Envoy 用証明書
cfssl gencert -ca ca.pem -ca-key ca-key.pem \
  -config ca-config.json -profile scalar-test-ca \
  envoy.json | cfssljson -bare envoy

# ScalarDB Cluster 用証明書
cfssl gencert -ca ca.pem -ca-key ca-key.pem \
  -config ca-config.json -profile scalar-test-ca \
  scalardb-cluster.json | cfssljson -bare scalardb-cluster

生成される証明書ファイル:

ファイル	用途
ca.pem / ca-key.pem	CA 証明書・秘密鍵
envoy.pem / envoy-key.pem	Envoy TLS 証明書・秘密鍵
scalardb-cluster.pem / scalardb-cluster-key.pem	ScalarDB Cluster TLS 証明書・秘密鍵

Step 5: Kubernetes Secret の作成

証明書と認証情報を Kubernetes Secret として登録します。

# 認証情報 Secret
kubectl create secret generic scalardb-credentials-secret \
  --from-literal=SCALAR_DB_CLUSTER_POSTGRES_USERNAME=postgres \
  --from-literal=SCALAR_DB_CLUSTER_POSTGRES_PASSWORD=postgres \
  --from-literal=SCALAR_DB_CLUSTER_LICENSE_KEY="<ライセンスキー>" \
  --from-file=SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM=<証明書PEM>

# TLS 関連 Secret（Envoy, ScalarDB Cluster, CA）
kubectl create secret generic envoy-tls-cert --from-file=tls.crt=envoy.pem
kubectl create secret generic envoy-tls-key --from-file=tls.key=envoy-key.pem
kubectl create secret generic scalardb-cluster-tls-ca --from-file=ca.crt=ca.pem
kubectl create secret generic scalardb-cluster-tls-cert --from-file=tls.crt=scalardb-cluster.pem
kubectl create secret generic scalardb-cluster-tls-key --from-file=tls.key=scalardb-cluster-key.pem
kubectl create secret generic client-ca-cert --from-file=ca.crt=ca.pem

Step 6: ScalarDB Cluster のデプロイ

Scalar の Helm Chart リポジトリを追加し、Custom Values ファイルを使ってデプロイします。

scalardb-cluster-custom-values.yaml

envoy:
  enabled: true
  tls:
    downstream:
      enabled: true
      certChainSecret: "envoy-tls-cert"
      privateKeySecret: "envoy-tls-key"
    upstream:
      enabled: true
      overrideAuthority: "cluster.scalardb.example.com"
      caRootCertSecret: "scalardb-cluster-tls-ca"

scalardbCluster:
  image:
    repository: "ghcr.io/scalar-labs/scalardb-cluster-node-byol-premium"
  scalardbClusterNodeProperties: |
    scalar.db.cluster.membership.type=KUBERNETES
    scalar.db.storage=jdbc
    scalar.db.sql.enabled=true
    scalar.db.cluster.auth.enabled=true
    scalar.db.cluster.tls.enabled=true
    # ... (その他のプロパティ)
  tls:
    enabled: true
    caRootCertSecret: "scalardb-cluster-tls-ca"
    certChainSecret: "scalardb-cluster-tls-cert"
    privateKeySecret: "scalardb-cluster-tls-key"
  secretName: "scalardb-credentials-secret"

helm repo add scalar-labs https://scalar-labs.github.io/helm-charts
helm install scalardb-cluster scalar-labs/scalardb-cluster \
  -f scalardb-cluster-custom-values.yaml \
  --version 1.10.0 \
  -n default

Step 7: デプロイ結果の確認

すべての Pod が正常に起動したことを確認します。

NAME                                        READY   STATUS    RESTARTS
scalardb-cluster-envoy-575c75c5d7-djrkj     1/1     Running   0
scalardb-cluster-envoy-575c75c5d7-gl6tb     1/1     Running   0
scalardb-cluster-envoy-575c75c5d7-qttsh     1/1     Running   0
scalardb-cluster-node-7fdbbd5746-25gpt      1/1     Running   0
scalardb-cluster-node-7fdbbd5746-4pkw8      1/1     Running   0
scalardb-cluster-node-7fdbbd5746-8d29m      1/1     Running   0
postgresql-scalardb-cluster-0               1/1     Running   0

ScalarDB Cluster Node × 3、Envoy × 3、PostgreSQL × 1 の計 7 Pod が Running 状態になりました。

Step 8: SQL CLI による接続テスト

Port-Forward を起動し、SQL CLI で接続テストを行います。

# Port-Forward
kubectl port-forward svc/scalardb-cluster-envoy 60053:60053 -n default

# SQL CLI で接続テスト
echo "CREATE NAMESPACE IF NOT EXISTS _test_ns; DROP NAMESPACE _test_ns;" | \
  java -jar scalardb-cluster-sql-cli-3.17.0-all.jar \
  --config sql-cli-database.properties

Refreshed the ring for [localhost]
Refreshing the auth token
No rows affected    # CREATE NAMESPACE 成功
No rows affected    # DROP NAMESPACE 成功

SQL CLI からの接続、認証、SQL 実行がすべて成功しました。

---

詰まったポイント・Tips

Claude Code による自動構築の過程で発生した問題と、その解決方法をまとめます。

1. Homebrew の PATH が未設定

症状: brew コマンドが見つからない

Apple Silicon Mac では Homebrew が /opt/homebrew/bin にインストールされますが、Claude Code のシェル環境ではこの PATH が設定されていない場合があります。

解決策: Claude Code は各コマンドの先頭で eval "$(/opt/homebrew/bin/brew shellenv)" を実行することで対応しました。llms.txt にこのパターンを記載しておくと、よりスムーズに動作します。

2. brew install --cask で sudo が必要

症状: Docker Desktop や JDK のインストールで sudo のパスワード入力を求められ、非対話ターミナルから実行できない

解決策: Claude Code はこの制限を検知すると、ユーザーに「別のターミナルから直接 brew install --cask docker を実行してください」と案内します。これは Claude Code の非対話環境では避けられない制約です。llms.txt の PREREQUISITES セクションに、手動インストールが必要なツールを明記しておくとよいでしょう。

3. minikube のメモリ不足エラー

症状: Exiting due to MK_USAGE: Docker Desktop has only 7836MB memory but you specified 8192MB

Docker Desktop のデフォルトメモリ上限が、llms.txt で指定したデフォルト値（8192MB）を下回っていました。

解決策: Claude Code はエラーメッセージから Docker Desktop のメモリ上限値（7836MB）を読み取り、マージンを持たせた 7000MB に自動調整して再起動しました。llms.txt にメモリのフォールバックロジックを記載しておくと、より確実です。

4. ライセンスキーの署名検証失敗

症状: ScalarDB Cluster Node Pod が CrashLoopBackOff — The given license key has an invalid signature.

初回に提供されたライセンスチェック証明書（license_check_cert_pem）が enterprise.scalar-labs.com 発行の古い証明書で、トライアルライセンスキーの署名と一致しませんでした。

解決策:

1. kubectl logs でエラーを特定
2. 正しい trial.scalar-labs.com 発行の証明書 PEM を取得
3. scalardb-credentials-secret を削除・再作成
4. kubectl rollout restart deployment scalardb-cluster-node で Pod を再起動

Claude Code はログからエラー原因を特定し、ユーザーに正しい証明書の提供を求めた上で、Secret の再作成と Pod の再起動を自動実行しました。

---

構築された環境のアーキテクチャ

最終的に構築された環境の全体構成は以下の通りです。

---

まとめ

llms.txt × Claude Code によるScalarDB Cluster のローカル環境構築を通じて、以下のことが確認できました。

• 成果:

  • Prerequisites の確認からScalarDB Cluster + Envoy + クライアントツールのセットアップまで、約 70 分で完了（手動で行った場合の Docker Desktop / JDK インストール時間を含む）
  • 途中で発生した 4 つの問題に対して、Claude Code がログ解析やエラーメッセージの読み取りによって自律的に対処
  • llms.txt のべき等な構成により、同じ手順を何度でも安全に再実行可能

• llms.txt を書く際のポイント:

  • 各ステップに Expected（期待結果） と On failure（失敗時の対処） を必ず記載する
  • パラメータには デフォルト値 を設定し、必須パラメータは明示する
  • macOS 特有の制約（sudo 必須の cask インストール等）は事前に注記する

• 今後の展望:

  • ScalarDB Analytics の環境構築手順を llms.txt に追加
  • Client SDK のビルド・実行テストの自動化
  • CI/CD パイプラインへの統合（llms.txt ベースの環境構築の再現性を活用）

以前の記事「Scalar DB Server の Kubernetes へのデプロイ方法について」では手動での Kubernetes デプロイ方法を紹介しましたが、llms.txt + AI コーディングアシスタントの組み合わせにより、環境構築の再現性と効率が大きく向上しました。

---

参考

https://scalardb.scalar-labs.com/docs/latest/helm-charts/getting-started-scalardb-cluster-tls/

https://scalardb.scalar-labs.com/docs/latest/helm-charts/how-to-deploy-scalardb-cluster/

---

執筆者紹介

執筆者

深津 航
株式会社Scalar 代表取締役CEO、Co-Founder

最近はAIを使った開発プロセスの改善に取り組んでいます。

会社情報

Scalar, Incは、「データマネジメントの未来を創る」を掲げ、データベースミドルウェアの研究開発・販売を行う日本発のグローバルスタートアップ企業です。複数の異なるデータベース（RDB、NoSQLなど）を仮想的に統合し、トランザクション処理や分析クエリを実現するデータベースミドルウェアであるScalarDB、データの改ざん検知を行うScalarDLを主な製品としています。是非下記の弊社サイトもチェックをお願いします!

https://www.scalar-labs.com/ja/products

https://medium.com/scalar-engineering-ja

https://www.scalar-labs.com/ja