考古|ES 6.0 里旧 template 字段明明还在只打废弃日志,写成数组值却匹配不到任何索引

6.0 的 Indices 变更共 8 条:索引模板匹配索引的字段从 template 改成 index_patterns(支持数组,也接受单个字符串),旧字段名仍被识别但会打废弃日志;shadow replicas 因使用率低被整体移除,连带删除 index.shared_filesystem、index.shadow_replicas、node.add_lock_id_to_custom_path;Open/Close 索引 API 的 allow_no_indices 默认值从 false 改成 true;删除文档不再自动建索引;别名 API 与删除索引 API 的 index 参数只按索引名解析;索引表达式里的 + 不再支持;translog 默认保留 12 小时或 512mb,且 flush 时不再删除。

说明

实测环境:本地起的 Elasticsearch 6.8.23 单节点实例(官方 tar 包直接跑,堆内存 512MB,机器学习关闭),curl 连本地 9200 端口。本文「实测」小节的命令和输出都出自这个实例。

来源和边界先交代:本文的依据出自 v5.6.16到 v6.8.23 标签下的官方文件(indices.asciidoc、PutIndexTemplateRequest.java、IndexMetaData.java),文中引用的原文均来自这些文件。示例取自官方示例;哪些是文档写明、哪些是我的推断,正文里逐处标注。

以下均出自 6.0 迁移文档(migrate_6_0/indices.asciidoc @ v6.8.23),共 86 行 8 条,下面逐条给出行号。

图 1:官方文件 indices.asciidoc(v6.8.23 标签)。来源:GitHub elastic/elasticsearch v6.8.23 indices.asciidoc

template → index_patterns

Previously templates expressed the indices that they should match using a glob style pattern in the template field. They should now use the index_patterns field instead. As the name implies you can define multiple glob style patterns in an array but for convenience defining a single pattern as a bare string is also supported.

(迁移文档第 9–13 行)

两种写法都合法(文档第 17–30 行给了这两个例子):

PUT _template/template_1
{
  "index_patterns": ["te*", "bar*"],
  "settings": { "number_of_shards": 1 }
}

PUT _template/template_2
{
  "index_patterns": "te*",
  "settings": { "number_of_shards": 1 }
}

改名的理由:template 装的是「这个模板要匹配哪些索引」,但名字上看不出来,和「模板本身」混在一起;index_patterns 一眼能看出是匹配模式,复数形式天然支持数组。

旧字段名在 6.x 并没有立刻失效

