DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

ElasticsearchインデックスをAPIコマンドで管理する究極ガイド

この究極ガイドでElasticsearchのインデックス管理をマスターしましょう。`PUT`を使用したカスタムマッピングと設定によるインデックスの注意深い作成、`GET`による設定と詳細の包括的な確認、`DELETE`による不要なインデックスの安全な削除方法を学びます。実用的な例、ベストプラクティス、重要な注意事項を提供し、最適なパフォーマンスとリソース管理のためにElasticsearch内のデータライフサイクルを効果的に制御できるようにします。

ElasticsearchインデックスをAPIコマンドで管理する究極ガイド

APIを通じてElasticsearchインデックスを管理することは日常的な作業ですが、高額なミスが発生しやすい場面でもあります。不適切なマッピングは再インデックスを強制する可能性があります。ワイルドカード削除は意図以上に多くのものを削除する可能性があります。開発環境で適切だったレプリカ設定は、デプロイ後に本番環境をイエローステータスにする可能性があります。

Elasticsearchインデックスは単なるJSONドキュメントのバケットではありません。マッピング、設定、エイリアス、シャード数、レプリカ数、アナライザー、ライフサイクル動作があります。すべてのAPIを暗記する必要はありませんが、注意深いルーチンが必要です：意図的にインデックスを作成し、Elasticsearchが実際に作成したものを検査し、安全に変更できる設定のみを更新し、ガードレールを設けて削除します。

以下の例ではKibana Dev Toolsスタイルのリクエストを使用しています。curlを好む場合も、同じパスとJSONボディがhttp://host:9200に対して適用されます。

インデックスに含まれるもの

インデックスはドキュメントの論理的な名前空間です。内部的には、プライマリシャードがデータを保持し、レプリカシャードが冗長性と検索容量のためにそのデータをコピーします。デフォルトのシャードとレプリカの動作はElasticsearchのバージョンとデプロイモードによって異なる可能性があるため、記憶に頼らないでください。自分のクラスターの設定を確認してください。

最も頻繁に検査する3つの要素は次のとおりです：

  • settings：number_of_shards、number_of_replicas、refresh_interval、分析設定など。
  • mappings：keyword、text、date、long、double、boolean、ip、ネスト/オブジェクトフィールドなどのフィールドタイプを定義します。
  • aliases：アプリケーションが安定した名前を使用できるようにし、その背後で実際のバッキングインデックスを交換できます。

適切なインデックスAPIワークフローは、最初のドキュメントがインデックスされる前に始まります。動的マッピングは探索には便利ですが、本番インデックスでは重要なフィールドに明示的なマッピングが必要です。user_idが誤ってtextとしてマッピングされると、集計や正確なフィルターが扱いにくくなります。タイムスタンプがtextとしてマッピングされると、時間範囲クエリは日付クエリのように動作しません。これらのミスは修正可能ですが、通常は新しいインデックスを作成して再インデックスする必要があります。

シンプルなインデックスを作成する

最も小さな作成リクエストは次のとおりです：

PUT /my_first_index

Elasticsearchはインデックスが作成された場合に確認応答を返します：

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my_first_index"
}

これはスクラッチインデックスには問題ありません。実際のデータの場合は、最初の数ドキュメントに形状を定義させるのではなく、期待する設定とマッピングでインデックスを作成してください。

マッピングと設定でインデックスを作成する

以下は実用的なproductsインデックスです。名前と説明の全文検索、IDとカテゴリの正確なフィルタリング、日付ソート、数値範囲フィルター、シンプルな在庫確認をサポートします。

PUT /products-v1
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "refresh_interval": "5s"
  },
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "product_id": { "type": "keyword" },
      "sku": { "type": "keyword" },
      "name": {
        "type": "text",
        "fields": {
          "raw": { "type": "keyword", "ignore_above": 256 }
        }
      },
      "description": { "type": "text" },
      "category": { "type": "keyword" },
      "price": { "type": "scaled_float", "scaling_factor": 100 },
      "stock": { "type": "integer" },
      "available": { "type": "boolean" },
      "created_at": { "type": "date" },
      "updated_at": { "type": "date" }
    }
  }
}

