> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# ログの保存と検索 - OpenSearch
OpenSearch は、SambaStack のモニタリングリファレンスアーキテクチャで使用される、デフォルトのログ保存・検索エンジンです。Fluent Bit から転送されたログと監査情報を保存し、Grafana または直接の API アクセスによる可視化とクエリを可能にします。
**リファレンスアーキテクチャに関する注意:** このセットアップではサードパーティ製コンポーネントを使用しています。バージョン、デフォルト値、コマンド構文は変更される可能性があります。SambaStack に固有でない問題については、該当コンポーネントを所有するベンダーまたはプロジェクトにお問い合わせください。
## 前提条件
作業を始める前に、以下の環境を準備してください。
* **kubectl** – 対象の Kubernetes クラスターへのアクセスが設定済みであること
* **Helm**（最新バージョン） – OpenSearch チャートのデプロイに使用
* **jq** – 動作確認時の JSON 出力の解析に使用
* **ストレージクラス** – 永続ボリュームのプロビジョニングに使用できる有効なストレージクラスが Kubernetes 環境に存在すること
**デプロイ順序:** Grafana でログを可視化する場合は、[Fluent Bit](/docs/ja/v2.2.3/sambastack/reference-architecture/observability/log-forwarder) および [Prometheus/Grafana](/docs/ja/v2.2.3/sambastack/reference-architecture/observability/monitoring-prom) よりも先に OpenSearch をデプロイしてください。
## リソース要件
以下は、OpenSearch の最小リソース推奨値です。
| デプロイタイプ | CPU | メモリ | ストレージ |
| - | - | - | - |
| シングルノード（開発/テスト） | 2 コア | 4 GB | 50 GB |
| マルチノード（本番） | ノードあたり 4 コア | ノードあたり 8 GB | ノードあたり 100 GB |
OpenSearch はメモリを大量に消費します。本番ワークロードでは、利用可能なメモリの 50% 以上（最大 32 GB）を JVM ヒープに割り当ててください。これらの値は、`opensearch-values.yaml` ファイルの `esJavaOpts` パラメータで設定します（例: `esJavaOpts: "-Xmx16g -Xms16g"`）。
## アーキテクチャ概要
SambaStack のモニタリングスタックにおいて、OpenSearch は中央のログリポジトリとして機能します。
* Fluent Bit から HTTPS（ポート 9200）でログを受信します
* 時間ベースのインデックス（デフォルト: `logs-7d`）にログを保存します
* Grafana ダッシュボードや直接クエリ向けの検索 API を提供します
* 永続ストレージを持つ StatefulSet として動作します
## デプロイ手順
### ステップ 1: monitoring 名前空間の作成
まず、すべての監視コンポーネント用の専用名前空間を作成します。この名前空間は、OpenSearch、Fluent Bit、Prometheus、Grafana で共有されます。
`monitoring-namespace.yaml` という名前のファイルを作成します。
```yaml theme={}
apiVersion: v1
kind: Namespace
metadata:
name: monitoring
```
名前空間を適用します。
```bash theme={}
kubectl apply -f monitoring-namespace.yaml
```
### ステップ 2: 管理者パスワード用 Secret の作成
OpenSearch は、インストール時に初期管理者パスワードを必要とします。パスワードは Kubernetes の Secret 経由で注入されます。
まず、base64 エンコードしたパスワードを生成します。
```bash theme={}
echo -n 'your-secure-password-here' | base64
```
**パスワード要件:**
* 8 文字以上
* 大文字、小文字、数字、特殊文字を組み合わせること
* 使用可能な特殊文字: `# @ % _ - + = .`
* `!` と `$` は問題を引き起こす可能性があるため、使用しないでください
平文のパスワードは安全に保管してください。後続のステップで Fluent Bit と Grafana を設定する際に必要になります。
`opensearch-initial-admin-password-secret.yaml` という名前のファイルを作成し、プレースホルダをエンコード済みのパスワードに置き換えます。
```yaml theme={}
apiVersion: v1
data:
OPENSEARCH_INITIAL_ADMIN_PASSWORD:
kind: Secret
metadata:
name: opensearch-initial-admin-password
namespace: monitoring
type: Opaque
```
Secret を適用します。
```bash theme={}
kubectl apply -f opensearch-initial-admin-password-secret.yaml
```
### ステップ 3: Helm values の設定
デプロイをカスタマイズするために、`opensearch-values.yaml` という名前のファイルを作成します。`` は、クラスターのストレージクラス名に置き換えてください。
```yaml theme={}
replicas: 1
singleNode: true
opensearchJavaOpts: "-Xms2g -Xmx2g"
resources:
requests:
cpu: "1000m"
memory: "4Gi"
limits:
cpu: "2000m"
memory: "4Gi" # ~2x heap leaves room for Lucene mmap, direct buffers, etc.
extraEnvs:
- name: OPENSEARCH_INITIAL_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: opensearch-initial-admin-password
key: OPENSEARCH_INITIAL_ADMIN_PASSWORD
persistence:
enabled: true
storageClass:
```
クラスターで利用可能なストレージクラスを確認するには、`kubectl get storageclass` を実行します。
#### 設定リファレンス
* `replicas` - この値を `1` に設定するのは、開発およびテスト用途に適しています。本番の高可用性デプロイでは、レプリカ数を 3 以上に増やし、ストレージクラスがマルチ AZ プロビジョニングに対応していることを確認してください。
* `singleNode` - この値を `true` に設定するのは、`replicas` が `1` の場合（同じく開発・テスト用途）に限定してください。`replicas` が `1` より大きい本番の高可用性デプロイでは、`false` に設定するか、この行自体を削除してください。
* **注**: 既存のデプロイでこの値を変更すると、イミュータブルなフィールドが変更されるため、StatefulSet の再作成が必要になります。
* `opensearchJavaOpts` - OpenSearch JVM の最小・最大 Java ヒープサイズを制御します。`"-Xms2g -Xmx2g"` に設定すると、ヒープはちょうど 2 GiB に固定されます。目安として、ヒープはコンテナのメモリ上限の約 *50%* とし、約 31 GiB を超えないようにしてください。チャートのデフォルト値である 512 MiB は、OpenSearch にバンドルされたプラグイン（Security、Security Analytics、ML Commons、Query Insights）が読み込まれると小さすぎるため、通常の使用でも OOM エラーが発生します。
* `resources` - Pod の CPU およびメモリのリクエスト（保証される割り当て）とリミット（上限）を制御します。
* `limits.memory` は、Lucene やダイレクトバッファが使用するオフヒープメモリの余地を残すため、`opensearchJavaOpts` のヒープサイズの約 2 倍に設定してください。
* `requests.memory` は、`limits.memory` と同じ値に設定してください。これにより Pod が `Guaranteed` QoS クラスに配置され、ノードのメモリ逼迫時の退避 (eviction) を防げます。
* `requests.cpu` は、インデックス操作時のベースライン性能を確保するために 1 コア以上に設定し、`limits.cpu` は、マージストーム、インデックス処理のスパイク、検索負荷の際にバーストできるよう、より高い値（例: 2 コア）に設定してください。
### ステップ 4: OpenSearch のインストール
OpenSearch 公式の Helm リポジトリを追加し、チャートをインストールします。
```bash theme={}
helm repo add opensearch https://opensearch-project.github.io/helm-charts/
helm repo update
```
```bash theme={}
helm upgrade --install opensearch opensearch/opensearch \
-n monitoring \
-f opensearch-values.yaml
```
## 動作確認
インストールが完了したら、OpenSearch が正常に動作していることを確認します。
### Pod ステータスの確認
```bash theme={}
kubectl -n monitoring get pod opensearch-cluster-master-0
```
期待される出力:
```text theme={}
NAME READY STATUS RESTARTS AGE
opensearch-cluster-master-0 1/1 Running 0 2m
```
### API 接続のテスト
OpenSearch API にローカルからアクセスするために、ポートフォワードを設定します。
```bash theme={}
kubectl -n monitoring port-forward svc/opensearch-cluster-master 9200:9200 &
```
管理者パスワードを取得します。
```bash theme={}
kubectl -n monitoring get secret opensearch-initial-admin-password -o json \
| jq -r '.data | to_entries[] | "\(.key): \(.value | @base64d)"'
```
API エンドポイントをテストします。
```bash theme={}
curl -u admin: -k https://localhost:9200
```
成功した場合のレスポンスは、次のようになります。
```json theme={}
{
"name": "opensearch-cluster-master-0",
"cluster_name": "opensearch-cluster",
"cluster_uuid": "eJI1tDhhQbO3fQb4LeZcyw",
"version": {
"distribution": "opensearch",
"number": "3.3.2",
"build_type": "tar",
"build_hash": "6564992150e26aaa62d4522a220dfff5188aeb88",
"build_date": "2025-10-29T22:24:07.450919802Z",
"build_snapshot": false,
"lucene_version": "10.3.1",
"minimum_wire_compatibility_version": "2.19.0",
"minimum_index_compatibility_version": "2.0.0"
},
"tagline": "The OpenSearch Project: OpenSearch"
}
```
作業が終わったら、ポートフォワードのプロセスを停止します。
```bash theme={}
pkill -f "port-forward.*opensearch"
```
## 成功基準
以下の条件を満たしていれば、OpenSearch のインストールは完了です。
* `opensearch-cluster-master-0` Pod が `Running` 状態で、READY が `1/1` と表示される
* OpenSearch API が curl に対して有効なクラスター情報を返す
* `monitoring` 名前空間に `opensearch-initial-admin-password` Secret が存在する
## 設定リファレンス
| パラメータ | デフォルト値 | 説明 |
| - | - | - |
| `replicas` | 1 | OpenSearch ノード数。本番の高可用性構成では 3 以上を使用 |
| `persistence.enabled` | true | インデックス用の永続ストレージを有効化 |
| `persistence.storageClass` | – | PVC 用の Kubernetes ストレージクラス |
| インデックス名 | `logs-7d` | Fluent Bit が作成するデフォルトインデックス（OpenSearch ではなく Fluent Bit 側で設定） |
## トラブルシューティング
### Pod が Pending 状態のまま進まない
**症状:** `opensearch-cluster-master-0` が `Pending` 状態のまま進まない。
**原因:** 通常、PersistentVolumeClaim (PVC) を満たせないことを示します。
**対処方法:**
```bash theme={}
# Check PVC status
kubectl -n monitoring get pvc
# Check events for details
kubectl -n monitoring describe pvc opensearch-cluster-master-opensearch-cluster-master-0
```
ストレージクラスが存在し、利用可能な容量があることを確認してください。
### Pod が CrashLoopBackOff になる
**症状:** Pod がクラッシュと再起動を繰り返す。
**原因:** メモリ不足またはパスワード Secret の欠落が原因であることが多いです。
**対処方法:**
```bash theme={}
# Check pod logs
kubectl -n monitoring logs opensearch-cluster-master-0
# Verify secret exists
kubectl -n monitoring get secret opensearch-initial-admin-password
```
### ポート 9200 で接続が拒否される
**症状:** ポートフォワードが有効な状態でも、`curl` が「Connection refused」を返す。
**対処方法:**
```bash theme={}
# Verify port-forward is running
ps aux | grep port-forward
# Check service endpoints
kubectl -n monitoring get endpoints opensearch-cluster-master
```
## 次のステップ
OpenSearch が稼働したら、次に進みます。
1. **Fluent Bit のデプロイ** – ログ転送をセットアップし、クラスターのログを OpenSearch に取り込みます。詳細は [Fluent Bit によるログ転送](/docs/ja/v2.2.3/sambastack/reference-architecture/observability/log-forwarder) をご参照ください。
2. **Prometheus と Grafana のデプロイ** – メトリクスの収集と可視化を追加します。Grafana のデプロイには、ログ探索用の OpenSearch データソースが含まれます。詳細は [Prometheus と Grafana による監視](/docs/ja/v2.2.3/sambastack/reference-architecture/observability/monitoring-prom) をご参照ください。
## クリーンアップ
クラスターから OpenSearch と関連リソースをすべて削除するには、以下のコマンドを実行します。
Helm リリースをアンインストールします。
```bash theme={}
helm uninstall opensearch -n monitoring
```
管理者パスワードの Secret を削除します。
```bash theme={}
kubectl delete secret opensearch-initial-admin-password -n monitoring
```
ストレージを解放するために、PersistentVolumeClaim を削除します。
```bash theme={}
kubectl -n monitoring delete pvc opensearch-cluster-master-opensearch-cluster-master-0
```
PVC を削除すると、保存されているログデータがすべて完全に削除されます。事前に、重要なログをバックアップ済みであることを確認してください。
モニタリングスタック全体を削除する場合で、他のコンポーネントが残っていないときは、名前空間を削除します。
```bash theme={}
kubectl delete namespace monitoring
```
名前空間を削除すると、その中のすべてのリソース（デプロイ済みであれば Fluent Bit、Prometheus、Grafana を含む）が削除されます。モニタリングスタック全体を削除する場合にのみ実行してください。