原文说「6.0 之后旧字段名不再被识别,用旧字段创建模板会失败」,这句不准确。6.8 的 PutIndexTemplateRequest.source 里 template 分支还在:值是字符串时按单个模式处理,并打一条废弃日志 Deprecated field [template] used, replaced by [index_patterns];代码注释写明这是为了兼容 beats、logstash 的 pre-5.0 模板(#21009)。见 PutIndexTemplateRequest.java @ v6.8.23 第 313–319 行。

真正会踩的是另一件事:该分支只接受 String。把模式写成数组却仍放在 template 字段下:

PUT _template/broken
{
  "template": ["logs-*", "metrics-*"],
  "settings": { "number_of_shards": 1 }
}

模板会创建成功,废弃日志也不会打,匹配列表是空的——新索引一条都匹配不上,而且 GET _template/broken 返回的内容看不出问题所在。这类模板的排查方向是:模板存在、order 正常,但没有任何新索引按它生效。

index_patterns 分支的取值规则见第 319–327 行:字符串按单元素处理,列表逐项 toString(),两者都不是就抛 Malformed [template] value, should be a string or a list of strings。

与 2.4 那条规则的关系

2.4 引入的「模板各自独立合法」规则在 6.0 依然生效:模板不能引用别的模板里定义的 analyzer、filter、tokenizer(2.4 的模板校验)。改名时若想把公共分析器抽到一个「公共模板」里给业务模板引用,这一步过不去——校验在 PUT 模板时就做,引用方自己不完整会被拒。

图 2:官方文件 PutIndexTemplateRequest.java(v6.8.23 标签)。来源:GitHub elastic/elasticsearch v6.8.23 PutIndexTemplateRequest.java

Shadow Replicas 移除

Shadow replicas don't see enough usage, and have been removed. This includes the following settings:

  • index.shared_filesystem
  • index.shadow_replicas
  • node.add_lock_id_to_custom_path

(迁移文档第 35–42 行)

shadow replica 是一种特殊副本:它不复制数据,直接读共享文件系统(NFS、SAN 一类)上主分片的数据文件,设计意图是给「存储层已经做了冗余」的场景省一份存储。官方给的移除理由只有一句:使用率不够。

这不是废弃而是删除。6.8 的源码里已经搜不到 index.shadow_replicas、index.shared_filesystem、node.add_lock_id_to_custom_path 三个名字;对照 5.6,index.shadow_replicas 还定义在 IndexMetaData.java @ v5.6.16 第 192 行。

影响分两头:

  • 配置项:这三个设置留在 elasticsearch.yml 或索引设置里,升级后按未知设置处理,节点启动失败(5.0 起的设置校验规则)。先删配置再升级。
  • 数据布局:用 shadow replica 的索引要改回普通副本(多一份存储)或改用快照做冗余。改之前要按现有数据量重算磁盘——功能删了,容量成本还在。

node.add_lock_id_to_custom_path 是 5.0 从 node.add_id_to_custom_path 改过来的名字,这次跟着一起删;它的用途是给 shadow replica 场景下的自定义数据路径加 lock id。

图 3:官方文件 IndexMetaData.java(v5.6.16 标签)。来源:GitHub elastic/elasticsearch v5.6.16 IndexMetaData.java

Open/Close 索引 API 的通配符行为

The default value of the allow_no_indices option for the Open/Close index API has been changed from false to true so it is aligned with the behaviour of the Delete index API. As a result, Open/Close index API don't return an error by default when a provided wildcard expression doesn't match any closed/open index.

(迁移文档第 44–51 行)

默认值在源码里能直接对上:OpenIndexRequest 的初始值是 IndicesOptions.fromOptions(false, true, false, true)(OpenIndexRequest.java 第 42 行),第二个参数就是 allowNoIndices,值为 true;参数顺序见 IndicesOptions.java 第 290–292 行。Close 侧用 IndicesOptions.strictExpandOpen(),它的 Option 集合里同样含 ALLOW_NO_INDICES(第 90–91 行)。Delete 索引 API 的默认值也是 allowNoIndices=true(DeleteIndexRequest.java 第 41 行),三条路已经对齐。

实际影响:依赖「通配符没匹配到就报错」做校验的运维脚本,升级后会静默成功。定时关闭旧索引的任务就是典型:以前索引名写错会报错提醒,现在什么都不做,日志里也看不出来。

要保留原来的校验,显式传 allow_no_indices=false。升级前可以用一次演练确认哪些脚本依赖这个行为:把通配符换成一个必然不匹配的值,看它还失不失败。

同一节里另外五条

删除文档不再自动建索引

Delete a document from non-existing index has been modified to not create the index. However if an external versioning is used the index will be created and the document will be marked for deletion.

(迁移文档第 53–58 行)

向一个不存在的索引发 delete,5.x 会把索引建出来,6.0 起不会。例外是用外部版本号(external versioning)的场景:索引仍会被创建,文档被标记删除。依赖 delete 把索引一起建出来的写法要改;用外部版本号的要先确认还是不是原意。

别名 API 只按索引名解析

The index parameter in the update-aliases, put-alias, and delete-alias APIs no longer accepts alias names. Instead, it accepts only index names (or wildcards which will expand to matching indices).

(迁移文档第 60–65 行)

源码上对应 IndicesAliasesRequest 的 INDICES_OPTIONS = IndicesOptions.fromOptions(false, false, true, false, true, false, true, false)(IndicesAliasesRequest.java 第 70 行),第七个参数 ignoreAliases 为 true。

实际影响:POST /_aliases、PUT /{index}/_alias/... 里 index 位置写别名的脚本,升级后要么解析不到要么报错,要改成真实索引名。反过来这也避免了「对着别名做别名操作」这类歧义。

删除索引 API 只按索引名解析

The index parameter in the delete index API no longer accepts alias names. Instead, it accepts only index names (or wildcards which will expand to matching indices).

(迁移文档第 67–72 行)

同上,DeleteIndexRequest 第 41 行的 ignoreAliases 也是 true。删别名不会删掉它指向的索引,想删索引要写索引名。

索引表达式里的 + 被移除

Omitting the + has the same effect as specifying it, hence support for + has been removed in index expressions.

(迁移文档第 74–79 行)

5.6 的 IndexNameExpressionResolver 里还有判断首字符是 + 的分支,并打一条废弃日志(v5.6.16 第 609 行与第 660 行);6.8 的实现里这段处理已经没有了。语义没变,只是写法删掉:升级前把脚本里的 + 前缀去掉即可。

Translog 保留策略

Translog files are now kept for up to 12 hours (by default), with a maximum size of 512mb (default), and are no longer deleted on flush. This is to increase the chance of doing an operation based recovery when bringing up replicas up to speed.

(迁移文档第 81–86 行)

两个默认值在源码里是:index.translog.retention.age 默认 12 小时(IndexSettings.java 第 208–209 行),index.translog.retention.size 默认 512mb(第 217–218 行),两者都是 Dynamic、IndexScope,可以运行中改。还有一个 index.translog.retention.total_files(默认 100,第 226 行)官方注明只用于测试、未注册。

影响面在磁盘:以前 flush 就把 translog 清掉,现在按 12 小时 / 512mb 两个上限留着,目的是让副本追平时有更大概率走 operation-based recovery(不用全量拷贝)。写入稀疏、分片数多的集群要重新估一次占用,尤其是长期不写入的历史索引。

升级 6.0 的检查清单

  1. 所有索引模板的 template 字段改成 index_patterns,同时确认没有把模式写成数组留在 template 下;
  2. 内容相同、只有匹配模式不同的模板合并成一个,用数组写多个模式;
  3. 复核模板里有没有引用别的模板定义的 analyzer/filter/tokenizer(2.4 那条规则);
  4. 搜 index.shadow_replicas、index.shared_filesystem、node.add_lock_id_to_custom_path,删掉配置;用过 shadow replica 的索引改回普通副本,按数据量重算磁盘;
  5. 依赖 Open/Close 通配符报错的脚本显式加 allow_no_indices=false;
  6. 检查有没有靠 delete 把索引一起建出来的写法;用了外部版本号的单独确认;
  7. POST /_aliases 与删除索引的 index 参数改成真实索引名,不写别名;
  8. 脚本里的索引表达式去掉 + 前缀;
  9. 按 12 小时 / 512mb 重算 translog 占用,写入稀疏的索引重点看;
  10. 用 _template API 拉全量模板做前后 diff,并建测试索引比对 settings 与 mappings。

模板改法与验证

先拉全量模板,找出还在用旧字段的:

curl -s 'localhost:9200/_template' > /tmp/templates.json

python3 -c "
import json
d = json.load(open('/tmp/templates.json'))
for name, body in d.items():
    pats = body.get('index_patterns')
    if pats is None:
        print('没有 index_patterns,检查 template 字段:', name, repr(body.get('template')))
    elif pats == []:
        print('匹配列表为空:', name)
"

改完之后做前后对比,而不是只看接口返回成功:

# 1) 改之前存一份
curl -s 'localhost:9200/_template' > /tmp/templates_before.json
# 2) 改之后存一份
curl -s 'localhost:9200/_template' > /tmp/templates_after.json
# 3) 建测试索引,看实际生效的 settings 与 mappings
curl -XPUT 'localhost:9200/test_after_001'
curl -s 'localhost:9200/test_after_001/_settings' | python3 -m json.tool
curl -s 'localhost:9200/test_after_001/_mapping' | python3 -m json.tool

模板改动的验证目标是「新索引的行为与改之前一致」,不是「PUT 没报错」。

新索引没按模板生效时,排查顺序:

# 1) 看有哪些模板、匹配模式是什么
curl -s 'localhost:9200/_cat/templates?v'
# 2) 看各模板的 index_patterns 与 order
curl -s 'localhost:9200/_template' | python3 -m json.tool | grep -A3 'index_patterns\|order'
# 3) 看索引实际拿到的设置
curl -s 'localhost:9200/test_after_001/_settings' | python3 -m json.tool

多个模板匹配同一个索引时,order 大的覆盖小的,且只在冲突项上覆盖、不冲突的合并——这是「配置没生效」最常见的原因:模板匹配上了,但被另一个 order 更大的模板盖掉。所以验证要看合并后的最终结果,不是单个模板的内容。

在 6.8.23 上跑一遍

同一个模板,两种写匹配规则的方式:

图 4:本地 6.8.23 单节点实例上的实测输出。上:老写法 template;下:新写法 index_patterns

curl -s -i -X PUT "http://localhost:9200/_template/tpl-old" \
  -H 'Content-Type: application/json' \
  -d '{"template":"t*","settings":{"number_of_shards":1}}' \
  | grep -i '^HTTP\|^Warning'

curl -s -i -X PUT "http://localhost:9200/_template/tpl-new" \
  -H 'Content-Type: application/json' \
  -d '{"index_patterns":["t*"],"settings":{"number_of_shards":1}}' \
  | grep -i '^HTTP\|^Warning'

两次都是 HTTP/1.1 200 OK,唯一的区别在响应头:老写法多一行 Warning: 299 Elasticsearch-6.8.23-... "Deprecated field [template] used, replaced by [index_patterns]"。

也就是说 6.x 上老写法仍然生效,只是每次调用都会带一条弃用告警。这决定了排查的优先级——它不会马上出问题,但如果不趁着还在 6.x 的时候改掉,升级到 7.0 就是一批模板同时失效。

结论是:把 GET /_template 的结果导出来 grep 一遍 "template":,命中就改成 index_patterns。判据不用猜,响应头里的 299 就是唯一权威信号。

写在最后

  • index_patterns 支持数组,改名时把内容重复的模板合并掉;
  • 旧 template 字段在 6.x 仍被识别(打废弃日志),但数组值会被静默忽略,模板匹配不到任何索引;
  • shadow replicas 是删除不是废弃,三个设置先清掉;我的建议是改回普通副本前重算一次磁盘,否则容易低估容量;
  • Open/Close 的 allow_no_indices 默认改成 true,依赖「通配符不匹配就报错」的脚本要显式传 allow_no_indices=false;
  • translog 按 12 小时 / 512mb 保留且 flush 不删,我的判断是写入稀疏的集群要重新估占用,按老的"flush 即清"估会偏小。

8 条里只有模板改名和 Open/Close 默认值这两条会在升级后立刻表现为「行为变了」,其余几条(别名解析、+、translog)多半体现在脚本兼容与磁盘占用上,容易被漏掉。

参考

本文对照 Elasticsearch v6.8.23 标签的官方文档与源码核对,引文逐字取自原文。图 4 的两次响应头来自本地 6.8.23 单节点实例。

0
0
0
0
评论
未登录
暂无评论