ES 版本升级检查

最近更新时间:2020-04-13 11:02:19

Elasticsearch 不同版本之间有部分不兼容的配置,如果您已设置,升级后,使用集群可能会受到影响。您可通过升级检查的功能,检查是否有不兼容的配置,并进行调整。以下是 ES 对 Elasticsearch 版本升级时检查的配置说明。

升级检查操作入口,在 控制台 详情页,单击右上角【升级】,操作步骤详见 升级 ES 集群

警告:

需特别留意本文中需要人工检查的部分(无法自动检查),并在升级前完成代码兼容性改造,避免升级后造成集群无法正常访问,例如,6.8版本升级到7.5版本后默认无法创建包含 type 的索引,详情见下文 需人工自查的不兼容配置

Elasticsearch 5.x 版本升级到 6.x 版本配置检查

检查的配置项列表

序号 配置维度 配置信息 兼容性 详细说明
1 集群级别 集群快照设置(Snapshot settings) CRITICAL 集群设置cluster.routing.allocation.snapshot.relocation_enabled,在6.0版本开始被废弃,详见 Breaking changes in 6.0
2 集群级别 集群存储限流设置(Store throttling settings) CRITICAL 集群设置indices.store.throttle.typeindices.store.throttle.max_bytes_per_sec,在6.0版本开始被废弃,详见 Breaking changes in 6.0
3 索引级别 索引相似性设置(Similarity settings) WARNING 索引设置index.similarity.base,在6.0版本开始被废弃,详见 Breaking changes in 6.0
4 索引级别 索引影子副本设置(Shadow Replicas settings) CRITICAL 索引设置index.shared_filesystemindex.shadow_replicas,在6.0版本开始被废弃,详见 Breaking changes in 6.0
5 索引级别 索引存储设置(Index Store settings) CRITICAL 索引设置index.store.type为 default,在6.0版本开始被废弃,详见 Breaking changes in 6.0
6 索引级别 索引存储限流设置(Index Store throttling settings) CRITICAL 索引设置index.store.throttle.typeindex.store.throttle.max_bytes_per_sec,在6.0版本开始被废弃,详见 Breaking changes in 6.0
7 索引级别 索引 Mapping 参数 include_in_all WARNING 索引 mapping 参数include_in_all,在6.0版本之后创建的索引中无法使用(5.x 版本创建包含此设置的索引在升级 6.x 版本后可以兼容),详见 Breaking changes in 6.0
8 索引级别 索引创建版本 CRITICAL 索引创建版本index.version.created不允许跨 ES 主版本,例如,无法将在 5.x 版本创建的索引直接升级到 7.x 版本,需要将失败的索引 reindex 迁移到新索引并删除后再进行升级。
9 索引模板级别 索引模板相似性设置(Similarity settings) CRITICAL 索引设置index.similarity.base,在6.0版本开始被废弃,详见 Breaking changes in 6.0,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
10 索引模板级别 索引模板影子副本设置(Shadow Replicas settings) CRITICAL 索引设置index.shared_filesystemindex.shadow_replicas,在6.0版本开始被废弃,详见 Breaking changes in 6.0,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
11 索引模板级别 索引模板存储设置(Index Store settings) CRITICAL 索引设置index.store.type为 default,在6.0版本开始被废弃,详见 Breaking changes in 6.0,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
12 索引模板级别 索引模板存储限流设置(Index Store throttling settings) CRITICAL 索引设置index.store.throttle.typeindex.store.throttle.max_bytes_per_sec,在6.0版本开始被废弃,详见 Breaking changes in 6.0,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
13 索引模板级别 索引模板 Mapping 参数 include_in_all CRITICAL 索引 Mapping 参数include_in_all,在6.0版本开始被废弃,详见 Breaking changes in 6.0,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
14 索引模板级别 索引模板 Mapping 元字段 _all CRITICAL 索引 Mapping 元字段_all,在6.0版本开始被废弃,详见 Breaking changes in 6.0,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
15 索引模板级别 索引模板 Mapping 多个 Types CRITICAL 索引 Mapping 包含多个 Types,在6.0版本开始被废弃,详见 Removal of mapping types,模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
说明:

  • 警告(WARNING):检查失败时仍可以升级。此类型检查项对应设置在升级后将被忽略。
  • 错误(CRITICAL):检查失败时无法升级。此类型检查项对应设置在目标版本无法兼容。

配置不兼容调整方法