ここでのいくつかの選択は意図的です。product_id、sku、categoryはkeywordです。なぜなら、通常は正確な値でフィルタリング、集計、またはアプリケーション動作を結合するからです。nameは検索用のtextで、ソートと完全一致のためのname.rawキーワードサブフィールドがあります。priceはscaled_floatを使用しているため、価格をバイナリ浮動小数点近似ではなく、セント単位のスケーリングされた値として保存できます。dynamic: strictは未知のフィールドを拒否するため、不良なプロデューサーデータが大きな失敗を引き起こすべき場合に便利です。

シャード数を盲目的にコピーしないでください。3つのプライマリシャードは小さいインデックスには多すぎ、大きいインデックスには少なすぎる可能性があります。シャード数は作成後に縮小、分割、または再インデックススタイルの移行なしに変更するのは難しいため、予想されるデータ量、保持期間、ノード数からサイズを決めてください。

作成後にインデックスを検査する

Elasticsearchが受け入れたものを常に確認してください：

GET /products-v1

これにより、設定、マッピング、エイリアスが返されます。焦点を絞ったチェックには、より狭いエンドポイントを使用します：

GET /products-v1/_mapping
GET /products-v1/_settings
GET /products-v1/_alias

多くのインデックスをコンパクトなコマンドラインで表示するには：

GET /_cat/indices/products-*?v

便利な列には、ヘルス、ステータス、プライマリシャード数、レプリカ数、ドキュメント数、削除済みドキュメント数、ストアサイズが含まれます。_cat APIは人間向けです。スクリプトにはJSON APIを使用してください。

フィールドが正しくマッピングされているか確認する場合は、次を使用します：

GET /products-v1/_mapping/field/price
GET /products-v1/_mapping/field/name.raw

これは大きなマッピングをスクロールして読むよりも速く読めます。

インデックス設定を安全に更新する

一部の設定は動的です。レプリカ数は一般的なものです：

PUT /products-v1/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

十分な適切なデータノードがない場合、これによりグリーンクラスターがイエローになる可能性があります。たとえば、1つのプライマリと2つのレプリカには、コピーを配置するための3つの別々の場所が必要です。アロケーションアウェアネスルールにより、要件が厳しくなる可能性があります。

refresh_intervalは、バルクロード中に変更する可能性のある別の設定です：

PUT /products-v1/_settings
{
  "index": {
    "refresh_interval": "30s"
  }
}

より長いリフレッシュ間隔はインデックス作成のオーバーヘッドを減らすことができますが、新しくインデックスされたドキュメントが検索に表示されるまで時間がかかります。バルクバックフィルの場合、チームはリフレッシュを増やしたり一時的に無効にしたり、データをロードし、通常の間隔を復元してから一度リフレッシュすることがよくあります：

POST /products-v1/_refresh

一部の設定は静的です。number_of_shardsは開いている既存のインデックスでは変更できません。プライマリシャード数が間違っていることがわかった場合は、新しいインデックスと移行を計画してください。

自分自身を欺かずにマッピングを変更する

マッピングに新しいフィールドを追加できます：

PUT /products-v1/_mapping
{
  "properties": {
    "brand": { "type": "keyword" }
  }
}

一般的に、既存のフィールドのタイプをその場で変更することはできません。priceがすでにtextの場合、これは古い値を有用な数値フィールドに変換しません。正しいマッピングで新しいインデックスを作成し、再インデックスします：

POST /_reindex
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

本番移行では、アプリケーションが物理インデックスバージョンを認識する必要がないようにエイリアスを使用します。

より安全なアプリケーションアクセスのためにエイリアスを使用する

最初のバージョンにエイリアスをポイントします：

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v1", "alias": "products" } }
  ]
}

アプリケーションはproductsから読み取ります。後で、products-v2を作成し、データを再インデックスし、テストし、アトミックにエイリアスを交換します：

POST /_aliases
{
  "actions": [
    { "remove": { "index": "products-v1", "alias": "products" } },
    { "add": { "index": "products-v2", "alias": "products" } }
  ]
}

