Vector elasticsearch Sink 配置字段弃用迁移指南：从 mode = normal 到 bulk 及源码实现对照

Vector elasticsearch Sink 配置字段弃用迁移指南：从 mode = normal 到 bulk 及源码实现对照

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector

Vector 的elasticsearchsink 在 0.18.0 版本中对顶层配置字段做了一次结构性调整：一批历史字段被标记为弃用并计划于 0.19.0 移除，取而代之的是分组更清晰的bulk与request子配置块。本篇基于该弃用公告的字段映射表，结合当前仓库 elasticsearch sink 源码 的实际实现，完整给出每个旧字段的迁移方式、新字段默认值与取值范围，以及后续版本中endpoint等字段被进一步弃用的演进脉络，帮助你在升级 Vector 时平滑改写 Elasticsearch 输出配置。

弃用背景：0.18.0 的字段重组

0.18.0 的官方弃用公告（2021-10-19-elasticsearch-config-deprecations.md）声明：部分elasticsearchsink 配置字段被弃用，并计划在 0.19.0 中移除。公告给出的完整映射表如下（本文完整继承该表）：

这次调整的核心思路是：把散落在顶层的写入参数收敛到bulk子块（描述"如何调用 Bulk API"），把 HTTP 层参数收敛到request子块（描述"如何发出 HTTP 请求"），与 sink 的mode概念对齐。下文逐字段说明迁移方式，并用当前仓库源码佐证每个新字段的解析位置、默认值与行为。

逐字段迁移说明

1.mode = normal→mode = bulk

写入模式字段mode的取值在 0.18.0 起由normal更名为bulk。当前源码中该枚举定义在 ElasticsearchMode：