集群级别

  • 集群快照设置(Snapshot settings)
    通过 ES 集群设置更新接口PUT _cluster/settings取消此设置(包括 persistent 和 transient):
    PUT _cluster/settings
    {
      "persistent": {
        "cluster.routing.allocation.snapshot.relocation_enabled": null
      },
      "transient": {
        "cluster.routing.allocation.snapshot.relocation_enabled": null
      }
    }
  • 集群存储限流设置(Store throttling settings)
    通过 ES 集群设置更新接口PUT _cluster/settings取消此设置(包括 persistent 和 transient):
    PUT _cluster/settings
    {
      "persistent": {
        "indices.store.throttle.type": null,
        "indices.store.throttle.max_bytes_per_sec": null
      },
      "transient": {
        "indices.store.throttle.type": null,
        "indices.store.throttle.max_bytes_per_sec": null
      }
    }

索引级别

  • 索引相似性设置(Similarity settings)
    此设置在升级 6.x 后被忽略,但不会影响升级。如需取消设置,可按照如下步骤操作:
    • 此设置需要关闭索引后修改,关闭后的索引无法被读写。关闭索引:
      POST my_index/_close
    • 使用 ES 索引设置更新接口取消此设置:
      PUT my_index/_settings
      {
         "index.similarity.base.*": null
      }
    • 最后打开索引:
      POST my_index/_open
  • 索引影子副本设置(Shadow Replicas settings)
    • 此设置需要关闭索引后修改,关闭后的索引无法被读写。关闭索引:
      POST my_index/_close
    • 使用 ES 索引设置更新接口取消此设置:
      PUT my_index/_settings
      {
          "index.shared_filesystem": null,
          "index.shadow_replicas": null
      }
    • 最后打开索引:
      POST my_index/_open
  • 索引存储设置(Index Store settings)
    • 此设置需要关闭索引后修改,关闭后的索引无法被读写。关闭索引:
      POST my_index/_close
    • 使用 ES 索引设置更新接口取消此设置:
      PUT my_index/_settings
      {
         "index.store.type": null
      }
    • 最后打开索引:
      POST my_index/_open
  • 索引存储限流设置(Index Store throttling settings)
    使用 ES 索引设置更新接口取消此设置:
    PUT my_index/_settings
    {
      "settings": {
        "index.store.throttle.type": null,
        "index.store.throttle.max_bytes_per_sec": null
      }
    }
  • 索引 Mapping 参数 include_in_all
    对已创建的包含此参数的索引,升级后可以兼容,无需修复。

索引模板级别

  1. 使用 API GET _template/my_template 获取不兼容模板my_template。存在以下三个不兼容设置:索引模板存储设置(Index Store settings)、索引模板 Mapping 参数 include_in_all、索引模板 Mapping 元字段_all
    {
     "my_template": {
       "order": 0,
       "template": "my_*",
       "settings": {
         "index": {
           "store": {
             "throttle": {
               "max_bytes_per_sec": "10m"
             }
           }
         }
       },
       "mappings": {
         "my_type": {
           "_all": {
             "enabled": true
           },
           "properties": {
             "my_field": {
               "type": "text",
               "include_in_all": true
             }
           }
         }
       },
       "aliases": {}
     }
    }
  2. 拷贝并去除模板中不兼容配置后,使用 API PUT _template/my_template 更新模板。
    PUT _template/my_template
    {
       "order": 0,
       "template": "my_*",
       "settings": {
       },
       "mappings": {
         "my_type": {
           "properties": {
             "my_field": {
               "type": "text"
             }
           }
         }
       },
       "aliases": {}
    }

Elasticsearch 6.8 版本升级到 7.x 版本配置检查

需人工自查的不兼容配置

  • 对于超过1024个字段数的索引,查询时如果不指定字段会非常消耗性能。建议设置默认查询字段index.query.default_field。如果仍要查询所有字段,那么可以通过提高“布尔查询最大子句数”设置indices.query.bool.max_clause_count来实现。
  • include_type_name默认为 false,升级后默认将无法创建包含 type 的索引,需要显式指定参数include_type_name
    警告:

    需重点关注集群是否有此项不兼容配置,避免升级后造成集群无法正常访问。

     PUT my_index?include_type_name
     {
       "mappings": {
         "type1": {
           "properties": {
             "name": {
               "type": "text"
             }
           }
         }
       }
     }

可自动检查的配置项列表

