ES 远程集群的证书模式被弃用，换成 API key 还能收紧访问范围

9.0 起，用证书模式配置远程集群会在弃用日志里产生警告。官方说它"将在未来主版本移除"，推荐迁移到 API key 模式——理由是后者能做细粒度访问控制。如果你在用跨集群，这条值得排进计划。

说明

本文基于 v9.4.2 的 changelog、官方文档与服务端源码。文中引用的行号都来自这个 tag，点链接能看到对应原文。

迁移的具体步骤本文未展开（官方有专门的迁移文档）；示例命令按通用写法给出，未在集群上执行。

官方条目

9.0 的 changelog 标为 deprecation（9.0.0.yml 第 1785–1796 行 @ v9.4.2），PR 120806，area: Security。

（上一版把这条写成 PR 120807，实际 120807 是 “Remove INDEX_REFRESH_BLOCK after index becomes searchable”，见第 1797–1799 行；本条是 120806。）

details 说明了处置和方向：

Certificate-based remote cluster security model is deprecated and will be removed in a future major version. Users are encouraged to migrate remote clusters from certificate to API key authentication. The API key-based security model is preferred way to configure remote clusters, as it allows to follow security best practices when setting up remote cluster connections and defining fine-grained access control.

impact 说了实际表现：

If you have configured remote clusters with certificate-based security model, you should migrate remote clusters from certificate to API key authentication. Configuring a remote cluster using certificate authentication, generates a warning in the deprecation logs.

拆开：

• 证书模式已弃用，将在未来主版本移除（没说是哪个版本）；
• 官方鼓励迁移到 API key 认证；
• 推荐理由：能遵循安全最佳实践、能定义细粒度访问控制；
• 当前的实际影响：配置证书模式的远程集群会在弃用日志里产生警告。

两种模式是什么

远程集群（跨集群搜索/复制）需要解决一个问题：怎么证明"我是谁"，以及"我能看什么"。

ES 提供了两套安全模型：

证书模式（certificate-based）：靠 TLS 证书建立信任。配置了 CA 或者 truststore，远端集群就可信。

API key 模式（API key-based）：用专门的跨集群 API key 认证。这个 key 在创建时就绑定了权限范围。

官方推荐后者的关键理由是那句 defining fine-grained access control——细粒度访问控制。

差别在：

• 证书模式证明的是"这个集群是谁"——身份层面的信任；
• API key 模式还能表达"这个集群能访问什么"——权限层面的控制。

举例：你可以给远程集群创建一个只能读某几个索引的 key。证书模式下做不到这一点——证书能证明身份，但不携带权限信息。

源码里的落点

上一版说"没找到弃用标记的位置"——它在 RemoteConnectionManager 里，不在 x-pack 的安全扩展里，所以按 security 相关的类名去搜搜不到。

一，弃用告警的完整实现（RemoteConnectionManager.java 第 110–138 行 @ v9.4.2）：

@Override
public void openConnection(DiscoveryNode node, @Nullable ConnectionProfile profile, ActionListener<Transport.Connection> listener) {
    assert profile == null || profile.getTransportProfile.equals(getConnectionProfile.getTransportProfile)
        : "A single remote connection manager can only ever handle a single transport profile";
    delegate.openConnection(
        node,
        profile,
        listener.delegateFailureAndWrap(
            (l, connection) -> l.onResponse(
                maybeLogDeprecationWarning(wrapConnectionWithRemoteClusterInfo(connection, clusterAlias, credentialsManager))
            )
        )
    );
}

private InternalRemoteConnection maybeLogDeprecationWarning(InternalRemoteConnection connection) {
    if (connection.getClusterCredentials == null
        && (false == REMOTE_CLUSTER_PROFILE.equals(this.getConnectionProfile.getTransportProfile))) {
        deprecationLogger.warn(
            DeprecationCategory.SECURITY,
            "remote_cluster_certificate_access-" + connection.getClusterAlias,
            "The remote cluster connection to [{}] is using the certificate-based security model. "
                + "The certificate-based security model is deprecated and will be removed in a future major version. "
                + "Migrate the remote cluster from the certificate-based to the API key-based security model.",
            connection.getClusterAlias
        );
    }
    return connection;
}

三点值得留意：

• 判据和文档一致：getClusterCredentials == null，也就是 keystore 里没有 cluster.remote.<alias>.credentials → 证书模式 → 打告警。这和文档第 50 行说的是同一条规则，源码是它的实现。
• 告警的 key 是 remote_cluster_certificate_access-<别名>，分类是 DeprecationCategory.SECURITY。排查时可以直接按这个 key 在弃用日志里 grep，比按消息正文搜靠谱。
• 触发时机是每次建连（openConnection 的回调里），不是配置时打一次。所以在用的集群会持续看到它，不用等到重启或改配置。

二，还有一个会让它不出现的条件：第二个判断是 false == REMOTE_CLUSTER_PROFILE.equals(...)，而 REMOTE_CLUSTER_PROFILE 的值是 "_remote_cluster"（RemoteClusterPortSettings.java 第 42 行）。也就是说，走 remote cluster server port（_remote_cluster 这个 transport profile）的连接，即便用证书模式也不会打这条告警——判断用的是 transport profile，不是"有没有配证书"。

