🚀 Elasticsearch 8.0 への移行時に注意すべき破壊的変更まとめ（AI版）

# はじめに
本記事では、Elasticsearch 8.0 にアップグレードする際に注意すべき変更点を、日本語形式でまとめます。(AI版)

参考資料：
- [Elastic breaking-changes-8.0 document](https://www.elastic.co/guide/en/elasticsearch/reference/current/migrating-8.0.html#breaking-changes-8.0)
- [Elastic github migration](https://github.com/elastic/elasticsearch/tree/8.17/docs/reference/migration/migrate_8_0)


## 🚨 破壊的変更（Breaking Changes）
Elasticsearch 8.0における以下の変更は、お客様のアプリケーションに影響を与え、正常な動作を妨げる可能性があります。8.0にアップグレードする前に、これらの変更点を確認し、影響を軽減するために説明されている手順を実行してください。

影響度判断基準：
| 影響度 | 判断基準 | 例 |
|:-:|:-:|:-:|
| 🔴 高  | 機能そのものの削除、移行せずに使用すると即エラー／起動不可|  REST エンドポイント削除、設定削除 |
| 🟠 中  | 挙動の変化・型変更・互換モードで動作可能な場合 | レスポンス形式変更、新しいフォーマットへの統一 |
| 🟡 低  | デフォルト値の変更・将来非推奨レベル・警告発生程度  | ログ形式の統一、オプション初期値の微修正 |

		
		

### 🔧 1.クラスタおよびノード設定の変更一覧

| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|----------------|-------|--------|
| 1 | `action.destructive_requires_name` のデフォルトが `true` に変更 | ワイルドカードによる破壊的操作が不可になり、明示的なインデックス名が必須 | 低 🟡 |
| 2 | `xpack.searchable.snapshot.shared_cache.size` は frozen ノード専用に | `data_frozen` でないノードで使うと起動エラーになる | 高 🔴 |
| 3 | `indices.query.bool.max_clause_count` が削除 | クエリの句数上限が自動算出に変更 | 中 🟠 |
| 4 | `indices.lifecycle.poll_interval` の最小値が `1s` に | `1s` 未満にすると起動や API エラーが発生 | 高 🔴 |
| 5 | `file` と `native` 認証がデフォルトで有効 | 無効にしない限り自動有効 | 低 🟡 |
| 6 | Realm 設定に `order` の明示が必須 | 未指定・重複すると起動失敗 | 高 🔴 |
| 7 | `cluster.routing.allocation.disk.include_relocations` 削除 | シャード移動容量は常に考慮される | 中 🟠 |
| 8 | `cluster.join.timeout` 削除 | 設定しても無効、削除推奨 | 低 🟡 |
| 9 | `discovery.zen.*` 設定すべて削除 | 例：`minimum_master_nodes` 残存で起動失敗 | 高 🔴 |
| 10 | `http.content_type.required` 削除 | 設定があると起動エラー | 低 🟡 |
| 11 | `http.tcp_no_delay` が削除 | 新しい形式 `http.tcp.no_delay` に置き換える必要あり | 低 🟡 |
| 12 | `node.local_storage` が削除 | すべてのノードはローカルストレージ必須になった | 高 🔴 |
| 13 | `cluster.remote.connect` が削除 | `node.remote_cluster_client` を使用する必要がある | 高 🔴 |
| 14 | `node.data` の自動検出が削除 | デフォルトで有効になるが、指定しないと警告される可能性あり | 中 🟠 |
| 15 | `xpack.monitoring.exporters.*.auth.password` が削除 | `auth.secure_password` を使用する必要がある | 高 🔴 |
| 16 | `xpack.ml.enabled` の削除 | Machine Learning 機能は常に有効になった | 低 🟡 |
| 17 | `xpack.ilm.enabled` の削除 | Index Lifecycle Management は常に有効 | 低 🟡 |
| 18 | `xpack.rollup.enabled` の削除 | Rollup 機能は常に有効 | 低 🟡 |
| 19 | `xpack.sql.enabled` の削除 | SQL サポートは無効化できなくなった | 低 🟡 |
| 20 | `gateway.expected_nodes` 等の削除 | クラスタリカバリ設定が削除された | 中 🟠 |
| 21 | `xpack.watcher.enabled` の削除 | Watcher 機能は常に有効になった | 低 🟡 |
| 22 | `xpack.vectors.enabled` の削除 | ベクトル機能は常に有効になった | 低 🟡 |
| 23 | `xpack.enrich.enabled` の削除 | Enrich 機能は常に有効 | 低 🟡 |
| 24 | `xpack.flattened.enabled` の削除 | Flattened 機能は常に有効 | 低 🟡 |
| 25 | `xpack.transform.enabled` の削除 | Transform 機能は常に有効 | 低 🟡 |
| 26 | `xpack.slm.enabled` の削除 | スナップショットライフサイクル管理は常に有効 | 低 🟡 |
| 27 | `xpack.monitoring.enabled` の削除 | モニタリング機能は常に有効 | 低 🟡 |
| 28 | `xpack.security.authz.store.roles.index.reload.interval` が削除 | インデックスベースのロールリロード間隔設定は無効化 | 中 🟠 |
| 29 | `script.max_compilations_rate` が削除 | script.cache の設定を使うことが推奨される | 中 🟠 |
| 30 | `transport.profiles.default.receive_buffer_size` が削除 | `transport.receive_buffer_size` を使用 | 低 🟡 |
| 31 | `transport.profiles.default.send_buffer_size` が削除 | `transport.send_buffer_size` を使用 | 低 🟡 |
| 32 | `transport.profiles.default.tcp_keep_alive` が削除 | `transport.tcp.keep_alive` を使用 | 低 🟡 |
| 33 | `transport.profiles.default.tcp_no_delay` が削除 | `transport.tcp.no_delay` を使用 | 低 🟡 |
| 34 | `transport.profiles.default.tcp_reuse_address` が削除 | `transport.tcp.reuse_address` を使用 | 低 🟡 |
| 35 | `transport.tcp.connect_timeout` が削除 | 削除されたため、関連処理は自動化された | 低 🟡 |
| 36 | `transport.tcp.keep_count` が削除 | TCP 設定の細かな調整不可に | 低 🟡 |
| 37 | `transport.tcp.keep_interval` が削除 | 同上 | 低 🟡 |
| 38 | `transport.tcp.keep_idle` が削除 | 同上 | 低 🟡 |
| 39 | `transport.tcp.no_delay` の設定名が変更 | `transport.tcp.no_delay` を使用する必要あり | 低 🟡 |
| 40 | `transport.tcp.reuse_address` の設定名が変更 | `transport.tcp.reuse_address` を使用する必要あり | 低 🟡 |
| 41 | `transport.tcp.send_buffer_size` が削除 | 削除により、システムが自動設定 | 低 🟡 |
| 42 | `transport.type` の `security4` サポート終了 | 古いセキュリティタイプは無効 | 高 🔴 |
| 43 | `xpack.graph.enabled` が削除 | Graph 機能は常に有効になった | 低 🟡 |
| 44 | `xpack.ml.max_open_jobs` の動作変更 | Machine Learning の動作に影響（パフォーマンス設定） | 中 🟠 |
| 45 | `reindex.remote.whitelist` が削除 | `reindex.remote.allowlist` を使用 | 中 🟠 |
| 46 | `node.attr.rack_id` などの node.attr.* に変更あり | 構成変更に伴う影響あり | 中 🟠 |

### 2.コマンドラインツールの変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|-------------------------|--------|--------|
| 1 | `elasticsearch-migrate` ツールが削除された | `elasticsearch-migrate` は file realm のユーザーとロールを native realm に変換するためのツールで、7.2.0 から非推奨となっていた。8.0 で完全に削除され、使用するとエラーになる。今後は全て native realm にて直接作成する必要あり。 | 高 🔴 |

### 3.インデックス設定の変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|-------------------------|--------|--------|
| 1 | システムインデックスへの直接アクセスが非推奨に | システムインデックスに直接アクセスするには、専用のセキュリティロールと `allow_restricted_indices: true` が必要。今後はアクセスがブロックされる可能性あり。 | 中 🟠 |
| 2 | `index.merge.policy.max_merge_at_once_explicit` が非推奨 | 設定しても効果なし。強制マージ中の同時マージ数は無制限に。今後のためにテンプレートやインデックスから削除を推奨。 | 中 🟠 |
| 3 | `index.max_adjacency_matrix_filters` が削除 | この設定は削除され、代わりに `indices.query.bool.max_clause_count` が適用される。設定を含むリクエストはエラーに。 | 高 🔴 |
| 4 | `index.force_memory_term_dictionary` が削除 | 7.0 で一時的に導入されたが、最適化が強制となったため設定が削除された。 | 高 🔴 |
| 5 | `index.soft_deletes.enabled` が削除 | ソフトデリートを無効化することは非対応になった。`false` に設定するとエラーになる。 | 高 🔴 |
| 6 | `index.translog.retention.age` と `index.translog.retention.size` が削除 | トランスログの保持設定は削除され、設定しているとエラーになる。 | 高 🔴 |

### 4.Java API の変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|-----------------------------|--------|--------|
| 1 | `indexlifecycle` パッケージが `ilm` にリネームされた | High Level REST Client で `indexlifecycle` が `ilm` に変更された。コードと整合性を取るための変更。 | 中 🟠 |
| 2 | `Fuzziness` クラスの使用方法が変更 | `build` メソッドは廃止。`fromString` や `fromEdits` を使用し、数値からの自動変換の寛容性が削除された。 | 高 🔴 |
| 3 | `Repository` の依存関係が変更 | `IndexShard` への依存が除かれ、`Store` と `MappingService` のみを使用。テスト性向上のため。 | 低 🟡 |

### 5.JVM オプションの変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|-------------------------------|--------|--------|
| 1 | `es.disk.auto_release_flood_stage_block` が削除 | ディスク使用量が回復した際の自動ブロック解除の制御は削除された。設定を保持していると起動時エラーになる。 | 高 🔴 |
| 2 | `es.rest.url_plus_as_space` が削除 | URL 中の `+` をスペースと扱う非推奨設定が削除された。今後は `%2B` として扱われる。 | 中 🟠 |
| 3 | `es.unsafely_permit_handshake_from_incompatible_builds` が削除 | 異なるビルド間でのハンドシェイクを許可する非安全なオプションが削除。設定を保持すると起動失敗。 | 高 🔴 |

### 6.ロギングの変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|----------------------------|--------|--------|
| 1 | JSON ログが ECS に準拠 | JSON 形式のログが Elastic Common Schema (ECS) に準拠した構造に変更された。ログを解析するアプリは更新が必要。 | 中 🟠 |
| 2 | 非推奨・スローログのプレーンテキスト出力が廃止 | Deprecation ログ、インデックススローログ、検索スローログのプレーンテキスト出力がなくなり、JSON のみとなった。 | 中 🟠 |
| 3 | 監査ログがサイズでローテーションおよび gzip 圧縮されるように | 監査ログはこれまでの日次ローテーションに加えて、サイズでもローテーションされ、かつ gzip 形式で保存される。処理スクリプト等は変更が必要。 | 中 🟠 |

### 7.マッピングの変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|----------------------------|--------|--------|
| 1 | 6.x 以前のインデックスは非対応に | Elasticsearch 8.0 は 7.0 以降に作成されたインデックスのみ対応。6.x 以前のものは 7.x で reindex が必要。 | 高 🔴 |
| 2 | 閉じたインデックスもバージョンチェック対象に | クローズドでも 6.x 以前のインデックスが存在すると起動できない。再 index が必要。 | 高 🔴 |
| 3 | completion フィールドの context 上限が 10 に | 1つの completion フィールドに最大10個の context のみ許容。超えるとエラー。 | 中 🟠 |
| 4 | 多段階の multi-fields は非対応に | multi-fields 内の multi-fields 定義は廃止。階層をフラットにするか `copy_to` を使うこと。 | 高 🔴 |
| 5 | `_field_names.enabled` 設定が削除 | テンプレートやマッピングからこの設定を削除する必要がある。 | 中 🟠 |
| 6 | `boost` パラメータがマッピングから削除 | インデックス時ブーストは完全削除。クエリ側でブースト指定を行うべき。 | 中 🟠 |
| 7 | joda-time 日付形式が非対応に | 旧形式を使用しているインデックスは java-time 形式で再作成が必要。 | 高 🔴 |
| 8 | `geo_shape` の旧パラメータが削除 | `tree`, `tree_levels`, `strategy`, `distance_error_pct` が廃止。7.x の既存インデックスは動作可。 | 中 🟠 |

### 8.パッケージ構成の変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|----------------------------|--------|--------|
| 1 | データディレクトリ構造が変更 | データは `${path.data}/nodes/0` ではなく、`path.data` 直下に保存されるようになった。複数ノードが同一パスを共有していると起動できないため、個別に分離する必要がある。 | 高 🔴 |
| 2 | 旧 Maxmind geoip データベースの削除 | Elasticsearch に同梱されていた古い geoip DB は削除された。ダウンローダー無効化 + DB 未提供の場合、geoip processor は機能せず。 | 中 🟠 |

### 9.Painless スクリプトの変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|------------------------------|--------|--------|
| 1 | `JodaCompatibleZonedDateTime` クラスの削除 | Joda → Java 時刻移行のための中間クラスが削除された。旧クラスに依存した script はコンパイルエラーになる。アップグレード前に `ZonedDateTime` ベースに置換が必要。 | 高 🔴 |


### 10.プラグインの変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|------------------------------|--------|--------|
| 1 | `repository-s3/gcs/azure` プラグインが本体に統合 | これらのプラグインはデフォルトで含まれるようになった。インストール・削除を試みても警告のみで動作は継続される。 | 中 🟠 |
| 2 | `getRestHandlerWrapper` 拡張ポイントの削除 | サードパーティ製プラグインで REST リクエストをフックする機構が廃止。旧セキュリティプラグイン等が非互換になる可能性あり。 | 高 🔴 |


### 11.REST API の変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|----------------|-------|--------|
| 1 | `_xpack` を含む REST API エンドポイントが削除 | `_xpack` を含むすべての REST API は削除されました。各機能には今後、標準の API パスでアクセスしてください。 | 🔴 高 |
| 2 | マッピングタイプを含む REST API エンドポイントが削除 | 型付きマッピングのサポートが終了し、関連する REST エンドポイントも削除されました。 | 🔴 高 |
| 3 | CCS の互換性が縮小 | クロスクラスター検索は直前のマイナーバージョンとしか互換性がなくなりました。 | 🟠 中 |
| 4 | `terms` 集約で `_term` キーが非対応に | ソートキー `_term` は無効化されました。 | 🟠 中 |
| 5 | `date_histogram` 集約で `_time` キーが非対応に | ソートキー `_time` は使えなくなりました。 | 🟠 中 |
| 6 | `moving_avg` 集約の削除 | 平滑化処理 `moving_avg` が完全に削除されました。 | 🔴 高 |
| 7 | `percentiles` 集約で重複 `percents` 禁止 | 同じパーセンタイル値を複数指定できません。 | 🟠 中 |
| 8 | `interval` パラメータが削除 | `date_histogram` における `interval` は使えなくなり、他の形式に移行が必要です。 | 🔴 高 |
| 9 | `nGram` トークンフィルターが削除 | `nGram`, `edgeNGram` のトークンフィルター名が削除されました。 | 🔴 高 |
| 10 | `nGram` トークナイザーが削除 | 同じく、トークナイザーとしての利用も不可能に。 | 🔴 高 |
| 11 | `in_flight_requests` → `inflight_requests` に変更 | ログや診断APIの項目名が変更。 | 🟡 低 |
| 12 | voting exclusion API のエンドポイントが変更 | クラスタ voting 設定の除外APIパスが変更されました。 | 🟠 中 |
| 13 | リモートインデックスの自動フォロー制限 | auto-follow パターンに一致しても自動追従されなくなります。 | 🟠 中 |
| 14 | `wildcard` 関数が削除 | EQL の `wildcard` 関数は削除されました。 | 🔴 高 |
| 15 | `freeze` アクションが no-op に | ILM の `freeze` は何も行わない動作に。 | 🟠 中 |
| 16 | ILM ポリシーのバリデーション強化 | より厳密な設定チェックが追加されました。 | 🟠 中 |
| 17 | `_upgrade` API が削除 | 古いアップグレードAPIが完全削除されました。 | 🔴 高 |
| 18 | freeze index API が削除 | 非推奨だった freeze index API が削除。 | 🔴 高 |
| 19 | force merge のパラメータ制限 | `max_num_segments` と `only_expunge_deletes` の併用が不可。 | 🟠 中 |
| 20 | index template API の `template` 削除 | テンプレート関連のパラメータが整理。 | 🔴 高 |
| 21 | synced flush の削除 | パフォーマンス用操作が削除。 | 🔴 高 |
| 22 | `?wait_for_active_shards` のデフォルト変更 | close index API の動作が微修正。 | 🟡 低 |
| 23 | index stats API の `types` 削除 | 統計取得での型指定が不可に。 | 🔴 高 |
| 24 | `user_agent` の `ecs` が無視される | もう効きません。入れても意味なし。 | 🟡 低 |
| 25 | `include_type_name` の削除 | 型付きマッピング完全終了。 | 🔴 高 |
| 26 | reindex 時のURL再エンコード | URLエンコードされたインデックス名が自動で再エンコードされます。 | 🟠 中 |
| 27 | `size` パラメータがリネーム | `reindex`, `delete by query`, `update by query` で名前変更あり。 | 🟠 中 |
| 28 | `script` フィールドにバリデーション追加 | `update by query` で未対応の script は拒否。 | 🟠 中 |
| 29〜32 | 複数の `local` パラメータ削除 | `cat node`, `cat shard`, `cat indices`, `get field mapping` の `local` が削除。 | 🔴 高 |
| 33 | `post data to jobs` が非推奨に | そのうち消える予定です。 | 🟡 低 |
| 34 | `job_id` プロパティ削除 | `Update datafeeds` API で不要になりました。 | 🔴 高 |
| 35 | レポジトリ使用中のステータスコード変更 | `500` → `409` に変更され、意味が明確に。 | 🟠 中 |
| 36〜37 | ML API の設定プロパティ削除 | `allow_no_datafeeds` と `allow_no_jobs` が削除。 | 🔴 高 |
| 38 | `StartRollupJob` の重複起動が成功扱いに | 再送時に成功とみなされるように。 | 🟡 低 |
| 39 | 空のスクリプト非サポートに | スクリプト／テンプレートで空文字列が無効。 | 🟠 中 |
| 40 | `code` パラメータが削除 | 保存スクリプトAPIから削除。 | 🔴 高 |
| 41 | `_type` フィールドの検索不可に | 型フィールドに依存した検索は廃止。 | 🔴 高 |
| 42 | multi search API の空行処理が変更 | 空行が action metadata として扱われる。 | 🟠 中 |
| 43 | `unmapped_type: string` 削除 | ソートの型指定オプションが使えなくなった。 | 🟠 中 |
| 44 | `_id` による集約・ソート禁止 | パフォーマンス考慮でデフォルト無効化。 | 🟠 中 |
| 45 | `common` クエリが削除 | だれも使ってないやつ、消えました。 | 🔴 高 |
| 46 | `cutoff_frequency` パラメータ削除 | `match`, `multi_match` から除外。 | 🔴 高 |
| 47 | `nested_filter`, `nested_path` 削除 | ソートリクエストの中でこれらは無効に。 | 🔴 高 |
| 48 | シャード選択に自動レプリカ最適化 | クエリは自動で最適なシャードにルーティング。 | 🟡 低 |
| 49 | ベクタ関数で `doc['field']` 非サポートに | フィールドアクセス記法が使えない。 | 🔴 高 |
| 50 | `indices_boost` がオブジェクト形式非対応に | リクエストボディの形式制限。 | 🟠 中 |
| 51 | `use_field_mapping` 削除 | 検索APIからこのパラメータが削除。 | 🔴 高 |
| 52 | `from` パラメータに負値禁止 | 検索開始位置の制限。 | 🟠 中 |
| 53 | range クエリで日付数値は常にミリ秒扱い | 曖昧性の排除。 | 🟠 中 |
| 54 | `geo_bounding_box` の `type` パラメータ削除 | 処理方式の指定が不可に。 | 🔴 高 |
| 55 | `type` クエリ削除 | 型に対する検索は完全終了。 | 🔴 高 |
| 56 | `kibana_user` ロール → `kibana_admin` | ロール名変更、設定注意。 | 🟠 中 |
| 57 | `indices` が system index を解決しない | snapshot / SLM API に影響。 | 🔴 高 |
| 58 | スナップショットのメタデータが圧縮に | デフォルトでオンに。 | 🟡 低 |
| 59 | S3 リポジトリが DNS スタイルに | URL の構造変更。 | 🟡 低 |
| 60 | リストアで `settings` 非対応に | リストア時に設定が反映されない。 | 🔴 高 |
| 61 | リポジトリ統計APIの削除 | `_snapshot/_stats` が消えた。 | 🔴 高 |
| 62 | Watcher 履歴が hidden data stream に移行 | アクセス制御の見直し必要。 | 🟠 中 |
| 63 | Cluster Health API のタイムアウトステータス変更 | ステータスコードが `408` 系に変化。 | 🟠 中 |
| 64 | `Content-Type` ヘッダーから `charset` 削除 | レスポンスエンコーディングへの影響あり。 | 🟡 低 |


### 12.SQL / JDBC の変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|---------------------------|--------|--------|
| 1 | JDBC ドライバで geometry 型の返却形式が変更 | JDBC ドライバは `org.elasticsearch.geo` オブジェクトの代わりに、geometry 情報を WKT（Well-Known Text）形式の文字列として返すようになった。既存コードで `ResultSet#getObject` を使って geo オブジェクトを期待している場合は変換処理が必要。 | 中 🟠 |
### 13.システム要件の変更一覧

| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|-----------------------------|--------|--------|
| 1 | EOL（サポート終了）OS のサポート終了 | 以下の OS は 8.0 でサポートされなくなった：Amazon Linux、CentOS 6、Debian 8、openSUSE Leap 42、Oracle EL 6、Ubuntu 16.04 | 高 🔴 |
| 2 | `SysV init` のサポート廃止 | すべての対応 OS が systemd に移行しているため `SysV init` は完全に削除された | 中 🟠 |
| 3 | Java 17 が必須に | Elasticsearch 8.0 は Java 17 以上が必須。旧バージョンで起動しようとすると失敗する | 高 🔴 |
| 4 | `JAVA_HOME` は無視されるように | JDK パス指定には `ES_JAVA_HOME` を使用する必要があり、`JAVA_HOME` は無視される | 中 🟠 |

### 14.Transform の変更一覧
| 番号 | 設定変更内容 | 詳細 | 影響度 |
|------|-----------------------------|--------|--------|
| 1 | 7.4 以前に作成された transform はアップグレードが必要 | 旧バージョンで作成された transform は非対応形式を含むため、8.0 にて `{transforms}` API を使ってアップグレードする必要がある。アップグレードはインデックス本体に影響しない。 | 中 🟠 |