序号 配置维度 配置信息 兼容性 详细说明
1 集群级别 用户代理预处理器(User agent processor)设置 WARNING 用户代理预处理器(User agent processor)的格式默认值变为ecs,详见 Breaking changes in 7.0
2 集群级别 集群分片数 WARNING 每个节点最大 shard 数cluster.max_shards_per_node默认1000,shard 数超过在升级后将无法创建新分片,详见 Breaking changes in 7.0
3 集群级别 集群设置(discovery.zen.no_master_block) WARNING 集群设置discovery.zen.no_master_block改名为cluster.no_master_block,详见 Breaking changes in 7.0
4 集群级别 预处理器管道(Ingest pipeline)日期格式 WARNING 预处理器管道(Ingest pipeline)datedate_index_name处理器使用废弃的日期格式,详见 Breaking changes in 7.0
5 索引级别 索引创建版本 CRITICAL 不允许6.0版本之前创建的索引升级到7.x版本,详见 Breaking changes in 7.0
6 索引级别 Delimited payload 词汇单元过滤器(Token filter)索引设置 WARNING Delimited payload 语汇单元过滤器(Token filter)从delimited_payload_filter改名为delimited_payload,详见 Breaking changes in 7.0
7 索引级别 索引设置(index.percolator.map_unmapped_fields_as_string) CRITICAL 索引设置index.percolator.map_unmapped_fields_as_string 改名为 index.percolator.map_unmapped_fields_as_text,详见 Breaking changes in 7.0
8 索引级别 索引名 WARNING 索引名不能包含“:”,详见 Breaking changes in 7.0
9 索引级别 索引设置(index.unassigned.node_left.delayed_timeout) CRITICAL 索引设置index.unassigned.node_left.delayed_timeout负数值被废弃,详见 Breaking changes in 7.0
10 索引级别 索引设置(index.shard.check_on_startup) CRITICAL 索引设置index.shard.check_on_startup的值为fix被废弃,详见 Breaking changes in 7.0
11 索引级别 经典相似性(classic similarity)索引 Mapping 参数 WARNING 经典相似性(classic similarity)索引 Mapping 参数被废弃,详见 Breaking changes in 7.0
12 索引级别 经典相似性(classic similarity)索引设置 WARNING 经典相似性(classic similarity)索引设置被废弃,详见 Breaking changes in 7.0
13 索引级别 索引字段数 WARNING 对于超过1024个字段的索引,建议设置默认查询字段(index.query.default_field)或提升最大字段数设置(indices.query.bool.max_clause_count),否则升级后将导致不指定字段的查询无法正常使用,详见 Breaking changes in 7.0
14 索引级别 索引 Mapping 日期格式 WARNING Joda-Time 格式改为 Java Time,详见 Breaking changes in 7.0
15 索引模板级别 Delimited payload 语汇单元过滤器(Token filter)索引模板设置 WARNING Delimited payload 语汇单元过滤器(Token filter)从delimited_payload_filter改名为delimited_payload,详见 Breaking changes in 7.0
16 索引模板级别 索引模板设置(index.percolator.map_unmapped_fields_as_string) CRITICAL 索引模板设置index.percolator.map_unmapped_fields_as_string改名为 index.percolator.map_unmapped_fields_as_text,升级后不兼容,详见 Breaking changes in 7.0
17 索引模板级别 索引模板设置(index.unassigned.node_left.delayed_timeout) CRITICAL 索引模板设置index.unassigned.node_left.delayed_timeout负数值被废弃,升级后不兼容,详见 Breaking changes in 7.0
18 索引模板级别 索引模板设置(index.shard.check_on_startup) CRITICAL 索引模板设置index.shard.check_on_startup的值为fix被废弃,升级后不兼容,详见 Breaking changes in 7.0
19 索引模板级别 经典相似性(classic similarity)索引模板 Mapping 参数 CRITICAL 经典相似性(classic similarity)索引模板 Mapping 参数被废弃,升级后不兼容,详见 Breaking changes in 7.0
20 索引模板级别 经典相似性(classic similarity)索引模板设置 CRITICAL 经典相似性(classic similarity)索引模板设置被废弃,升级后不兼容,详见 Breaking changes in 7.0
21 索引模板级别 索引模板字段数 CRITICAL 对于超过1024个字段的索引模板,建议设置默认查询字段(index.query.default_field)或提升最大字段数设置(indices.query.bool.max_clause_count),否则升级后将导致不指定字段的查询无法正常使用,详见 Breaking changes in 7.0
22 索引模板级别 索引模板 Mapping 日期格式 WARNING Joda-Time 格式改为 Java Time,详见 Breaking changes in 7.0

配置不兼容调整方法