所以"配了证书模式就一定有告警"这句话要打个折：告警的有无取决于连接走的 profile。

怎么判断自己在用哪种

文档里有一条明确的判定规则（remote-clusters.md 第 50 行 @ v9.4.2），说的是 cluster.remote.<cluster_alias>.credentials 这个设置：

The presence (or not) of this setting determines which model a remote cluster uses. If present, the remote cluster uses the API key based model. Otherwise, it uses the certificate based model.

判断标准就一条：

• 配了 credentials → API key 模式；
• 没配 → 证书模式。

所以排查很简单——看 keystore 里有没有这个设置：

/usr/share/elasticsearch/bin/elasticsearch-keystore list | grep -i "cluster.remote"

如果只看到 cluster.remote.<alias>.seeds 之类、没有 credentials，那就在用证书模式。

（说明：这个设置是 keystore 里的安全设置，不在 elasticsearch.yml 里，所以 grep 配置文件找不到。这一点和 discovery-ec2 换 SDK v2 里的 discovery.ec2 系统属性类似——有些配置不在常规位置。）

迁移要做什么

按官方的说法，迁移方向是"从证书到 API key"。具体步骤官方有专门文档（changelog 里链到了 remote-clusters-migrate），具体步骤以官方文档为准。

能确定的两点：

一，要创建跨集群 API key。 ES 提供了专门的 API（security.create_cross_cluster_api_key，文档里有链接）。创建时指定权限范围——这就是"细粒度"的由来。

二，把它配到 cluster.remote.<alias>.credentials。按文档的说明，这个值放在 keystore 里，并且每个节点都要配。

文档还提到一个便利之处（同一段说明）：

If the setting is added, removed, or updated in the ES keystore and reloaded via the Nodes reload secure settings API, the cluster will automatically rebuild its connection to the remote.

改完可以热加载——通过 reload secure settings API 触发，集群会自动重建连接，不用重启节点。这对生产环境挺重要，省掉一次滚动重启。

为什么细粒度控制更合适

官方那句"细粒度访问控制"是这次迁移真正的价值所在。

用证书模式配置远程集群时，典型的形态是：信任了远端集群，它就能查它能查的东西。权限的边界在远端集群侧——本地集群没法限制"对方只能看我这几个索引"。

API key 模式把这个边界移到了本地：创建 key 的时候就写清楚"这个 key 能读哪些索引"。远端拿着这个 key 过来，超出范围的请求会被拒绝。

这个差别在多团队协作或者合规要求下很重要：

• 多团队：不同业务线的集群互相连接时，你不希望 A 团队能看 B 团队的全部数据；
• 合规：数据访问范围需要可审计、可证明。key 上绑定的权限是显式的，比"配了证书所以能访问"更容易说明白。

第二点在审计场景里价值最明显——当被问到"这个远程集群能访问什么"时，证书模式要翻 TLS 配置和远端权限设置才能回答，API key 模式看 key 的定义就行。

迁移前要想清楚的一件事

要迁的话，先做一件事：盘一遍现有的跨集群访问需求。

因为 API key 要绑定权限，你得先知道每个远程集群实际需要访问什么。如果从没梳理过，直接迁很可能会：

• 权限给大了 → 等于没迁移，白做；
• 权限给小了 → 业务查询开始报错。

做法是先从宽松起步，再逐步收紧：创建时给一个比实际需要稍大的范围，观察一段时间（看有没有越界访问），再收到合适的范围。

这个办法慢，但比"一步到位"安全。权限收紧导致的故障排查起来很花时间——报错信息通常只说"没权限"，不会告诉你应该要什么权限。

迁移时的两个容易踩的点

一是别只验正向，要验反向。迁移完成后，很多人只试"该查的能查到"，这是不够的。API key 的价值在于限制，所以要专门试一次访问未授权的索引，确认被拒。

只验正向不验反向，等于没验证权限是否真的生效——万一 key 上绑的权限比预想的宽，正向测试全通过，但边界根本没设住。

二是权限要按用途分开。如果这个 key 同时用于 CCS（搜索）和 CCR（复制），要注意两者对权限的要求不完全一样。做法是搜索和复制用两个 key——用途不同、生命周期不同、审计需求也不同。

还有一点：API key 可以设过期时间。给跨集群用的 key 建议明确设过期并纳入轮换流程，别建完就忘——长期不轮换的凭据本身就是风险，而跨集群 key 通常权限范围较大，更不该一直放着。

如果暂时迁不了怎么办

现实里跨集群配置常牵扯多个团队，不是想迁就能立刻迁。这期间可以做几件事降低风险：

一，把证书模式的权限影响面摸清楚。证书模型下远端用户的权限会带过来，所以要知道"远端有哪些人、他们有什么权限"。这份清单是评估风险的基础——如果远端有很宽的权限，说明当前的跨集群边界比想象中宽。