書き込み負荷の高いシステムでは、書き込みエイリアスを使用し、is_write_indexを明示的に指定します：

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v2", "alias": "products-write", "is_write_index": true } }
  ]
}

エイリアスは、インデックスバージョンをサービスにハードコーディングするのを避ける最も簡単な方法の1つです。

インデックス名を注意深くリストして検索する

複数のインデックスを検査するには：

GET /products-v1,products-v2/_settings
GET /products-*/_mapping
GET /_cat/indices/products-*?v&s=index

大規模クラスターでは広いワイルドカードに注意してください。GET /*やGET /_allは巨大なレスポンスを生成する可能性があり、バージョン、設定、リクエストオプションによってはシステムインデックスや隠しインデックスを含む場合があります。logs-prod-*やproducts-*のような狭いパターンを優先してください。

スクリプトからインデックスが存在するか確認するには、HEADを使用します：

HEAD /products-v1

200は存在することを意味します。404は存在しないことを意味します。

ガードレール付きでインデックスを削除する

削除はシンプルです：

DELETE /products-v1

運用上のリスクは構文ではありません。リスクは、間違ったインデックスを削除したり、スナップショットが完了する前に削除したりすることです。

削除する前に、パターンが正確に何に一致するかをリストします：

GET /_cat/indices/products-old-*?v&s=index

出力が正しく、データが復元可能または不要になった場合は、同じパターンを削除します：

DELETE /products-old-*

多くのクラスターは、action.destructive_requires_nameで破壊的なワイルドカード操作を制限しています。これは、明示的な名前が必要でない限りDELETE /*のような広範な削除をブロックするため、優れた安全設定です。その保護があっても、削除操作を本番変更として扱ってください：インデックスパターンを確認し、スナップショットを確認し、呼び出し元が適切な権限を持っていることを確認してください。

時系列データにはライフサイクルポリシーを優先する

手動削除は1回限りのクリーンアップには許容されます。ログ、メトリクス、トレース、その他の時系列データには、適切な場合はIndex Lifecycle Managementまたはデータストリームを使用してください。ライフサイクルポリシーは、インデックスが経過時間またはサイズ目標に達したときにロールオーバーし、古いデータを別のティアに移動し、保持期間が切れた後に削除できます。

これは重要です。なぜなら、手動クリーンアップは最悪のタイミングで失敗する傾向があるからです。誰かが忘れ、ディスクがいっぱいになり、洪水段階のウォーターマークがインデックスを読み取り専用にし、チームがプレッシャーの下でクリーンアップすることになります。ライフサイクルポリシーは、保持をカレンダーリマインダーではなく設定に変えます。

シンプルな日常ルーチン

本番クラスターの場合、実用的なインデックス管理ルーチンは次のようになります：

ヘルスを確認：

GET /_cluster/health

パターンでインデックスをリスト：

GET /_cat/indices/logs-*?v&s=store.size:desc

疑わしい設定を検査：

GET /logs-prod-2026.05.24/_settings

アプリケーションリリースから新しいフィールドを追加する前にマッピングを確認：

GET /logs-prod-2026.05.24/_mapping

移行の前後にエイリアスを確認：

GET /_cat/aliases/products*?v

これは華やかな作業ではありませんが、多くの問題を早期に発見します：間違ったレプリカ数、偶発的な動的フィールド、古いエイリアス、期限切れになるべき古いインデックス。

避けるべき一般的な間違い

開発環境のデフォルトを本番アーキテクチャにしないでください。シングルノードクラスター、レプリカゼロ、動的マッピングはデモには問題ないかもしれませんが、リカバリ計画にはなりません。

頭の中でマッピングを変更し、Elasticsearchが同意していると仮定しないでください。実際のマッピングを検査してください。

最初に一致するインデックスをリストせずにワイルドカード削除を使用しないでください。

それらを配置するのに十分なデータノードとゾーンなしに高いレプリカ数を設定しないでください。

アプリケーションが依存するインデックスにエイリアスをスキップしないでください。アプリケーションがすでにエイリアスと通信している場合、最初の移行ははるかに簡単になります。

優れたインデックス管理は、主に規律ある繰り返しです。意図を持って作成し、存在するものを検査し、エイリアスで移行し、保持を自動化し、破壊的なアクションを退屈なほど明示的にします。

テンプレートは1回限りの作成よりも重要

同じ種類のインデックスを繰り返し作成する場合は、手動のPUT /index-name呼び出しに依存しないでください。インデックステンプレートまたはコンポーザブルテンプレートを使用して、新しいインデックスが自動的に正しいマッピング、設定、エイリアス、ライフサイクルポリシーを受け取るようにします。

ログプラットフォームは古典的な例です。logs-web-2026.05.24に正しい@timestampマッピングがあるが、明日のインデックスが最初のドキュメントによって動的に作成される場合、1つの不正なイベントがフィールドを誤ってマッピングする可能性があります。そのミスは、ダッシュボードが失敗するか集計が消えるまで現れないかもしれません。テンプレートはそのドリフトを防ぎます。

シンプルなテンプレートは、将来のインデックスに対してパターン、設定、マッピングを定義するかもしれません：

PUT /_index_template/logs_web_template
{
  "index_patterns": ["logs-web-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" },
        "service": { "type": "keyword" },
        "level": { "type": "keyword" },
        "message": { "type": "text" },
        "trace_id": { "type": "keyword" }
      }
    }
  }
}

テンプレートはコードでレビューするのも簡単です。バージョン管理に入れ、アプリケーション変更と同じパスでデプロイし、ロールオーバーが次のバッキングインデックスを作成する前にテストしてください。

アプリケーションを驚かせずに再インデックスする

最もクリーンなインデックス移行は通常次のとおりです：新しいバージョン付きインデックスを作成し、データを再インデックスし、カウントとサンプルクエリを比較し、エイリアスを交換します。緊急の設定変更を楽しむのでなければ、アプリケーションを直接products-v1に向けないでください。

注意深い移行は次のようになります：

PUT /products-v2
{
  "mappings": {
    "properties": {
      "product_id": { "type": "keyword" },
      "name": { "type": "text" },
      "price": { "type": "scaled_float", "scaling_factor": 100 }
    }
  }
}

次に再インデックス：

POST /_reindex?wait_for_completion=false
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

wait_for_completion=falseを使用するとタスクIDが返されるため、長い再インデックスを監視できます。完了後、ドキュメント数を比較し、代表的な検索を実行します。その後にのみエイリアスを交換します。

書き込み負荷の高いインデックスの場合は、デュアルライト、一時停止ウィンドウ、または信頼できるソースからのリプレイを検討してください。APIコマンドは簡単ですが、一貫性計画が実際の作業です。

セキュリティと権限

インデックスAPIはすべてのアプリケーションユーザーが利用できるべきではありません。検索サービスはエイリアスに対する読み取り権限が必要な場合があります。データインジェスターは書き込みエイリアスに対する作成、インデックス、書き込み権限が必要な場合があります。広範な削除や管理権限を持つべきIDはほとんどありません。

これは重要です。なぜなら、インデックスAPIは強力だからです。manage権限を持つ侵害されたアプリケーション資格情報は、レプリカ設定を変更したり、インデックスを閉じたり、データを削除したりできます。破壊的な権限は分離し、本番削除にはアプリケーションパスではなくオペレーターワークフローを必要とします。

命名規則でミスを減らす

目的とライフサイクルをエンコードする名前を使用します：products-v3、logs-web-2026.05.24、metrics-api-000123、またはデータソースに一致するデータストリーム名。newindex、test2、prod-finalのような曖昧な名前は避けてください。クリーンアップ中、曖昧な名前は何を削除しても安全かを判断するのを難しくします。

時系列インデックスの場合は、一貫した日付形式を使用し、ローカル時間とUTCの仮定を混在させないでください。バージョン管理されたビジネスインデックスの場合は、エイリアスを安定させ、物理インデックスバージョンをその背後で変更できるようにします。退屈な命名規則は運用上の安全機能です。