集群级别

  • 用户代理预处理器(User agent processor)设置
    使用非ecs格式的 user agent 将被废弃,应调整为:
    PUT _ingest/pipeline/my_pipeline1
    {
    "processors" : [
      {
        "user_agent" : {
          "field" : "agent",
          "ecs": true
        }
      }
    ]
    }
  • 集群分片数
    对于超过分片数限制的集群,有两种调整方法:
    • 降低集群分片数(通过清理过期索引、shrink 索引 等)。
    • 修改集群设置提高分片数限制。
      PUT _cluster/settings
      {
      "persistent": {
      "cluster.max_shards_per_node": 5000
      }
      }
  • 集群设置(discovery.zen.no_master_block)
    对于使用了集群设置discovery.zen.no_master_block的集群,在升级完成后调整为cluster.no_master_block,例如:
    PUT _cluster/settings
    {
    "persistent": {
      "cluster.no_master_block": "write"
    }
    }
  • 预处理器管道(Ingest pipeline)日期格式
    可参考 Joda based date formatters are replaced with java ones 进行调整。

索引级别

  • 索引创建版本
    不允许6.0版本之前创建的索引升级到7.x版本,对于需要保留的索引,需要在升级前执行 reindex , 例如:
    POST _reindex
    {
    "source": {
      "index": "my_index"
    },
    "dest": {
      "index": "new_my_index"
    }
    }
  • Delimited payload 语汇单元过滤器(Token filter)索引模板设置
    将索引设置中的delimited_payload_filter改为delimited_payload,例如原始索引如下:
    PUT my_index
    {
    "settings": {
      "analysis": {
        "analyzer": {
          "whitespace_plus_delimited": {
            "tokenizer": "whitespace",
            "filter": [ "plus_delimited" ]
          }
        },
        "filter": {
          "plus_delimited": {
            "type": "delimited_payload_filter",
            "delimiter": "+",
            "encoding": "int"
          }
        }
      }
    }
    }
    修改后的索引:
    PUT my_index
    {
    "settings": {
      "analysis": {
        "analyzer": {
          "whitespace_plus_delimited": {
            "tokenizer": "whitespace",
            "filter": [ "plus_delimited" ]
          }
        },
        "filter": {
          "plus_delimited": {
            "type": "delimited_payload",
            "delimiter": "+",
            "encoding": "int"
          }
        }
      }
    }
    }
  • 索引设置(index.percolator.map_unmapped_fields_as_string)
    将索引设置index.percolator.map_unmapped_fields_as_string调整为index.percolator.map_unmapped_fields_as_text(此设置调整前需要 close 索引)。
    PUT my_index/_settings
    {
    "index.percolator.map_unmapped_fields_as_text": true
    }
  • 索引名
    对于包含“:”的索引,需执行 reindex,例如:
    POST _reindex
    {
    "source": {
      "index": "my_index"
    },
    "dest": {
      "index": "new_my_index"
    }
    }
  • 索引设置(index.unassigned.node_left.delayed_timeout)
    将索引设置index.unassigned.node_left.delayed_timeout调整为正整数:
    PUT my_index/_settings
    {
    "index.unassigned.node_left.delayed_timeout": 0
    }
  • 索引设置(index.shard.check_on_startup)
    将索引设置index.shard.check_on_startup值为fix调整为其它值,例如:
    PUT my_index/_settings
    {
    "index.shard.check_on_startup": true
    }
  • 经典相似性(classic similarity)索引 Mapping 参数、经典相似性(classic similarity)索引设置
    对于包含经典相似性(classic similarity)的索引设置或 Mapping,调整为其他类型,例如原始索引如下:
    PUT my_index
    {
    "mappings": {
      "doc": {
        "properties": {
          "field1": {
            "properties": {
              "field4": {
                "type": "text",
                "similarity": "classic"
              }
            }
          }
        }
      }
    }
    }
    修改后的索引为:
    PUT my_index
    {
    "mappings": {
      "doc": {
        "properties": {
          "field1": {
            "properties": {
              "field4": {
                "type": "text",
                "similarity": "BM25"
              }
            }
          }
        }
      }
    }
    }
  • 索引字段数
    对于超过1024个字段的索引,有两种调整方法:
    • 设置默认查询字段设置index.query.default_field
      PUT my_index/_settings
      {
      "index.query.default_field": "field1"
      }
    • 通过修改 ES YML 配置文件提升最大字段数设置indices.query.bool.max_clause_count(后续支持)。
  • 索引 Mapping 日期格式
    可参考 Joda based date formatters are replaced with java ones 进行调整。

索引模板级别

索引模板级别的不兼容设置调整请参考 索引级别

目录