二，在远端收紧权限。迁移之前，可以先在远端把不需要跨集群访问的用户权限收窄。这是证书模型下唯一能控制边界的手段，虽然粗，但总比什么都不做强。

三，给跨集群连接单独建模。如果条件允许，让跨集群访问走专门的账号/角色，而不是让所有人的权限都无条件带过去。

四，把迁移排进版本计划。官方已明确"未来主版本会移除"，所以问题已经只剩"什么时候做"。建议在下一个主版本升级之前完成。

第二条最值得先做：在证书模型下主动收紧远端权限，既降低当前风险，也让后续迁移时的"应授予什么权限"有参考——你现在实际用到了哪些索引，就是迁移后 API key 该声明的范围。

迁移前先收紧，能同时解决两个问题（当前风险 + 迁移时的权限依据）。

值得排进计划，但不用紧急处理

这条是 deprecation，不是 breaking。实际影响目前只有一条：弃用日志里多一条警告。

功能照常可用。官方说"将在未来主版本移除"，但没说是哪个版本——可能是 10，也可能更远。

所以建议是：

• 不要把它放进当前升级窗口（9.0 升级本身的 breaking 已经够多了）；
• 要记进待办，在下一个主版本升级前处理掉；
• 如果你们本来就在规划安全改造（比如收紧跨集群权限），那可以顺势一起做——这次迁移正好能带来权限细化。

最实际的切入点：不要为了消除警告而迁移，要为了拿到细粒度控制而迁移。前者是被动应付，后者有实际收益。

和别的"弃用"条目放一起看

9.x 的 deprecation 写过几条，它们的共同模式值得总结：

三条的共同点是：都给了明确的替代方案。

这是 ES 弃用条目的一贯做法——不会只说"这个要没了"，而会说"用这个代替"。所以读 deprecation 时，重点是"我现在该往哪个方向改"。

因为替代方案通常是更好的做法（这次的细粒度控制就是），早改早受益，不用等到非改不可。

检查清单

• 证书模式在 9.0 被标为 deprecation（changelog 第 1785–1796 行，PR 120806），当前影响只是弃用日志里一条警告，功能照常。
• 判断用哪种模式只按一条：keystore 里有没有 cluster.remote.<alias>.credentials。有 → API key 模式；没有 → 证书模式。它是安全设置，不在 elasticsearch.yml 里。
• 弃用告警在源码里的位置是 RemoteConnectionManager.maybeLogDeprecationWarning（第 125–138 行），条件是 getClusterCredentials == null 且 profile 不是 _remote_cluster。
• 告警 key 是 remote_cluster_certificate_access-<别名>，分类 SECURITY，每次建连都打——按这个 key grep 弃用日志最直接。
• 走 remote cluster server port 的连接不打这条告警，所以"配了证书却没有告警"不代表不在证书模式。
• 迁移前先盘一遍实际访问需求：先给稍宽的范围、观察越界情况、再收紧；权限收紧导致的报错通常只说"没权限"，排查很花时间。
• 验证要正向 + 反向都做：除了"该查的能查到"，要专门试一次访问未授权索引确认被拒。
• 搜索（CCS）与复制（CCR）用两个 key；给 key 设过期并纳入轮换。

写在最后

这条 deprecation 当前影响很小——只是一条弃用日志。

写它的主要理由是它的替代方案有实际价值：API key 模式能做细粒度访问控制，而证书模式只能证明身份。如果你们的跨集群连接比较随意（一个远程集群能看全部索引），这次迁移正好是个收紧的机会。

一，判断自己在用哪种模式，看 keystore 里有没有 cluster.remote.<alias>.credentials。有就是 API key 模式，没有就是证书模式。

二，当前只是弃用日志警告，不用紧急处理。但记进待办，下个主版本前处理掉。

三，迁移的收益不只是消除警告。细粒度访问控制是实打实的安全改进——如果本来就该收紧跨集群权限，这就是最好的时机。

参考

• changelog 9.0.0：Deprecate certificate based remote cluster security model（第 1786–1796 行）@ v9.4.2
• remote-clusters.md：cluster.remote.<alias>.credentials 决定使用哪种安全模型（第 50 行）@ v9.4.2
• remote-clusters.md：跨集群请求签名相关设置 @ v9.4.2
• PR 120806

• RemoteConnectionManager.java 第 110–138 行 @ v9.4.2
• RemoteClusterPortSettings.java 第 42 行 @ v9.4.2

本文对照 Elasticsearch v9.4.2 标签的 changelog、官方文档与服务端源码核对，引文逐字取自原文或源码。迁移的具体操作步骤本文未展开，需参考官方的远程集群迁移文档；示例命令未在集群上执行；“证书模式已被弃用” 的依据除 changelog 与文档外，源码里也找到了告警实现（RemoteConnectionManager 第 125–138 行）；“走 _remote_cluster profile 的连接不打这条告警” 由该方法的第二个判断条件推出，未实测；“权限收紧导致的报错只说没权限” 是按一般现象的描述，未见官方说明。