pub enum ElasticsearchMode { /// Ingests documents in bulk, using the bulk API `index` action. #[serde(alias = "normal")] #[default] Bulk, /// Ingests documents in bulk, using the bulk API `create` action. DataStream, }

#[serde(alias = "normal")]表明源码在反序列化时保留了normal作为bulk的别名，即旧配置中的mode: normal仍可被解析，但新配置应统一写mode: bulk（或省略，因为bulk就是默认模式）。另一个取值data_stream面向 Elasticsearch Data Streams，固定使用create动作；从源码结构看，Data Stream 模式还会自动把事件中的timestamp字段重命名为 Elastic Common Schema 要求的@timestamp（见 config.rs 中 DATA_STREAM_TIMESTAMP_KEY 及DataStreamMode::remap_timestamp）。

2.host→endpoint（并进一步演进为endpoints）

连接地址字段从host更名为endpoint。在 0.18.0/0.19.0 之后，当前仓库又完成了一轮演进：endpoint（单地址）本身也被标记为弃用，推荐改用可写多个地址的endpoints列表。这一点在 ElasticsearchConfig 上有明确的deprecated元数据：

/// The Elasticsearch endpoint to send logs to. #[serde(default)] #[configurable( deprecated = "This option has been deprecated, the `endpoints` option should be used instead." )] #[configurable(required_one_of = "endpoint")] pub endpoint: Option<HttpEndpoint>, /// A list of Elasticsearch endpoints to send logs to. #[serde(default)] #[configurable(required_one_of = "endpoint")] pub endpoints: Vec<HttpEndpoint>,

两个约束值得注意：

• endpoint与endpoints是"必选其一"（required_one_of）关系：两者都缺失会在验证阶段报Endpoints option must be specified，两者同时出现则报互斥错误。对应的验证逻辑见 validate()，并有单元测试 validate_rejects_endpoint_and_endpoints 覆盖。
• endpoints支持在 URL 中内嵌 Basic 认证凭据，如https://user:password@example.com；若同时配置了auth且 URL 内含凭据，会触发配置错误（源码见 ElasticsearchConfig 注释）。
• 运行时，如果检测到旧式endpoint字段，ElasticsearchCommon::parse_many 会打印弃用告警：DEPRECATION, use of deprecated option 'endpoint'. Please use 'endpoints' option instead.（common.rs 第 279-281 行）。

因此，从 0.18.0 时代迁移过来的endpoint配置，在当前版本建议直接改写为endpoints列表。

3.bulk_action→bulk.action

Bulk API 的动作字段从顶层bulk_action移入bulk子块。当前实现见 BulkConfig：

pub struct BulkConfig { /// Action to use when making requests to the Elasticsearch Bulk API. /// Only `index`, `create` and `update` actions are supported. #[serde(default = "default_bulk_action")] pub action: UnconfinedTemplate, /// The name of the index to write events to. #[serde(default = "default_index")] pub index: Template, /// The default index to write events to if the template in `bulk.index` cannot be resolved pub template_fallback_index: Option<String>, pub version: Option<UnconfinedTemplate>, pub version_type: VersionType, }

关键点：

• 取值范围为index、create、update三者之一，默认值是index（见 default_bulk_action()）；解析逻辑由 BulkAction::try_from 完成，非法取值会报Invalid bulk action。
• bulk.action的类型是UnconfinedTemplate，即支持按事件做模板渲染（如action: "{{ action }}"），在运行期由 ElasticsearchCommonMode::bulk_action 逐事件求值后再转成BulkAction；data_stream模式则固定为create。
• 实际写入 Bulk 请求体的编解码在 encoder.rs 中完成，每个事件的 action 行由write_bulk_action生成。

另外，顶层的bulk配置块本身也保留了历史别名——config.rs 第 192 行 的#[serde(alias = "normal", default)]表明旧版以normal命名的顶层块同样能映射到bulk，这是为旧配置平滑过渡留下的兼容入口。

4.index→bulk.index

索引名从顶层index移入bulk.index。默认值为vector-%Y.%m.%d（按天滚动索引，见 default_index()），支持模板化，官方文档示例为application-{{ application_id }}-%Y-%m-%d。

当前实现比 0.18.0 时期更精细，有三个值得了解的机制（见 ElasticsearchCommonMode::index）：

• 模板失败回退：可配置bulk.template_fallback_index指定模板渲染失败时使用的兜底索引；
• confinement 安全约束：bulk.index属于路由字段，会先经过 common_mode() 的模板 confinement 检查再渲染。若渲染因安全约束（而非普通渲染错误）失败，事件会被直接丢弃且不会回退到兜底索引——源码注释明确说明这是有意设计，避免"静默接受一个攻击性事件"；
• 请求路由：所有 bulk 请求最终发往{base_url}/_bulk?{query}端点，由 ElasticsearchCommon::parse_config 拼接，pipeline等查询参数也会附加在该 URI 上。

5.headers→request.headers

HTTP 请求头从顶层headers移入request子块。该结构定义在 sink 通用的 RequestConfig：

/// Outbound HTTP request settings. pub struct RequestConfig { #[serde(flatten)] pub tower: TowerRequestConfig, /// Additional HTTP headers to add to every HTTP request. pub headers: BTreeMap<String, String>, }

要点：

• request是扁平化嵌入的（#[serde(flatten)]展开 tower 配置），所以除headers外，request子块下还能写max_retries、timeout等请求层参数；
• 头部名称与值均支持事件模板渲染（如X-Event-Level: "{{level}}"、X-Event-Timestamp: "{{timestamp}}"），源码通过 split_headers() 把头部拆分为"静态头"与"模板头"两类分别处理，避免为纯静态头做逐事件渲染；
• request.headers作用于每一个发往 Elasticsearch 的 HTTP 请求，包括健康检查请求——get() 在构造 GET 请求时会遍历request.headers逐一附加。

迁移前后配置对照

结合上述映射，一个典型的旧版（0.18.0 之前）配置：

sinks: es: type: elasticsearch inputs: [my_source] mode: normal host: http://10.24.32.122:9000 bulk_action: create index: application-%Y.%m.%d headers: X-My-Custom-Header: "A-Value"

按 0.18.0 的弃用表迁移后为：

sinks: es: type: elasticsearch inputs: [my_source] mode: bulk # 默认值，可省略 endpoint: http://10.24.32.122:9000 bulk: action: create # 默认 index index: application-%Y.%m.%d request: headers: X-My-Custom-Header: "A-Value"

若进一步适配当前仓库对应的版本（endpoint已弃用），则推荐最终形态：

sinks: es: type: elasticsearch inputs: [my_source] endpoints: # 取代已弃用的单数 endpoint - http://10.24.32.122:9000 - http://10.24.32.123:9000 api_version: auto # 默认 auto，启动时自动探测 bulk: action: create index: application-%Y.%m.%d request: headers: X-My-Custom-Header: "A-Value"

后续版本中同样重要的弃用项

除 0.18.0 这批字段外，当前源码中还能看到两项仍在生效的弃用，建议在改写配置时一并处理：

suppress_type_name与api_version的关系可以从源码推断：type字段在 Elasticsearch 7.x 弃用、8.x 移除，api_version（auto/v6/v7/v8）取代了它的作用。当api_version: auto时，Vector 在构建期向集群根路径发起 GET 请求读取主版本号（get_version()）；若探测失败，源码会降级为启发式假设——如果旧配置设置了suppress_type_name则假定 v6，否则假定 v8（common.rs 第 166-185 行），并建议显式设置api_version。

运行时行为与验证要点

改写配置后，几个可以在实际部署中验证的行为（均有源码依据）：

• 端点校验前移：endpoint(s)必须包含 http/https 协议且带主机名，否则在反序列化阶段即失败（测试 validate_rejects_non_http_endpoint 断言错误信息含must be an absolute http(s) URL）。
• 版本号约束校验：bulk.version与bulk.version_type的组合在 validate() 中会被静态校验，例如version_type: external未配bulk.version会报ExternalVersioningWithoutVersion，配了version却没配id_key会报ExternalVersioningWithoutDocumentID——这两类配置错误在构建期即可发现，而不会拖到运行时。
• 健康检查：sink 通过GET /_cluster/health探活（healthcheck()），request.headers中配置的头部会随该请求发出；Amazon OpenSearch Serverless 场景会跳过健康检查并强制api_version: auto（validate()）。
• 多端点容错：endpoints列表中的每个地址各自构建一个 service，经 build() 装配为分布式服务，配合重试与健康逻辑在端点间调度；健康检查采用select_ok语义，任一端点可达即通过。
• 部分失败重试：request_retry_partial默认关闭；若开启以重试含部分失败的批量请求，源码注释提醒应配合id_key去重（config.rs 第 127-131 行）。

小结：迁移检查清单

1. mode: normal改为mode: bulk（或省略，bulk为默认）；
2. host改为endpoint，并在当前版本进一步改为endpoints列表；注意与auth的互斥规则——URL 内嵌凭据与显式auth二选一；
3. bulk_action改为bulk.action，取值限index/create/update，默认index，支持按事件模板化；
4. index改为bulk.index，默认vector-%Y.%m.%d，可配bulk.template_fallback_index做渲染失败回退；
5. headers改为request.headers，键值均支持事件模板渲染；
6. 顺带审视suppress_type_name，改为显式api_version，避免探测失败时的启发式版本假设。

以上每一项均能在 src/sinks/elasticsearch/ 模块内找到对应的解析、校验与渲染代码路径；改写后可用vector validate在部署前捕获端点互斥、版本号组合等静态配置错误，再借助/_cluster/health健康检查确认目标集群连通。

【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector