This is an automated email from the ASF dual-hosted git repository.
JiaLiangC pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ambari-website.git
The following commit(s) were added to refs/heads/main by this push:
new 9744fb3 AMBARI-26656: Document multi-cluster architecture, usage and
recovery (#44)
9744fb3 is described below
commit 9744fb34df258e0bb7cbcf69dffc83637420561c
Author: jialiang <[email protected]>
AuthorDate: Tue Sep 22 14:33:55 2026 +0800
AMBARI-26656: Document multi-cluster architecture, usage and recovery (#44)
* AMBARI-26656: Add compressed hand-drawn multi-cluster diagrams
* AMBARI-26656: Document multi-cluster architecture, usage and recovery
Add bilingual 3.1 preview guides for isolated clusters, managed HBase
dependencies, API contracts and recovery. Link the guides from navigation,
architecture, release notes and the pinned source baseline; cover localized
diagrams on desktop and mobile.
Validation: npm run test:i18n (160 passed), npm run test:deployment (7
passed), npm run typecheck, npm run build, and WEBSITE_TEST_PORT=4186 npm run
test:e2e -- --workers=2 --grep "multi-cluster|3.1 preview|3.1 guides" (6
passed). No cluster runtime tests were executed for this documentation change.
---
.../version-3.1.0.json | 4 +
.../ambari-design/ambari-architecture.md | 2 +
.../version-3.1.0/frontend/react-ui.md | 6 +
.../version-3.1.0/multi-cluster/architecture.md | 117 +++++++++++++++++
.../version-3.1.0/multi-cluster/getting-started.md | 113 ++++++++++++++++
.../multi-cluster/managed-dependencies.md | 116 +++++++++++++++++
.../version-3.1.0/multi-cluster/operations.md | 141 ++++++++++++++++++++
.../version-3.1.0/release-baseline.md | 7 +
.../version-3.1.0/release-notes.md | 6 +
.../handdrawn/multi-cluster-architecture-en.webp | Bin 0 -> 93312 bytes
.../handdrawn/multi-cluster-architecture-zh.webp | Bin 0 -> 103492 bytes
.../3.1.0/handdrawn/multi-cluster-bindings-en.webp | Bin 0 -> 105060 bytes
.../3.1.0/handdrawn/multi-cluster-bindings-zh.webp | Bin 0 -> 110404 bytes
.../img/3.1.0/handdrawn/multi-cluster-diagrams.md | 143 +++++++++++++++++++++
.../3.1.0/handdrawn/multi-cluster-recovery-en.webp | Bin 0 -> 134158 bytes
.../3.1.0/handdrawn/multi-cluster-recovery-zh.webp | Bin 0 -> 133216 bytes
tests/e2e/i18n.spec.ts | 42 +++++-
tests/i18n.test.mjs | 4 +-
.../ambari-design/ambari-architecture.md | 2 +
versioned_docs/version-3.1.0/frontend/react-ui.md | 6 +
.../version-3.1.0/multi-cluster/architecture.md | 117 +++++++++++++++++
.../version-3.1.0/multi-cluster/getting-started.md | 113 ++++++++++++++++
.../multi-cluster/managed-dependencies.md | 116 +++++++++++++++++
.../version-3.1.0/multi-cluster/operations.md | 141 ++++++++++++++++++++
versioned_docs/version-3.1.0/release-baseline.md | 7 +
versioned_docs/version-3.1.0/release-notes.md | 6 +
versioned_sidebars/version-3.1.0-sidebars.json | 11 ++
27 files changed, 1218 insertions(+), 2 deletions(-)
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0.json
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0.json
index 5060d3f..15c2cb6 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0.json
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0.json
@@ -3,6 +3,10 @@
"message": "3.1.0（预览）",
"description": "The label for the upcoming 3.1.0 documentation"
},
+ "sidebar.ambariSidebar.category.Multi-cluster Management": {
+ "message": "多集群管理",
+ "description": "The label for category 'Multi-cluster Management' in
sidebar 'ambariSidebar'"
+ },
"sidebar.ambariSidebar.category.Monitoring": {
"message": "监控系统",
"description": "The label for category 'Monitoring' in sidebar
'ambariSidebar'"
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/ambari-design/ambari-architecture.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/ambari-design/ambari-architecture.md
index bd95ad9..0bd572e 100644
---
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/ambari-design/ambari-architecture.md
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/ambari-design/ambari-architecture.md
@@ -34,6 +34,8 @@ limitations under the License.
## 请求与数据路径 {#request-and-data-paths}
+同一控制平面可以管理多个归属独立的集群。主机归属、URL 与权限边界、持久化工作流身份以及可选 HBase
共享提供方，详见[多集群架构](../multi-cluster/architecture.md)。
+
下图表示控制和请求路径，指标响应会返回采集器：
```text
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/frontend/react-ui.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/frontend/react-ui.md
index b24012a..8b8c50c 100644
---
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/frontend/react-ui.md
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/frontend/react-ui.md
@@ -35,6 +35,12 @@ Ambari 3.1 使用 `ambari-web/latest` 中的 React 应用作为主要 Web UI。
历史 Ember 应用仅用于迁移比较；本指南不将其作为 3.1 的运行路径介绍。
+## 多集群导航 {#multi-cluster-navigation}
+
+集群操作使用 React hash 路由中的 `/clusters/:clusterName/main/*`。全局 `/clusters` 与
`/services` 目录显示已授权集群和服务部署，选择一行后 URL
会明确所属集群。不同标签页保留独立上下文。旧的不带集群链接通过授权集群选择来解析，不会任意选取第一个集群。
+
+安装、草稿恢复、Admin 管理与具体 URL
参阅[创建与使用集群](../multi-cluster/getting-started.md)。[HBase
托管依赖](../multi-cluster/managed-dependencies.md)说明提供方选择与就绪条件，[运维与恢复](../multi-cluster/operations.md)说明精确请求身份与重试。
+
## 工作流覆盖范围 {#workflow-coverage}
### 安装和主机 {#installation-and-hosts}
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/architecture.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/architecture.md
new file mode 100644
index 0000000..581f08b
--- /dev/null
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/architecture.md
@@ -0,0 +1,117 @@
+---
+title: 多集群架构
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# 多集群架构 {#multi-cluster-architecture}
+
+Ambari 可以通过一台 Server 和一套元数据数据库管理多个独立集群。每个集群拥有自己的服务、主机分配、配置、请求和权限。运维人员还可以选择让新的
HBase 部署使用其他集群中的托管 HDFS 与 ZooKeeper 服务。
+
+本指南说明 [AMBARI-26656 / PR #4216](https://github.com/apache/ambari/pull/4216)
合入的实现，并于 2026-09-22 对照 trunk `fc07b5cb873dc154c48349085494e664baf6b9d1` 核查。它属于
3.1.0 **预览**文档，不构成正式版本的支持认证，详见[源码基线](../release-baseline.md)。
+
+建议先阅读[创建与使用集群](./getting-started.md)，再阅读 [HBase
托管依赖](./managed-dependencies.md)和[运维与恢复](./operations.md)。
+
+## 控制平面与集群边界 {#control-plane-and-cluster-boundaries}
+
+
+
+图中展示了两个使用本地服务依赖的独立集群。两组 Agent 都注册到同一台 Ambari Server，由 Server
向对应主机分发任务，并持久化每个请求所属的集群。共享 Server 不会合并两个 HDFS 命名空间或 ZooKeeper 集群。
+
+| 边界 | 含义 |
+| --- | --- |
+| Server 与数据库 | 共享管理可用性、升级和备份范围。多集群管理不会额外提供 Server 高可用。 |
+| 集群 | 独立的服务部署、期望配置、授权和操作范围。 |
+| 主机 | 可以已注册但未分配，也可以归属一个运行时集群；同一台主机不能同时成为两个集群的成员。 |
+| 服务 | 部署身份为 `(cluster_id, service_name)`，A 中的 HBase 与 B 中的 HBase 是不同部署。 |
+| 托管依赖 | 显式的消费方与提供方关系。提供方保留服务生命周期与数据所有权。 |
+| 远程集群注册 | 用于引用远程集群的已有独立集成，不会把另一台 Server 的主机导入当前运行时，也不构成生命周期联邦管理。 |
+
+Server 故障会影响所有集群的管理操作。服务守护进程有各自的可用性机制，不能假设 Server
故障会令所有服务停止，也不能假设所有操作仍然可用。多个集群共享 HDFS 或 ZooKeeper 提供方时，提供方故障也会影响其消费方。
+
+## 路由与权限隔离 {#route-and-authorization-isolation}
+
+运维 URL 中明确包含集群名称：
+
+```text
+/latest/#/clusters/analytics-a/main/hosts
+/latest/#/clusters/analytics-b/main/services/HBASE/summary
+/latest/#/clusters
+/latest/#/services
+
+/api/v1/clusters/analytics-a/services/HBASE
+/api/v1/clusters/analytics-b/services/HBASE
+```
+
+最后两个浏览器路由是全局授权目录。选择服务后，URL 会明确该服务所属的集群。不同标签页可以同时查看不同集群，不会把某个全局“当前集群”值作为权限依据。
+
+React 按登录用户与路由作用域划分运行时。切换集群会使旧请求、缓存、轮询和事件消费逻辑失效，避免它们更新新页面。最近使用的数字集群 ID
偏好仅用于导航，仍需经过 Server 当前授权和集群目录验证。
+
+Server 授权才是安全边界。AMBARI 作用域的授权全局生效，CLUSTER 作用域的授权仅对目标集群生效。集群管理员不因此获得 Ambari
管理权限。服务端 STOMP 授权与投影限制事件投递，请求与任务读取也检查实际归属；仅靠浏览器过滤无法保护其他集群的信息。
+
+## 持久化身份与恢复 {#persistent-identity-and-recovery}
+
+| 身份 | 用途 |
+| --- | --- |
+| 数字集群 ID | 重命名后保持稳定，兼容的 REST 路径仍使用集群名称。 |
+| 创建草稿 UUID | 标识一次安装意图、其所有者，以及由该草稿创建的确切集群。 |
+| 工作流作用域与修订号 | 隔离安装草稿与集群工作流；拒绝过期写入，避免覆盖其他会话的检查点。 |
+| 绑定 UUID | 标识一条 HDFS 或 ZooKeeper 托管关系及其私有命名空间。 |
+| 快照版本与指纹 | 标识已批准的提供方与客户端配置，以及消费方拓扑和安全输入。 |
+| 操作 ID 与 epoch | 关联一次尝试，排除先前操作遗留的过期结果。 |
+| 部署 UUID 与尝试 ID | 持久化安装、启动和检查流程，不依赖浏览器会话存活。 |
+| 请求、任务与主机 ID | 将执行结果关联到精确的调度任务和经过授权的主机。 |
+
+创建时提交
`creation_draft_id`。创建响应丢失后，恢复逻辑检查已保存的草稿与集群关联；仅有相同集群名称，不足以证明它由当前草稿创建。创建过程不会删除已有集群或共享仓库定义。
+
+数据库强制主机独占归属。升级路径检测到历史重复归属时，会停止并要求明确修复，不会静默选择所有者。应先备份并解决归属歧义，再重试升级。
+
+## 共享服务但不转移所有权 {#shared-services-without-shared-ownership}
+
+托管 HBase 部署可以分别选择 HDFS 存储提供方与 ZooKeeper
协调提供方。每条绑定都持久化提供方的数字身份、经过审核的配置快照、私有命名空间及操作历史。
+
+提供方设置通过允许列表进入 HBase 专用的客户端配置覆盖层。消费集群保留自己的 Hadoop
配置，不会接收提供方的管理凭据。客户端安装、凭据处理和连通性检查都针对精确的当前计划执行。
+
+绑定就绪与部署完成是不同状态。Server 协调提供方准备、消费方安装、依赖校验、HBase
启动与服务检查。刷新时读取同一个部署，不重新发起替代任务，详见[绑定与就绪流程](./managed-dependencies.md#deployment-sequence)。
+
+## 实现位置 {#implementation-map}
+
+| 层次 | 源码与职责 |
+| --- | --- |
+| 浏览器导航 | [React
路由](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/router/RoutesList.tsx)和[集群目录](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/screens/Directories/ClusterDirectory.tsx)：明确集群上下文、授权发现和草稿恢复。
|
+| 管理界面 | [Admin
路由](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-admin/src/main/resources/ui/ambari-admin/src/router/RoutesList.tsx)：集群概览、主机资源、权限与仓库导航。
|
+| 主机归属 |
[主机归属升级](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/upgrade/HostMembershipSchemaUpgrade.java)：独占归属与迁移检查。
|
+| 依赖批准 |
[托管服务协调器](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedServiceDependencyCoordinator.java)：授权、预览、快照、绑定变更与操作关联。
|
+| 部署恢复 |
[部署协调器](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyDeploymentCoordinator.java)：持久化安装、就绪、启动和服务检查进度。
|
+| 启动与生命周期门禁 |
[就绪策略](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyReadinessPolicy.java)和[生命周期策略](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyLifecyclePolicy.java)：当前证据、影响确认与删除保护。
|
+| Agent 侧执行 | [托管 HBase
脚本](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/resources/stacks/BIGTOP/3.2.0/services/HBASE/package/scripts/managed_hbase_dependency.py)：结构化观测、私有客户端配置和校验。
|
+
+脚本继承来源目录含有 `BIGTOP/3.2.0`，这个目录名不代表托管依赖的兼容性约定。当前校验器要求使用已激活的 BIGTOP 3.3.0
仓库，并且解析后的版本元数据匹配。
+
+## 验证证据与待验收范围 {#evidence-and-remaining-qualification}
+
+历史[实现与运行记录](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/docs/design/multi-cluster-review-and-remediation.md)区分了以下检查点：
+
+| 场景 | 已记录证据 | 局限 |
+| --- | --- | --- |
+| 两个独立集群，各自使用本地 HBase 依赖 | 源码 `1ab17a10ea333e35d9952666d57d8f4383762103`
的六主机原生 RPM 部署，验证了不同 HBase 身份、服务检查、跨用户访问拒绝与重复主机归属拒绝。 | 属于历史源码与包验收，并非重新部署当前
trunk。 |
+| 跨集群托管 HBase | 一个部署完成，两条绑定就绪，并通过 SDK Put/Get 服务检查。 | 使用了较早 RPM
加已记录的文件与类覆盖补丁，不能描述为最终无覆盖补丁的包验收。 |
+| Admin 工作流 | 已记录概览、主机归属、草稿恢复、授权、重命名与删除的浏览器及 API 检查。 | 并未穷尽所有角色、代理和浏览器组合。 |
+| 其他故障与安全场景 | 存在实现及聚焦回归覆盖。 | 真实 KDC
回调、托管提供方停止与删除、解绑保留数据、全部崩溃与丢响应边界、完整消息代理撤权矩阵仍需验收。 |
+
+网站构建与浏览器测试验证的是这些文档和图片，不构成集群运行验收。
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/getting-started.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/getting-started.md
new file mode 100644
index 0000000..832cd8a
--- /dev/null
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/getting-started.md
@@ -0,0 +1,113 @@
+---
+title: 创建与使用集群
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# 创建与使用集群 {#creating-and-using-clusters}
+
+本流程用于在同一台 Ambari Server
下管理两个独立集群。架构和版本边界请参阅[多集群架构](./architecture.md)。共享提供方是可选能力，另见 [HBase
托管依赖](./managed-dependencies.md)。
+
+## 开始前准备 {#before-you-start}
+
+使用包含多集群实现且相互匹配的 Server、Agent、Web 和 Admin
制品。完成常规[安装准备](../quick-start/installation-guide.md)，包括 DNS、网络连通性、仓库和 Agent
注册。已有安装必须遵循[升级流程](../upgrade-guide.md)，本指南不能替代数据库迁移。
+
+| 要求 | 检查内容 |
+| --- | --- |
+| 创建权限 | 账号拥有 `AMBARI.ADD_DELETE_CLUSTERS`。仅有集群管理权限不代表拥有全局创建权限。 |
+| 主机目录 | 新主机已注册到当前 Server 且尚未分配。安装前查看 Admin 的主机资源页面。 |
+| 仓库定义 | 选择的 Stack 与仓库适用于目标主机。相同设置可复用，共享定义冲突需明确处理。 |
+| 唯一目标 | 选择新的集群名称，并启动全新的安装草稿。 |
+| 容量 | 按总负载规划共享 Server、数据库与各服务部署容量；此处不承诺固定的集群数量上限。 |
+
+一个六主机示例：
+
+| 集群 | 主机 | 本地服务 |
+| --- | --- | --- |
+| analytics-a | worker1、worker2、worker3 | HDFS、ZooKeeper 与 HBase |
+| analytics-b | worker4、worker5、worker6 | HDFS、ZooKeeper 与 HBase |
+
+这只是拓扑示例，不是生产容量建议。主机名无需与示例一致，关键是两组主机不能重叠。
+
+## 创建首个或后续集群 {#create-the-first-or-next-cluster}
+
+1. 从主 React 入口登录。打开 **Clusters（集群）**，或在拥有权限时使用集群菜单中的 **Admin Cluster
Management（集群管理）**。
+2. 在 Admin 中打开 **Create Cluster（创建集群）**，选择 **Start installation
wizard（启动安装向导）**。全局集群目录也为具备权限的用户提供创建入口。
+3. 输入新集群名称。向导 URL 含有草稿标识，安装中断时应保留该 URL。
+4. 选择 Stack 与版本，检查仓库 URL。仅注册或选择尚未分配给其他集群的主机。
+5. 选择服务。如果需要独立的 HBase 部署，保留本地 HDFS 与 ZooKeeper 选项，不要仅因存在其他集群就选择托管提供方。
+6. 检查组件放置和配置。确认每个主机名都属于预期目标，创建第二个集群时尤其需要检查。
+7. 提交审核页，跟踪安装与启动进度，重试前检查失败的请求和任务。
+8. 完成向导后，打开该集群的主机与服务页面，核对真实目录和组件状态，并执行所选服务适用的服务检查。
+
+创建下一个集群时，从**新草稿**重新开始，不要复用第一个集群保存的安装 URL。已有集群和共享仓库记录会被保留。
+
+名称冲突意味着校验失败，不代表可以覆盖或接管已有集群。应选择其他名称；如果实际目标就是已有集群，则通过经过授权的入口打开它。
+
+## 恢复中断的安装 {#resume-an-interrupted-installation}
+
+使用原账号打开 **Clusters（集群）** 或 Admin 的 **Create Cluster（创建集群）**。已保存安装会显示目标、阶段和安装
ID，选择原草稿对应的恢复或继续操作。
+
+编辑前等待工作流加载已保存的修订版本。密码、私钥等敏感字段不会保留在持久化检查点中，可能需要重新输入。敏感信息缺失会阻止受影响的操作，但非敏感输入可以继续保留。
+
+如果创建或主机分配响应丢失，应由向导对照原草稿和已记录的分配意图进行核对，不要再创建一个同名集群来“修复”不确定状态。修订冲突需要先重新加载当前检查点，再重试编辑，详见[恢复场景](./operations.md#recovery-cases)。
+
+离开或刷新页面不代表 Server 工作已取消。重新连接后，应检查保存的工作流及对应请求 ID。
+
+## 切换与比较集群 {#switch-and-compare-safely}
+
+| 任务 | 入口 |
+| --- | --- |
+| 浏览已授权集群 | `/latest/#/clusters` |
+| 比较不同服务部署 | `/latest/#/services` |
+| 打开 A 的主机列表 | `/latest/#/clusters/analytics-a/main/hosts` |
+| 打开 B 的 HBase 配置 |
`/latest/#/clusters/analytics-b/main/services/HBASE/configs` |
+| 查看 B 的操作 | `/latest/#/clusters/analytics-b/main/requests` |
+
+这些路径假定使用标准部署根路径；存在反向代理前缀时需保留该前缀。集群名称应编码为单个 URL 路径片段，不要直接拼接未经转义的名称。
+
+目录将搜索、排序和分页保留在 URL 中。服务目录同时标明服务和所属集群，并显示 HBase
依赖摘要。某个集群加载失败时，不会用其他集群的行冒充其结果，应针对失败范围重试。
+
+登录后，Ambari 重新验证已有的授权跳转目标或用户最近使用的数字集群 ID
偏好。仅有一个授权集群时可以自动选择，否则由界面提示选择。旧的不带集群的链接会在选择过程中保留目标页面。目标已删除或无权访问时，不应静默切换到另一集群。
+
+## Admin 管理任务 {#admin-tasks}
+
+| 页面 | 用途 |
+| --- | --- |
+| Cluster Overview（集群概览） | 查找托管集群，打开目标集群或其详情。 |
+| Cluster Details（集群详情） | 查看基本信息、服务与主机、访问权限、操作历史、配置与导出。 |
+| Host Resources（主机资源） | 区分已分配与未分配主机，打开目标集群已有的添加主机向导。 |
+| Cluster Permissions（集群权限） | 为明确的目标集群授予或移除权限，并重新读取授权结果。 |
+| Versions & Repositories（版本与仓库） | 检查全局仓库目录与所选集群的版本状态。 |
+| Remote Clusters（远程集群） | 维护远程引用，不会创建另一个由本机管理的运行时集群。 |
+
+重命名保留数字身份。删除属于独立的受保护操作：检查服务状态和依赖影响，停止必要组件，再通过经过授权的删除流程操作。界面行消失或请求已受理，都不能证明删除已经完成。
+
+## 检查结果 {#check-the-result}
+
+1. 在每个集群的主机页面确认主机集合符合预期，且归属互不重叠。
+2. 在不同标签页分别打开两个集群的 HBase，核对所属集群、生效的存储与协调配置以及服务检查结果。
+3. 使用仅有某个集群权限的账号，验证只能访问预期目录和操作。全局管理员不适合作为隔离测试账号。
+4. 刷新含有明确集群的 URL，确认仍加载原目标；未完成工作流应从原检查点恢复。
+5. 检查本次发起操作所对应的请求和任务状态，不要使用最近某个无关成功任务作为完成证据。
+
+脚本检查可参考[只读 API
示例](./operations.md#read-only-api-examples)。真实拓扑与角色验收需要在部署环境执行，网站示例本身不会运行这些检查。
+
+## 源码参考 {#source-references}
+
+流程依据为 [Admin
创建集群页面](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-admin/src/main/resources/ui/ambari-admin/src/screens/ClusterManagement/ClusterCreate.tsx)、[集群目录](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/screens/Directories/ClusterDirectory.tsx)、[服务目录](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/screens/Directories/ServiceDirectory.
[...]
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/managed-dependencies.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/managed-dependencies.md
new file mode 100644
index 0000000..6a97321
--- /dev/null
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/managed-dependencies.md
@@ -0,0 +1,116 @@
+---
+title: HBase 托管依赖
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# HBase 托管依赖 {#managed-hbase-dependencies}
+
+托管依赖允许新的 HBase 服务使用已有托管 HDFS 服务和／或 ZooKeeper
集群，同时保留独立的消费集群、主机和生命周期。这是可选能力，独立集群仍可使用各自本地的 HDFS 与 ZooKeeper。
+
+规划共享部署前，请阅读[架构与验证边界](./architecture.md)。当前消费方为 HBase，实现的依赖类型为 `HDFS` 和
`ZOOKEEPER`；这不是通用服务联邦，也不支持任意外部端点。
+
+## 拓扑与所有权 {#topology-and-ownership}
+
+
+
+图中刻意将 HDFS 与 ZooKeeper
放在不同的提供集群中，它们也可以位于同一个提供集群。每项选择都有独立绑定和就绪检查，执行部署前应审核完整计划。消费方主机始终属于消费集群。
+
+| 选择 | 效果 |
+| --- | --- |
+| 本地 HDFS 与 ZooKeeper | 常规独立 HBase 部署，不需要跨集群托管绑定。 |
+| 托管 HDFS、本地 ZooKeeper | HBase 使用所选提供方存储，协调仍在本地。 |
+| 本地 HDFS、托管 ZooKeeper | 存储保留在本地，协调使用所选提供方。 |
+| 托管 HDFS 与 ZooKeeper | 两条绑定，各有提供方身份、私有命名空间和就绪证据。 |
+
+Ambari 协调批准、准备与校验。HBase 直接连接提供方守护进程执行存储与协调，数据不经过 Ambari
Server。共享提供方也意味着共享其可用性与维护依赖。
+
+## 兼容性与权限 {#compatibility-and-permissions}
+
+| 检查项 | 当前约定 |
+| --- | --- |
+| 消费方生命周期 | 草稿、新服务计划或处于初始状态的新 HBase 服务。不支持转换已有数据的本地 HBase 部署。 |
+| Stack 与版本 | 消费方和提供方均使用已激活的 BIGTOP 3.3.0
仓库，解析后的版本元数据非空且相等，并具备兼容的客户端特性。仅显示版本相同并不充分。 |
+| 提供方就绪 | 快照批准前，所选服务必须已安装且健康。 |
+| HDFS 特性 | 托管绑定校验器拒绝 Federation 和 Observer NameNode 客户端。不能因 Ambari
其他功能支持它们，就推断此处也支持。 |
+| 安全模式 | 双方均非安全模式，或满足专用的同 realm Kerberos 检查。混合安全与非安全模式以及跨 realm 绑定均被拒绝。 |
+| 网络 | 每台当前 HBase 守护进程主机均可解析并访问配置中的 NameNode RPC、DataNode 数据传输及 ZooKeeper
端点。以真实提供方配置为准，不要假定默认端口。 |
+| 消费方权限 | 修改与身份规划需要 `SERVICE.MODIFY_CONFIGS` 和
`SERVICE.SET_SERVICE_USERS_GROUPS`；添加服务还需要 `SERVICE.ADD_DELETE_SERVICES`。 |
+| 提供方权限 | 发现需要服务查看授权；准备与变更需要提供集群上的
`SERVICE.RUN_CUSTOM_COMMAND`。仅有消费集群管理权限并不足够。 |
+
+安装草稿需要全局创建集群权限。安装、启动和服务检查仍保留常规操作权限要求；表中列出的是依赖相关前提，不是完整角色授权配方。
+
+初始安全路径是在**已经启用 Kerberos 的消费集群**中添加 HBase。新建集群安装不会自动建立可用的安全依赖计划。同 realm
支持包含身份映射、提供方策略证明、凭据签发与校验；存在实现不代表真实 KDC 验收已经完成。
+
+## 选择并审核提供方 {#choose-and-review-providers}
+
+1. 启动新集群安装，或在目标消费集群中打开 **Add Service（添加服务）** 并选择 HBase。
+2. 在服务选择步骤中，分别检查 **Storage（存储）** 与 **ZooKeeper** 选项。需要保留本地的依赖应维持本地默认值。
+3. 对于托管依赖，打开授权提供方列表，选择前核对提供集群、服务、兼容性结果和返回的原因。
+4. 保存选择并预览计划。向导可以取消仅用于满足 HBase
依赖而自动选中的本地守护进程服务，但会保留用户明确选择或其他本地消费方需要的服务。客户端包仍然必需。
+5. 在配置步骤检查托管客户端值，按需编辑普通 HBase 属性。提供方管理的值应通过选择与审核提供方来变更，不要复制完整提供方配置。
+6. 在审核步骤确认消费方身份、提供方归属、私有路径、主机放置和当前兼容性结果。提供方或拓扑变化会使旧预览失效。
+7. 提交审核后的计划，跟踪服务端拥有的部署。在依赖准备或校验未完成前，不要手动启动 HBase。
+
+在已有 HBase 旁添加其他服务，会保留其依赖归属，不会提供迁移入口。不支持的选择应在执行部署前解决。
+
+## 私有配置与数据路径 {#private-configuration-and-data-paths}
+
+Server 根据每条绑定的 UUID 派生私有路径：
+
+```text
+HDFS binding:
+ hdfs://<provider-authority>/apps/ambari-managed/hbase/<hdfs-binding-id>/root
+ hdfs://<provider-authority>/apps/ambari-managed/hbase/<hdfs-binding-id>/wal
+
+ZooKeeper binding:
+ /ambari-managed-hbase/<zk-binding-id>/hbase
+```
+
+HDFS 与 ZooKeeper 的绑定 ID 相互独立。root 与 WAL 路径分离，ZooKeeper 绑定拥有私有容器和协调子节点。Ambari
还维护所有权与 fencing 记录，不要手动删除这些记录，或将保留路径用于其他应用。
+
+只有允许列表中的客户端设置进入批准快照。HBase 配置覆盖层不会覆写无关本地服务的 Hadoop 配置，提供方的管理 principal 与 keytab
也不会复制给消费方。应读取返回的命名空间和计划身份，不要自行猜测 HBase 用户或路径规则。
+
+## 部署顺序 {#deployment-sequence}
+
+
+
+| 阶段 | 必须建立的事实 |
+| --- | --- |
+| 保存与预览 | 精确的草稿或服务计划修订号、所选提供方和当前指纹。 |
+| 批准与准备 | 持久化绑定快照，提供方针对精确命名空间与身份完成准备。 |
+| 安装与配置 | 在预期消费主机上安装已批准的客户端和私有配置，并持久化请求与任务关联。 |
+| 凭据与校验 | 需要时完成凭据处理，检查 NameNode RPC、DataNode 写读、ZooKeeper 会话与私有
znode，以及当前客户端与身份的证据。 |
+| 就绪与启动 | 全部托管绑定就绪，并且**每台当前 HBase 守护进程主机**的证据有效。 |
+| 服务检查与完成 | 将精确的启动和服务检查请求、任务结果关联到同一个持久化部署。 |
+
+某条绑定处于 `READY` 不代表部署已完成。应检查部署的 `completed` 字段、当前请求和任务结果以及操作身份。`INSTALL_ONLY`
是明确的流程分支，不等于 `COMPLETE`。
+
+## 更新、维护与解绑 {#updates-maintenance-and-detach}
+
+打开 HBase 的 **Dependencies（依赖）**
页签，或使用服务目录中的依赖链接。页面显示归属、阶段、期望与已应用快照版本、就绪情况和允许的后续动作。
+
+提供方配置变化时，使用 **Review changes（审核变更）**，检查候选快照，并在允许时应用审核后的变更。并发冲突需要重新预览。**Retry
preparation（重试准备）** 通过受支持的操作重试当前绑定，不能复用无关任务结果。
+
+停止或重启提供方前，应查看依赖它的消费方，并确认当前影响修订号。没有查看权限的消费方可能仅显示匿名数量，因此可见名称列表为空不代表没有影响。存在活动绑定时，提供方删除会被阻止。
+
+执行 **Detach provider（解绑提供方）** 前先停止 HBase。解绑保留提供方服务和存储数据，已解绑依赖不能继续用于重启
HBase。解绑不是数据迁移或数据擦除命令，应明确规划消费方退役、数据保留和后续清理；真实解绑与数据保留验收仍属于待确认范围。
+
+## 源码参考 {#source-references}
+
+参阅[快照校验器](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencySnapshotValidator.java)、[命名空间分配](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyNamespace.java)、[依赖
API
客户端](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6
[...]
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/operations.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/operations.md
new file mode 100644
index 0000000..c16704d
--- /dev/null
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/multi-cluster/operations.md
@@ -0,0 +1,141 @@
+---
+title: 运维与恢复
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# 运维与恢复 {#operations-and-recovery}
+
+操作必须针对明确的集群和精确保存的操作身份。HTTP 提交成功、进程退出码为零、某条日志或无关请求完成，都不能证明目标工作流已经结束。应使用 Server
的结构化状态与标识。
+
+本手册补充[集群创建](./getting-started.md)和 [HBase
托管依赖](./managed-dependencies.md)。[架构指南](./architecture.md#evidence-and-remaining-qualification)区分了历史运行证据与尚待完成的验收。
+
+## 只读 API 示例 {#read-only-api-examples}
+
+以下是供已认证 API 客户端使用的 HTTP
请求目标。将示例集群名和标识占位符替换为本次操作返回的值，并保留部署环境的认证与代理设置。不要将凭据写入脚本或共享诊断输出。
+
+```http
+GET
/api/v1/clusters?fields=Clusters/cluster_id,Clusters/cluster_name,Clusters/provisioning_state
+GET /api/v1/clusters/analytics-a/hosts?fields=Hosts/host_name
+GET /api/v1/clusters/analytics-a/services/HBASE/dependencies
+GET /api/v1/clusters/analytics-a/services/HBASE/dependencies/{bindingId}
+GET
/api/v1/clusters/analytics-a/services/HBASE/dependencies/deployments/{deploymentId}
+GET /api/v1/clusters/analytics-a/requests/{requestId}
+GET /api/v1/clusters/analytics-a/requests/{requestId}/tasks
+```
+
+| 观测对象 | 读取与验证 |
+| --- | --- |
+| 集群目录 | `Clusters.cluster_id` 与 `Clusters.cluster_name`；名称变化时数字身份必须保持不变。 |
+| 绑定列表 | `items`；归属可能为 `managed`、`local`、`unmanaged` 或
`unknown`。缺少托管绑定不代表本地依赖健康。 |
+| 绑定详情 |
`binding_id`、`consumer`、`provider`、`phase`、`row_version`、`operation_epoch`、期望与已应用快照版本和操作身份。
|
+| 绑定就绪 | `readiness` 标识必需、已准备及已验证的守护进程主机；`capabilities`、`allowed_actions` 与
`next_action` 说明允许的后续步骤。 |
+| 部署 |
`deployment_id`、`cluster_id`、`attempt_id`、`request_id`、`history`、`state`、`phase`、`failure_code`、`retry_allowed`、`completed`
与 `install_only`。 |
+| 任务完成 | 读取精确请求的任务及所属集群，确认任务、主机和操作的关联及终态结果，不要搜索全部近期请求来猜测。 |
+
+结构化依赖错误包含 `code` 与 `message`。应按 HTTP
状态和精确错误码处理分支，消息文本只用于诊断。字段缺失、值格式错误或身份属于其他操作时，必须保留错误或未解决状态。
+
+## 集成方变更契约 {#mutation-contract-for-integrators}
+
+常规管理优先使用界面。自动化请以固定版本的 [API
客户端](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/api/serviceDependenciesApi.ts)和
[REST
服务](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/api/services/ManagedServiceDependencyService.java)作为请求体契约。
+
+表中的 `D` 表示 `/api/v1/clusters/{clusterName}/services/HBASE/dependencies`。
+
+| 方法与资源 | 契约 |
+| --- | --- |
+| `GET D/candidates?type=HDFS` | 为已有 HBase 消费方发现已授权候选提供方；ZooKeeper 使用其对应依赖类型。 |
+| `POST D/preview` | 预览单个或完整选择集，不表示批准或开始准备。 |
+| `POST D` | 使用操作 UUID，批准精确的绑定 ID、提供方身份、预览 schema 版本与返回的指纹；支持包含一项或两项的集合。 |
+| `POST D/deployments/{deploymentId}` | 在不可变部署 UUID 下持久化或启动精确目标，并明确是否仅安装。 |
+| `POST D/deployments/{deploymentId}/actions/retry` | 仅在返回能力允许时，使用操作 UUID
重试该部署。 |
+| `GET D/{bindingId}/preview-update` | 批准提供方配置变化前，读取最新更新提案。 |
+| `POST D/{bindingId}/actions/update` | 随操作 UUID 提交最新预览中的行版本、快照版本、指纹、批准值和
schema 版本。 |
+| `POST D/{bindingId}/actions/retry` | 提交操作 UUID 与期望的当前行版本。 |
+| `POST D/{bindingId}/actions/verify-credentials` | 在工作流允许手动凭据处理时，针对预期的当前
epoch 校验凭据。 |
+| `DELETE D/{bindingId}` | 满足生命周期门禁后，使用操作 UUID 和期望行版本解绑，不擦除提供方数据。 |
+
+草稿和添加服务的发现入口为 `/api/v1/service-dependencies/candidates` 与
`/api/v1/service-dependencies/preview`，需要对应的草稿或服务计划作用域与期望修订号。不要仅为发现提供方而创建一个虚假的
HBase 服务。
+
+提供方侧读取使用 `/api/v1/clusters/{clusterName}/services/{serviceName}/dependents` 和
`/api/v1/clusters/{clusterName}/services/{serviceName}/dependency-impact`。停止或重启确认与当前影响修订号及精确提供方、动作绑定。其他消费方变化后应重新读取影响。
+
+提交前持久化启动和重试 ID。超时后先读取原资源，再决定是否重试；同一次尝试应保留不可变的重试身份。已确认存在的部署随后返回 404 时，不能发起替代部署。
+
+## 绑定阶段 {#binding-phases}
+
+| 阶段 | 运维含义 |
+| --- | --- |
+| `PREVIEWED` | 绑定尚未建立提供方准备证据。 |
+| `PROVIDER_PREPARING` | 提供方正在执行工作，应检查对应请求。 |
+| `PROVIDER_PREPARED` | 提供方准备已具备，消费方安装和校验仍有门禁。 |
+| `ZOOKEEPER_HANDOFF_RECONCILING` | 执行专用的 ZooKeeper 交接核对流程，不能视为就绪。 |
+| `CONSUMER_VERIFYING` | 正在收集当前客户端、身份与连通性证据。 |
+| `READY` | 当前批准输入对应的绑定就绪已建立，部署完成仍需单独观测。 |
+| `STALE` | 批准输入或证据不再匹配当前提供方或消费方状态，应审核变更。 |
+| `FAILED` | 检查失败详情及允许的重试动作。 |
+| `FENCING_UNCERTAIN` | 无法可靠确认现有操作所有权，进一步变更前应调查。 |
+| `DETACHING`、`RETIRED`、`DETACHED`、`TOMBSTONED` |
退役与解绑生命周期阶段，均不代表自动删除数据，也不授予重启旧依赖的权限。 |
+
+应结合阶段与返回能力判断。阶段名称本身不能替代拓扑、快照、身份和权限检查。
+
+## 恢复场景 {#recovery-cases}
+
+| 现象或精确错误码 | 检查对象 | 恢复方式 |
+| --- | --- | --- |
+| 安装刷新或创建响应丢失 | 原草稿 UUID、所有者、修订号与已保存的集群关联。 |
恢复原草稿，重新输入要求的敏感信息；没有关联证明时，不接管同名集群。 |
+| 工作流修订冲突 | 最新保存的作用域、修订号及其他活动编辑者。 | 重新加载权威检查点，审核差异，再提交当前修改。 |
+| `DEPENDENCY_OPERATION_STALE` | 当前操作、行版本、快照与 epoch。 |
重新加载，输入变化时重新预览，不将旧批准重放到新状态。 |
+| `DEPENDENCY_VERSION_UNSUPPORTED` | 双方活动仓库记录与解析后的版本元数据。 |
选择兼容提供方或修正仓库，不绕过校验器。 |
+| `DEPENDENCY_SECURITY_MISMATCH` 或 `CROSS_REALM_NOT_SUPPORTED` | 双方安全模式与
realm。 | 使用受支持拓扑，不复制提供方 keytab 来绕过不匹配。 |
+| `DEPENDENCY_CONSUMER_NOT_READY` | 每台必需守护进程主机的包、配置、凭据与校验证据。 |
修复失败前提，再使用界面提供的准备或校验动作。 |
+| `DEPENDENCY_NAMENODE_RPC_FAILED` 或 `DEPENDENCY_DATANODE_READ_WRITE_FAILED` |
配置端点、网络、身份及精确结构化探测结果。 | 修正报告的问题，再对受影响的当前计划重新校验。 |
+| `DEPENDENCY_ZOOKEEPER_SESSION_FAILED` 或
`DEPENDENCY_ZOOKEEPER_AUTHORIZATION_FAILED` | ZooKeeper 连通性、客户端身份与私有 znode 策略。
| 修正连通性或授权，再按受支持路径校验。 |
+| `DEPENDENCY_FENCING_UNCERTAIN` | 持久化操作与提供方所有权记录。 |
保留不确定状态并调查，不删除日志记录来强行标记成功。 |
+| 部署 `UNRESOLVED` | 精确部署历史及缺失或不匹配的请求、任务关联。 | 保留证据并调查，仅在 Server 明确允许时重试。 |
+| 提供方停止或删除受阻 | 当前消费方与影响，以及消费方停止和解绑要求。 | 协调维护，审核当前影响，或通过受支持流程退役、解绑消费方。 |
+| 某个集群目录数据加载失败 | 该集群授权及失败的读取。 | 针对该范围重试，保留其他成功加载的授权行。 |
+
+按场景记录精确的集群、草稿、绑定、部署、操作、epoch、请求和任务
ID，并附脱敏结构化响应。日志可用于解释失败，但不能作为工作流成功依据。问题报告中不得包含凭据或原始 keytab。
+
+## Blueprint 交接 {#blueprint-handoff}
+
+托管 Blueprint 通过设置声明需要的依赖类型：
+
+```json
+{
+ "settings": [
+ {
+ "managed_dependencies": [
+ {"consumer_service": "HBASE", "dependency_type": "HDFS"},
+ {"consumer_service": "HBASE", "dependency_type": "ZOOKEEPER"}
+ ]
+ }
+ ]
+}
+```
+
+使用 `provision_action: PREPARE_ONLY`，等待真实主机放置和拓扑配置完成，然后预览完整 HBase
选择，应用审核后的配置，批准精确绑定指纹，并以精确目标启动持久化部署。提供方 ID 和凭据不应放入可复用模板。常规本地 Blueprint 路径保留默认动作。
+
+这说明的是交接契约，不是完整部署请求体。实现集成时应同时参考 [Blueprint
实现](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyBlueprintPlan.java)和[通用
Blueprint 指南](../ambari-design/blueprints/index.md)。
+
+## 升级与验收工作 {#upgrade-and-acceptance-work}
+
+升级前备份共享数据库和 Server 配置，验证主机独占归属以及作用域工作流和依赖表迁移。未确认正确所有者之前，不要通过删除归属行来“修复”重复记录。
+
+在依赖生产部署之前，应验证双集群主机与权限隔离、双标签页导航、精确草稿恢复、逐主机托管就绪，以及实际需要的提供方维护路径。安全安装还需真实 KDC
与凭据测试。网络中断和 Server 重启演练应始终使用已保存的操作 ID。
+
+正式发布前仍需补充最终制品与 tag 矩阵、受支持的升级与数据库组合、真实 KDC
结果、托管解绑与数据保留证据，以及故障注入和消息代理撤权结果。只有对应测试实际执行后才能补充结论，历史源码审查不能替代这些证据。
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-baseline.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-baseline.md
index 9b535b7..df7677f 100644
---
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-baseline.md
+++
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-baseline.md
@@ -26,6 +26,7 @@ limitations under the License.
| 上一版本源代码标签 | `release-3.0.0`, `3acb048b3f6e209d6d1e5ac54efcbd30f1b25c57` |
| 2026-09-07 审查的社区 trunk | `94c6389a96b38bccef0b6a08269481a086b63ca1` |
| 监控目标基线，PR #4182 | `4e95d2e33493ac934d7d98a14a81d86c0f1bc0c4` |
+| 2026-09-22 多集群专题核查 | `fc07b5cb873dc154c48349085494e664baf6b9d1`，包含
AMBARI-26656 / PR #4216 |
| 审查 trunk 中的 Maven 开发版本 | `3.1.0.0-SNAPSHOT` |
对于本文档，PR #4182 包含在预期的 3.1.0 功能基线中。发布候选版本必须同时包含选定的社区更改和监控实现；表中的参考 SHA
不是要求用旧功能分支替换较新的社区工作。
@@ -66,6 +67,12 @@ React 对等基线区分实现、静态比较和运行时验证。较早的审
文档构建和浏览器检查会验证本网站的路由、翻译、标签和资源，但不会执行 Ambari 集群升级、Maven/RPM 生产构建或监控故障演练。
+## 多集群专题补充 {#multi-cluster-follow-up}
+
+[多集群指南](./multi-cluster/architecture.md)使用上表中较新的固定 trunk
版本，核查集群隔离、持久化向导恢复、Admin 管理与 HBase 托管依赖。这是聚焦源码补充，不是重新执行原有整版审查或新的 RPM 验收。
+
+指南区分最终独立集群包验收与早期带覆盖补丁的托管 HBase 部署证据，并说明真实
KDC、解绑与数据保留、故障注入及消息代理撤权等剩余门禁。[运维指南](./multi-cluster/operations.md#upgrade-and-acceptance-work)列出了发布最终支持声明前仍需补齐的证据。
+
## 发布版本前 {#before-publishing-a-release}
选定发布候选版本后更新此基线。记录最终源代码标签、签名构件/校验和位置、软件包目标矩阵、支持的升级路径、测试结果和发布投票结果。完成这些工作后，才能将预览标记替换为已发布版本。
diff --git
a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-notes.md
b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-notes.md
index a649e52..166010a 100644
--- a/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-notes.md
+++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/version-3.1.0/release-notes.md
@@ -47,6 +47,12 @@ Ambari Web 默认进入 React 应用。当前实现承接了集群安装、主
默认入口和打包变更：[#4198](https://github.com/apache/ambari/pull/4198)。工作流覆盖范围及验收边界见
[React 用户指南](./frontend/react-ui.md)。
+### 隔离的多集群管理 {#multi-cluster-management}
+
+一台 Ambari Server 可以管理多个独立集群，提供主机独占归属、明确的集群 URL、作用域权限与可恢复安装草稿。全局集群和服务目录以及 Admin
主机目录使归属清晰可见。新的 HBase 部署还可以选择托管 HDFS 与 ZooKeeper 提供方，通过批准快照、私有命名空间和持久化就绪检查建立依赖。
+
+实现来源：[AMBARI-26656 /
#4216](https://github.com/apache/ambari/pull/4216)。参阅[架构](./multi-cluster/architecture.md)、[使用指南](./multi-cluster/getting-started.md)、[HBase
兼容性限制](./multi-cluster/managed-dependencies.md)和[恢复手册](./multi-cluster/operations.md)。独立集群与共享提供方的证据具有不同验收边界，两者都不额外提供
Server 高可用。
+
### Java 基线升级，Ambari 与 Stack 独立选择 JDK {#java-baseline}
源码构建要求 **JDK 17 和 Maven 3.9.x**，由 Maven 强制检查。共享依赖管理更新了 Spring/Spring
Security、Jetty、Jersey、Guice、日志、持久化和 Jakarta API 等基础组件。自定义 Java
扩展及其传递依赖也需要核对兼容性，不能只替换 JDK 就认为迁移完成。
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-architecture-en.webp
b/static/img/3.1.0/handdrawn/multi-cluster-architecture-en.webp
new file mode 100644
index 0000000..bab77d6
Binary files /dev/null and
b/static/img/3.1.0/handdrawn/multi-cluster-architecture-en.webp differ
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-architecture-zh.webp
b/static/img/3.1.0/handdrawn/multi-cluster-architecture-zh.webp
new file mode 100644
index 0000000..9f3d0d1
Binary files /dev/null and
b/static/img/3.1.0/handdrawn/multi-cluster-architecture-zh.webp differ
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-bindings-en.webp
b/static/img/3.1.0/handdrawn/multi-cluster-bindings-en.webp
new file mode 100644
index 0000000..6b4a9a0
Binary files /dev/null and
b/static/img/3.1.0/handdrawn/multi-cluster-bindings-en.webp differ
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-bindings-zh.webp
b/static/img/3.1.0/handdrawn/multi-cluster-bindings-zh.webp
new file mode 100644
index 0000000..6f2be85
Binary files /dev/null and
b/static/img/3.1.0/handdrawn/multi-cluster-bindings-zh.webp differ
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-diagrams.md
b/static/img/3.1.0/handdrawn/multi-cluster-diagrams.md
new file mode 100644
index 0000000..c994105
--- /dev/null
+++ b/static/img/3.1.0/handdrawn/multi-cluster-diagrams.md
@@ -0,0 +1,143 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Multi-cluster diagram sources
+
+These six WebP illustrations accompany the bilingual 3.1.0 preview guides.
+They depict source revision fc07b5cb873dc154c48349085494e664baf6b9d1, reviewed
+on 2026-09-22. They are conceptual diagrams, not runtime screenshots.
+
+## Generation and delivery
+
+- Model: gpt-image-2, image-edit API with the existing overall architecture
+ illustration as a style reference.
+- Requested size: 1536 x 1024, medium quality, WebP output.
+- Style reference: overall-architecture-en.webp in this directory, reduced to
+ 836 pixels wide for the reference request.
+- Final delivery: WebP, maximum width 1536, cwebp quality 78, method 6.
+- Visual review: compressed 836-pixel-wide previews only.
+- The credential and API account configuration are deliberately not included.
+- English and Chinese explain the same boundaries; geometry need not be
identical.
+
+The overview shows local dependencies in both clusters. The binding diagram
shows
+two separately selected providers; using one provider cluster for both is also
+possible. The recovery diagram summarizes the normal managed deployment path.
+Its persisted identity applies throughout the workflow, not only after Start.
+The page text and structured API contract define the complete gates and failure
+paths.
+
+## Shared prompt
+
+```text
+Use case: infographic-diagram.
+Asset type: Apache Ambari 3.1 preview documentation, landscape 1536x1024,
ordinary resolution.
+Input image: STYLE REFERENCE ONLY. Replace all architecture content with the
specified new diagram; do not retain the old architecture.
+Style: match the reference's hand-drawn technical sketch, warm off-white
paper, fine irregular graphite ink outlines, light pencil hatching, restrained
teal control arrows and ochre dashed service/data arrows, small sketched
browser/server/database icons. Clean readable handwritten labels, generous
spacing. This is an engineering illustration, not a corporate slide or a grid
of colored cards. No gradients, giant colored panels, logos, watermark, footer
credits, tiny text, decorative pros [...]
+Render exact labels and accurate directed arrows; retain code identifiers
untranslated.
+```
+
+## architecture-en
+
+Output: multi-cluster-architecture-en.webp
+
+```text
+Title: "Ambari 3.1: Multi-cluster architecture".
+Top: two small browser windows side by side, labelled "Tab A / analytics-a"
and "Tab B / analytics-b"; under both "URL-scoped cluster context". Both point
down to one central large Ambari Server sketched machine labelled "REST +
RBAC", "Authorized events", "Requests / tasks". Server connects right to a
single cylinder "Metadata DB", with small labels "Cluster IDs", "Drafts /
revisions", "Bindings / operations".
+Server sends control arrows down into TWO SEPARATE outlined cluster
enclosures: left "Cluster A / ID 2" with three hosts "worker1-3", right
"Cluster B / ID 3" with three different hosts "worker4-6". Inside each
enclosure show "Agents", then "HDFS + ZooKeeper + HBase", connected by short
control arrows. This is the independent LOCAL-dependencies example. NO arrows
between A and B.
+Bottom three concise notes: "One host, at most one cluster"; "Independent
configs, tasks and permissions"; "Shared Server and DB failure boundary".
+Legend: solid teal "Management traffic". Make ownership and the single shared
control plane visually unmistakable.
+```
+
+## architecture-zh
+
+Output: multi-cluster-architecture-zh.webp
+
+```text
+Title: "Ambari 3.1：多集群架构".
+Top: two small browser windows side by side, labelled "标签页 A / analytics-a"
and "标签页 B / analytics-b"; under both "URL 明确集群上下文". Both point down to one
central large Ambari Server sketched machine labelled "REST + RBAC", "授权事件投递",
"请求 / 任务". Server connects right to a single cylinder "元数据数据库", with small
labels "集群 ID", "草稿 / 修订号", "绑定 / 操作".
+Server sends control arrows down into TWO SEPARATE outlined cluster
enclosures: left "集群 A / ID 2" with three hosts "worker1-3", right "集群 B / ID
3" with three different hosts "worker4-6". Inside each enclosure show "Agents",
then "HDFS + ZooKeeper + HBase", connected by short control arrows. This is the
independent LOCAL-dependencies example. NO arrows between A and B.
+Bottom three concise notes: "每台主机最多属于一个集群"; "配置、任务与权限各自独立"; "Server
与数据库仍是共享故障边界".
+Legend: solid teal "管理流量". Make ownership and the single shared control plane
visually unmistakable. All explanatory labels Simplified Chinese.
+```
+
+## bindings-en
+
+Output: multi-cluster-bindings-en.webp
+
+```text
+Title: "HBase: Managed cross-cluster dependencies".
+At top one modest controller "Ambari Server" with "Approved snapshots +
operation epochs". Teal control arrows go to both consumer and providers for
preparation.
+Left outlined area "Consumer cluster A": sketched machines "HBase Master" and
"RegionServers"; a paper client-settings icon "Private client config"; beneath
it "Dedicated HBase identity".
+Right two separate provider enclosures: upper "Provider cluster B / HDFS" with
"NameNode + DataNodes", lower "Provider cluster C / ZooKeeper" with "ZooKeeper
ensemble". Put two distinct ochre dashed arrows FROM consumer HBase TO the
correct provider: upper arrow "Storage binding", lower arrow "Coordination
binding".
+In HDFS area draw two folder icons labelled "Private root" and "Private WAL".
In ZooKeeper area draw tree icon labelled "Private znode". Bottom caption "Each
binding owns a private namespace and UUID".
+Bottom narrow readiness strip: "Prepare provider -> Install clients -> Verify
every daemon host -> READY -> Start HBase".
+Two notes: "Data flows directly to providers"; "Stop consumer does not stop
providers". Small legend teal solid "Control", ochre dashed "Service traffic".
Do NOT imply shared hosts, copied provider credentials, arbitrary storage
engines, or proxying data through Ambari.
+```
+
+## bindings-zh
+
+Output: multi-cluster-bindings-zh.webp
+
+```text
+Title: "HBase：跨集群托管依赖".
+At top one modest controller "Ambari Server" with "已批准快照 + 操作 epoch". Teal
control arrows go to both consumer and providers for preparation.
+Left outlined area "消费集群 A": sketched machines "HBase Master" and
"RegionServers"; a paper client-settings icon "私有客户端配置"; beneath it "独立的 HBase
身份".
+Right two separate provider enclosures: upper "提供集群 B / HDFS" with "NameNode +
DataNodes", lower "提供集群 C / ZooKeeper" with "ZooKeeper 集群". Put two distinct
ochre dashed arrows FROM consumer HBase TO the correct provider: upper arrow
"存储绑定", lower arrow "协调绑定".
+In HDFS area draw two folder icons labelled "私有 root" and "私有 WAL". In
ZooKeeper area draw tree icon labelled "私有 znode". Bottom caption
"每个绑定拥有独立的命名空间与 UUID".
+Bottom narrow readiness strip: "准备提供方 -> 安装客户端 -> 校验全部守护进程主机 -> READY -> 启动
HBase".
+Two notes: "业务数据直接访问提供方"; "停止消费方不会停止提供方". Small legend teal solid "控制流量",
ochre dashed "服务流量". Do NOT imply shared hosts, copied provider credentials,
arbitrary storage engines, or proxying data through Ambari. All explanatory
labels Simplified Chinese.
+```
+
+## recovery-en
+
+Output: multi-cluster-recovery-en.webp
+
+```text
+Title: "Managed HBase: Deployment and recovery".
+Draw a hand-sketched sequence as six numbered milestones in two rows, with
large clear arrows in the exact sequence:
+1 "Save + preview" with sublabel "Draft / cluster + revision"
+2 "Approve + prepare" with sublabel "Binding UUID + snapshot"
+3 "Install clients" with sublabel "Exact host / request / task"
+4 "Credentials + verify" with sublabel "Every current daemon host"
+5 "READY -> Start HBase" with sublabel "All managed bindings ready"
+6 "Service checks" with sublabel "Server confirms completion".
+First row milestones 1,2,3 left to right. Second row 4,5,6 left to right. Draw
a clear connector from 3 to 4 along outside edge, not crossing content.
+Below flow a cylinder "Durable deployment UUID" and paper "Operation ID +
epoch". Side annotation "Refresh: read the SAME deployment".
+Bottom recovery band: "FAILED / STALE / UNRESOLVED -> Read state -> Review /
retry when allowed"; curved recovery arrow returns to milestone 2, never
directly to success.
+Two footer notes: "Missing or stale evidence is not success"; "INSTALL_ONLY is
not COMPLETE".
+Show refresh as a read, NOT as a new launch. Credential step applies only to
secure mode, mark "(if secure)" beside credentials. No code dump or fine print.
+```
+
+## recovery-zh
+
+Output: multi-cluster-recovery-zh.webp
+
+```text
+Title: "托管 HBase：部署与恢复".
+Draw a hand-sketched sequence as six numbered milestones in two rows, with
large clear arrows in the exact sequence:
+1 "保存并预览" with sublabel "草稿 / 集群 + 修订号"
+2 "批准并准备" with sublabel "绑定 UUID + 快照"
+3 "安装客户端" with sublabel "精确的主机 / 请求 / 任务"
+4 "凭据与校验" with sublabel "全部当前守护进程主机"
+5 "READY -> 启动 HBase" with sublabel "全部托管绑定就绪"
+6 "服务检查" with sublabel "服务端确认完成".
+First row milestones 1,2,3 left to right. Second row 4,5,6 left to right. Draw
a clear connector from 3 to 4 along outside edge, not crossing content.
+Below flow a cylinder "持久化部署 UUID" and paper "操作 ID + epoch". Side annotation
"刷新：读取同一个部署".
+Bottom recovery band: "FAILED / STALE / UNRESOLVED -> 读取状态 -> 按允许的动作审核 / 重试";
curved recovery arrow returns to milestone 2, never directly to success.
+Two footer notes: "缺失或过期的证据不能视为成功"; "INSTALL_ONLY 不等于 COMPLETE".
+Show refresh as a read, NOT as a new launch. Credential step applies only to
secure mode, mark "凭据仅限安全模式" beside credentials. No code dump or fine print.
All explanatory labels Simplified Chinese.
+```
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-recovery-en.webp
b/static/img/3.1.0/handdrawn/multi-cluster-recovery-en.webp
new file mode 100644
index 0000000..7a2fa7c
Binary files /dev/null and
b/static/img/3.1.0/handdrawn/multi-cluster-recovery-en.webp differ
diff --git a/static/img/3.1.0/handdrawn/multi-cluster-recovery-zh.webp
b/static/img/3.1.0/handdrawn/multi-cluster-recovery-zh.webp
new file mode 100644
index 0000000..446bb21
Binary files /dev/null and
b/static/img/3.1.0/handdrawn/multi-cluster-recovery-zh.webp differ
diff --git a/tests/e2e/i18n.spec.ts b/tests/e2e/i18n.spec.ts
index 247a75a..554adf4 100644
--- a/tests/e2e/i18n.spec.ts
+++ b/tests/e2e/i18n.spec.ts
@@ -168,7 +168,7 @@ test('3.1 preview routes are bilingual and preserve the
stable default', async (
const data = JSON.parse(readFileSync('.docusaurus/globalData.json', 'utf8'));
const versions = data['docusaurus-plugin-content-docs'].default.versions;
const preview = versions.find(item => item.name === '3.1.0');
- expect(preview.docs).toHaveLength(73);
+ expect(preview.docs).toHaveLength(77);
expect(preview.isLast).toBe(false);
expect(versions.find(item => item.name === '3.0.0').isLast).toBe(true);
expect(versions.some(item => item.name === 'current')).toBe(false);
@@ -296,6 +296,46 @@ test('3.1 guides render the monitoring asset and localized
navigation', async ({
for (const label of labels) expect(label).toMatch(/[\u3400-\u9fff]/);
});
+test('multi-cluster guides render localized compact diagrams without
overflow', async ({page, request}, testInfo) => {
+ const errors: string[] = [];
+ page.on('pageerror', error => errors.push(error.message));
+ for (const prefix of ['', '/zh-Hans']) {
+ for (const docSlug of ['architecture', 'getting-started',
'managed-dependencies', 'operations']) {
+ await page.goto(`${prefix}/docs/3.1.0/multi-cluster/${docSlug}`);
+ await expect(page.locator('html')).toHaveAttribute('data-has-hydrated',
'true');
+ await expect(page.locator('article h1')).toBeVisible();
+ await expect(page.getByTestId('translation-fallback')).toHaveCount(0);
+ await expect.poll(() => page.evaluate(() =>
document.documentElement.scrollWidth <= window.innerWidth)).toBe(true);
+ const diagrams = page.locator('article img');
+ await expect(diagrams).toHaveCount(docSlug === 'architecture' ? 1 :
docSlug === 'managed-dependencies' ? 2 : 0);
+ for (const diagram of await diagrams.all()) {
+ await diagram.scrollIntoViewIfNeeded();
+ await expect.poll(() => diagram.evaluate((element: HTMLImageElement)
=> element.complete && element.naturalWidth > 0)).toBe(true);
+ const source = await diagram.getAttribute('src');
+ expect(source).toContain(`-${prefix ? 'zh' : 'en'}-`);
+ const dimensions = await diagram.evaluate((element: HTMLImageElement)
=> ({
+ width: element.naturalWidth, height: element.naturalHeight,
+ displayedWidth: element.getBoundingClientRect().width,
+ availableWidth: element.closest('article')!.clientWidth,
+ }));
+ expect(dimensions.width).toBe(1536);
+ expect(dimensions.height).toBe(1024);
+
expect(dimensions.displayedWidth).toBeLessThanOrEqual(dimensions.availableWidth);
+ const asset = await request.get(source!);
+ expect(asset.ok()).toBe(true);
+ expect(asset.headers()['content-type']).toContain('image/webp');
+ expect((await asset.body()).length).toBeLessThan(200 * 1024);
+ }
+ if (docSlug === 'architecture') {
+ await page.locator('article img').screenshot({
+ path: testInfo.outputPath(`multi-cluster-${prefix ? 'zh' :
'en'}.png`),
+ });
+ }
+ }
+ }
+ expect(errors).toEqual([]);
+});
+
test('version menu preserves the selected language', async ({page, isMobile})
=> {
await page.goto('/zh-Hans/docs/3.0.0/introduction');
await expect(page.locator('html')).toHaveAttribute('data-has-hydrated',
'true');
diff --git a/tests/i18n.test.mjs b/tests/i18n.test.mjs
index 3e8af58..5109959 100644
--- a/tests/i18n.test.mjs
+++ b/tests/i18n.test.mjs
@@ -119,6 +119,8 @@ test('3.1.0 retains current general documentation without
obsolete tutorial rout
'platform/java-dependencies', 'platform/python-runtime',
'platform/rpm-packaging', 'frontend/react-ui',
'frontend/customizing-react-ui',
+ 'multi-cluster/architecture', 'multi-cluster/getting-started',
+ 'multi-cluster/managed-dependencies', 'multi-cluster/operations',
'quick-start/installation-guide', 'quick-start/download',
'ambari-design/blueprints/index', 'ambari-design/kerberos/index',
'ambari-design/views/index', 'ambari-design/views/developing-react-views',
@@ -128,7 +130,7 @@ test('3.1.0 retains current general documentation without
obsolete tutorial rout
'ambari-dev/running-tests', 'ambari-plugin-contribution/index',
];
for (const id of required) assert.ok(ids.includes(id), `Missing supported
documentation: ${id}`);
- assert.equal(ids.length, 73);
+ assert.equal(ids.length, 77);
assert.equal(new Set(ids).size, ids.length);
assert.ok(!ids.some(id => id.startsWith('ambari-design/metrics/') ||
id.startsWith('ambari-plugin-contribution/scom/')));
assert.ok(!ids.includes('ambari-plugin-contribution/step-by-step'));
diff --git a/versioned_docs/version-3.1.0/ambari-design/ambari-architecture.md
b/versioned_docs/version-3.1.0/ambari-design/ambari-architecture.md
index 31912ef..b2f77cb 100644
--- a/versioned_docs/version-3.1.0/ambari-design/ambari-architecture.md
+++ b/versioned_docs/version-3.1.0/ambari-design/ambari-architecture.md
@@ -34,6 +34,8 @@ limitations under the License.
## Request And Data Paths {#request-and-data-paths}
+The same control plane can manage several independently owned clusters. See
[Multi-cluster Architecture](../multi-cluster/architecture.md) for host
ownership, URL and permission boundaries, persistent workflow identity, and
optional shared HBase providers.
+
The following shows control and request paths; metric responses return to the
scraper:
```text
diff --git a/versioned_docs/version-3.1.0/frontend/react-ui.md
b/versioned_docs/version-3.1.0/frontend/react-ui.md
index cf4f701..e7dbb97 100644
--- a/versioned_docs/version-3.1.0/frontend/react-ui.md
+++ b/versioned_docs/version-3.1.0/frontend/react-ui.md
@@ -35,6 +35,12 @@ React is selected by default when no browser preference
exists. An older browser
The historical Ember application is referenced only for migration comparison;
it is not a 3.1 operating path described by this guide.
+## Multi-cluster Navigation {#multi-cluster-navigation}
+
+Cluster operations use `/clusters/:clusterName/main/*` inside the React hash
route. The global `/clusters` and `/services` directories show authorized
clusters and deployments; selecting a row establishes its owning cluster in the
URL. Separate tabs retain independent context. Unscoped legacy links resolve
through an authorized cluster selection, not an arbitrary first cluster.
+
+See [Creating and Using Clusters](../multi-cluster/getting-started.md) for
installation, saved-draft recovery, Admin management and concrete URLs.
[Managed HBase Dependencies](../multi-cluster/managed-dependencies.md) explains
provider selection and readiness; [Operations and
Recovery](../multi-cluster/operations.md) covers exact request identity and
retry.
+
## Workflow Coverage {#workflow-coverage}
### Installation and Hosts {#installation-and-hosts}
diff --git a/versioned_docs/version-3.1.0/multi-cluster/architecture.md
b/versioned_docs/version-3.1.0/multi-cluster/architecture.md
new file mode 100644
index 0000000..cb34ed6
--- /dev/null
+++ b/versioned_docs/version-3.1.0/multi-cluster/architecture.md
@@ -0,0 +1,117 @@
+---
+title: Multi-cluster Architecture
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Multi-cluster Architecture {#multi-cluster-architecture}
+
+Ambari can manage several independent clusters through one Server and metadata
database. A cluster owns its services, host assignments, configurations,
requests and permissions. Operators can optionally connect a new HBase
deployment to managed HDFS and ZooKeeper services in other clusters.
+
+This guide describes the implementation merged in [AMBARI-26656 / PR
#4216](https://github.com/apache/ambari/pull/4216), checked against trunk
`fc07b5cb873dc154c48349085494e664baf6b9d1` on 2026-09-22. It belongs to the
3.1.0 **preview** documentation; it is not a released-version support
certificate. See [Source Baseline](../release-baseline.md).
+
+Start with [Creating and Using Clusters](./getting-started.md), then [Managed
HBase Dependencies](./managed-dependencies.md) and [Operations and
Recovery](./operations.md).
+
+## Control Plane And Cluster Boundaries {#control-plane-and-cluster-boundaries}
+
+
+
+The drawing uses two independent clusters with local service dependencies.
Both sets of Agents register with the same Ambari Server. The Server dispatches
tasks to the appropriate hosts and persists each request's owning cluster.
Sharing a Server does not merge the two HDFS namespaces or ZooKeeper ensembles.
+
+| Boundary | What it means |
+| --- | --- |
+| Server and database | Shared management availability, upgrade and backup
scope. Multi-cluster management does not introduce Server high availability. |
+| Cluster | Independent service deployment, desired configuration,
authorization and operation scope. |
+| Host | Registered but unassigned, or assigned to exactly one runtime
cluster. One host cannot simultaneously run as a member of both clusters. |
+| Service | Deployment identity is the pair `(cluster_id, service_name)`;
HBase in A and HBase in B are different deployments. |
+| Managed dependency | An explicit consumer/provider relationship. The
provider retains service lifecycle and data ownership. |
+| Remote Cluster registration | A separate existing integration for remote
cluster references. It does not import another Server's hosts into this runtime
or federate its lifecycle management. |
+
+A Server outage affects management for every cluster. Service daemons have
their own availability mechanisms; do not assume either that they all stop or
that every operation remains available during a Server outage. If clusters
share an HDFS or ZooKeeper provider, a provider outage also affects its
consumers.
+
+## Route And Authorization Isolation {#route-and-authorization-isolation}
+
+Operational URLs include the cluster name:
+
+```text
+/latest/#/clusters/analytics-a/main/hosts
+/latest/#/clusters/analytics-b/main/services/HBASE/summary
+/latest/#/clusters
+/latest/#/services
+
+/api/v1/clusters/analytics-a/services/HBASE
+/api/v1/clusters/analytics-b/services/HBASE
+```
+
+The last two browser routes are global authorized directories. Selecting a
service establishes its cluster in the URL. Separate tabs can inspect different
clusters without using a global selected-cluster value as authority.
+
+React keys its runtime by authenticated user and route scope. Cluster switches
invalidate old requests, caches, polling and event consumers before they can
update the new screen. A last-used numeric cluster preference is only a
navigation hint; the Server's current authorization and cluster inventory must
validate it.
+
+Server authorization remains the security boundary. AMBARI-scoped grants apply
globally; CLUSTER-scoped grants apply to the named cluster. Being a cluster
administrator does not grant Ambari administration. Server-side STOMP
authorization/projection restricts event delivery, and request/task reads
validate actual ownership. Browser filtering alone cannot protect another
cluster's information.
+
+## Persistent Identity And Recovery {#persistent-identity-and-recovery}
+
+| Identity | Purpose |
+| --- | --- |
+| Numeric cluster ID | Stable cluster identity across rename; names remain in
compatible REST paths. |
+| Creation draft UUID | Identifies one installation intent, its owner and the
exact cluster created from it. |
+| Workflow scope and revision | Separates installer drafts and cluster
workflows; rejects obsolete writes instead of overwriting another session's
checkpoint. |
+| Binding UUID | Identifies one managed HDFS or ZooKeeper relationship and its
private namespace. |
+| Snapshot version and fingerprints | Identify approved provider/client
configuration and consumer topology/security inputs. |
+| Operation ID and epoch | Associate an attempt and exclude stale work from an
earlier operation. |
+| Deployment UUID and attempt ID | Persist the installation/start/check
workflow independently of a browser session. |
+| Request, task and host IDs | Tie execution results to the exact scheduled
work and authorized host. |
+
+Creation submits `creation_draft_id`. If a create response is lost, recovery
checks the saved draft-to-cluster association. A matching cluster name is not
sufficient proof that the current draft created it. Creation does not delete
existing clusters or shared repository definitions.
+
+The database enforces exclusive host membership. The upgrade path detects
duplicate historical memberships and stops for explicit remediation; it does
not silently select an owner. Back up and resolve ambiguous ownership before
retrying an upgrade.
+
+## Shared Services Without Shared Ownership
{#shared-services-without-shared-ownership}
+
+A managed HBase deployment may select HDFS for storage and ZooKeeper for
coordination independently. Each binding persists the provider's numeric
identity, a reviewed configuration snapshot, a private namespace and operation
history.
+
+Provider settings enter an allowlisted, HBase-specific client overlay. The
consumer retains its own Hadoop configuration and does not receive the
provider's administrative credentials. Client installation, credential work and
connectivity checks run against the exact current plan.
+
+A binding becoming ready is distinct from a deployment completing. The Server
coordinates provider preparation, consumer installation, dependency
verification, HBase Start and service checks. Refresh reads the same deployment
instead of launching replacement work. See the [binding and readiness
walkthrough](./managed-dependencies.md#deployment-sequence).
+
+## Implementation Map {#implementation-map}
+
+| Layer | Source and responsibility |
+| --- | --- |
+| Browser navigation | [React
routes](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/router/RoutesList.tsx)
and [cluster
directory](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/screens/Directories/ClusterDirectory.tsx):
explicit cluster context, authorized discovery and draft resume. |
+| Administration | [Admin
routes](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-admin/src/main/resources/ui/ambari-admin/src/router/RoutesList.tsx):
cluster overview, host resources, permissions and repository navigation. |
+| Host membership | [Host membership
upgrade](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/upgrade/HostMembershipSchemaUpgrade.java):
exclusive ownership and migration checks. |
+| Dependency approval | [Managed service
coordinator](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedServiceDependencyCoordinator.java):
authorization, preview, snapshots, binding mutations and operation lineage. |
+| Deployment recovery | [Deployment
coordinator](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyDeploymentCoordinator.java):
persistent install, readiness, start and service-check progression. |
+| Start and lifecycle gates | [Readiness
policy](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyReadinessPolicy.java)
and [lifecycle
policy](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyLifecyclePolicy.java):
current evidence, impact conf [...]
+| Agent-side execution | [Managed HBase
scripts](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/resources/stacks/BIGTOP/3.2.0/services/HBASE/package/scripts/managed_hbase_dependency.py):
structured observations, private client configuration and verification. |
+
+The scripts' inherited source directory includes `BIGTOP/3.2.0`; that
directory name is not the managed dependency compatibility contract. The
current validator requires active BIGTOP 3.3.0 repositories and matching
resolved version metadata.
+
+## Evidence And Remaining Qualification {#evidence-and-remaining-qualification}
+
+The historical [implementation and runtime
record](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/docs/design/multi-cluster-review-and-remediation.md)
contains separate checkpoints:
+
+| Scenario | Recorded evidence | Limit |
+| --- | --- | --- |
+| Two independent clusters, local HBase dependencies | Six-host native RPM
deployment at source `1ab17a10ea333e35d9952666d57d8f4383762103`; distinct HBase
identities, service checks, foreign-user denials and duplicate-host rejection.
| Historical source/package acceptance, not a new deployment of the current
trunk. |
+| Cross-cluster managed HBase | A deployment reached complete with both
bindings ready and an SDK Put/Get service check. | Used an earlier RPM plus
documented file/class overlays; do not describe it as the final clean-package
acceptance. |
+| Admin workflows | Recorded browser/API checks for overview, host ownership,
draft resume, grants, rename and deletion. | Not an exhaustive role, proxy or
browser matrix. |
+| Remaining fault/security scenarios | Source and focused regression coverage
exist. | Real KDC callbacks, managed provider stop/delete/detach retention,
every crash/drop boundary and complete broker revocation matrix still need
qualification. |
+
+Website build and browser tests validate these documents and images. They do
not establish cluster runtime acceptance.
diff --git a/versioned_docs/version-3.1.0/multi-cluster/getting-started.md
b/versioned_docs/version-3.1.0/multi-cluster/getting-started.md
new file mode 100644
index 0000000..e4d59b9
--- /dev/null
+++ b/versioned_docs/version-3.1.0/multi-cluster/getting-started.md
@@ -0,0 +1,113 @@
+---
+title: Creating And Using Clusters
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Creating And Using Clusters {#creating-and-using-clusters}
+
+Use this procedure for two independent clusters managed by the same Ambari
Server. For the architecture and version boundary, read [Multi-cluster
Architecture](./architecture.md). Sharing providers is optional and is covered
separately in [Managed HBase Dependencies](./managed-dependencies.md).
+
+## Before You Start {#before-you-start}
+
+Use matching Server, Agent, Web and Admin artifacts containing the
multi-cluster implementation. Complete the normal [installation
prerequisites](../quick-start/installation-guide.md), including DNS,
connectivity, repositories and Agent enrollment. Existing installations must
follow the [upgrade procedure](../upgrade-guide.md); this guide is not a
substitute for the database migration.
+
+| Requirement | Check |
+| --- | --- |
+| Creation authority | Your account has `AMBARI.ADD_DELETE_CLUSTERS`.
Cluster-only administration does not grant global creation. |
+| Host inventory | New hosts are registered with this Server and are
unassigned. Check Admin's Host Resources before installation. |
+| Repository definition | The selected Stack and repository work on the target
hosts. Reuse identical settings; resolve a conflicting shared definition
explicitly. |
+| Unique target | Choose a new cluster name and start a fresh installation
draft. |
+| Capacity | Size the shared Server/database and each service deployment for
their combined load. No fixed cluster-count capacity guarantee is implied. |
+
+A small example uses six hosts:
+
+| Cluster | Hosts | Local services |
+| --- | --- | --- |
+| analytics-a | worker1, worker2, worker3 | HDFS, ZooKeeper and HBase |
+| analytics-b | worker4, worker5, worker6 | HDFS, ZooKeeper and HBase |
+
+This is a topology example, not a production sizing recommendation. Hosts need
not match these names. The critical property is that the two host sets do not
overlap.
+
+## Create The First Or Next Cluster {#create-the-first-or-next-cluster}
+
+1. Sign in through the primary React entry point. Open **Clusters**, or use
the cluster menu's **Admin Cluster Management** entry if authorized.
+2. In Admin, open **Create Cluster** and choose **Start installation wizard**.
The global Clusters directory also exposes creation to authorized users.
+3. Enter the new cluster name. The wizard URL includes a draft identifier;
retain that URL if the installation is interrupted.
+4. Select the Stack/version and review repository URLs. Register or select
only unassigned hosts for this cluster.
+5. Select services. For an independent HBase deployment, retain the local HDFS
and ZooKeeper choices. Do not choose managed providers merely because other
clusters are present.
+6. Review component placement and configurations. Confirm that every hostname
belongs to the intended target, especially when adding the second cluster.
+7. Submit Review, follow installation and startup progress, and inspect any
failed request/task before retrying.
+8. Finish the wizard, open the cluster's Hosts and Services screens, and
verify the actual inventory and component states. Run the service checks
appropriate to the selected services.
+
+Repeat from a **new** draft to create the next cluster. Do not reuse the first
cluster's saved installer URL. Existing clusters and shared repository records
are preserved.
+
+A name collision is a validation failure, not permission to overwrite or adopt
the existing cluster. Choose another name, or open the existing cluster through
an authorized link if that was your intent.
+
+## Resume An Interrupted Installation {#resume-an-interrupted-installation}
+
+Open **Clusters** or Admin **Create Cluster** using the same account. Your
saved installations show their target, phase and installation ID; choose the
resume/continue action for the original draft.
+
+Allow the workflow to load its saved revision before editing. Passwords,
private keys and other sensitive fields are stripped from persisted checkpoints
and may need to be entered again. A missing secret blocks the affected
operation, while non-secret inputs can remain saved.
+
+If a create or host-assignment response was lost, let the wizard reconcile its
original draft and recorded assignment intent. Do not create another same-name
cluster to “repair” uncertainty. A revision conflict requires reloading the
current checkpoint before retrying edits. See [recovery
cases](./operations.md#recovery-cases).
+
+Leaving or refreshing a page does not establish that Server work was
cancelled. Inspect the saved workflow and its request IDs after reconnecting.
+
+## Switch And Compare Safely {#switch-and-compare-safely}
+
+| Task | Entry |
+| --- | --- |
+| Browse authorized clusters | `/latest/#/clusters` |
+| Compare service deployments | `/latest/#/services` |
+| Open A's hosts | `/latest/#/clusters/analytics-a/main/hosts` |
+| Open B's HBase configuration |
`/latest/#/clusters/analytics-b/main/services/HBASE/configs` |
+| Inspect B's operations | `/latest/#/clusters/analytics-b/main/requests` |
+
+These paths assume the standard deployment base; preserve any configured
reverse-proxy prefix. Encode a cluster name as one URL path segment instead of
concatenating an unescaped name.
+
+Directories retain search, sorting and pagination in the URL. The Services
directory identifies both the service and owning cluster and shows HBase
dependency summaries. A failure loading one cluster does not turn another
cluster's rows into its replacement; retry the failed scope.
+
+After login, Ambari revalidates an authorized continuation or the user's last
numeric cluster preference. A sole authorized cluster can be selected
automatically; otherwise the UI asks for a selection. Old unscoped links
preserve their intended destination through this selection. A removed or
forbidden target must not silently become another cluster.
+
+## Admin Tasks {#admin-tasks}
+
+| Screen | Use |
+| --- | --- |
+| Cluster Overview | Find managed clusters and open the desired cluster or its
details. |
+| Cluster Details | Review Basic Information, Services & Hosts, Access
Permissions, Operation History, and Configuration & Export. |
+| Host Resources | Distinguish assigned and unassigned hosts; open the target
cluster's existing Add Host wizard. |
+| Cluster Permissions | Grant or remove access for the explicit target
cluster, then read back its privileges. |
+| Versions & Repositories | Review the global repository catalog and the
selected cluster's version state. |
+| Remote Clusters | Maintain remote references; this does not create another
locally managed runtime cluster. |
+
+Rename preserves numeric identity. Deletion is a separate guarded operation:
inspect service state and dependency impact, stop the required components, and
use the authorized deletion workflow. Do not interpret removing a UI row or
receiving an accepted request as proof of deletion.
+
+## Check The Result {#check-the-result}
+
+1. In each cluster's Hosts screen, confirm the expected host set and disjoint
ownership.
+2. Open each cluster's HBase service in a separate tab. Verify the owning
cluster, effective storage/coordination configuration and service-check results.
+3. With a cluster-limited account, verify only the intended inventory and
operations are available. A global administrator is not a useful isolation test
account.
+4. Refresh an explicit cluster URL and confirm it reloads the same target;
resume any unfinished workflow from its original checkpoint.
+5. Check the request and task states for the exact operation you launched. Do
not use a recent unrelated successful task as its completion evidence.
+
+For scripted checks, use the [read-only API
examples](./operations.md#read-only-api-examples). Real topology and role
acceptance must be performed in your deployment; the website examples do not
execute those checks.
+
+## Source References {#source-references}
+
+The procedure follows [Admin Create
Cluster](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-admin/src/main/resources/ui/ambari-admin/src/screens/ClusterManagement/ClusterCreate.tsx),
the [cluster
directory](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/screens/Directories/ClusterDirectory.tsx),
the [service
directory](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1
[...]
diff --git a/versioned_docs/version-3.1.0/multi-cluster/managed-dependencies.md
b/versioned_docs/version-3.1.0/multi-cluster/managed-dependencies.md
new file mode 100644
index 0000000..06d37c3
--- /dev/null
+++ b/versioned_docs/version-3.1.0/multi-cluster/managed-dependencies.md
@@ -0,0 +1,116 @@
+---
+title: Managed HBase Dependencies
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Managed HBase Dependencies {#managed-hbase-dependencies}
+
+Managed dependencies let a new HBase service consume an existing managed HDFS
service and/or ZooKeeper ensemble while keeping its own cluster, hosts and
lifecycle. They are optional: independent clusters can continue using their own
local HDFS and ZooKeeper.
+
+Read the [architecture and evidence boundary](./architecture.md) before
planning a shared deployment. The current consumer is HBase, and the
implemented dependency types are `HDFS` and `ZOOKEEPER`; this is not a
general-purpose service federation or arbitrary external-endpoint feature.
+
+## Topology And Ownership {#topology-and-ownership}
+
+
+
+The diagram deliberately places HDFS and ZooKeeper in different provider
clusters. They can also be in the same provider cluster. Each selection has its
own binding and readiness checks; review the complete plan before provisioning.
The consumer's hosts remain members of its own cluster.
+
+| Choice | Effect |
+| --- | --- |
+| Local HDFS and ZooKeeper | Conventional independent HBase deployment; no
managed cross-cluster binding is needed. |
+| Managed HDFS, local ZooKeeper | HBase storage uses the selected provider;
coordination stays local. |
+| Local HDFS, managed ZooKeeper | Storage stays local; coordination uses the
selected provider. |
+| Managed HDFS and ZooKeeper | Two bindings, each with its own provider
identity, private namespace and readiness evidence. |
+
+Ambari coordinates approval, preparation and verification. HBase communicates
directly with provider daemons for storage and coordination; data does not flow
through Ambari Server. A shared provider introduces shared availability and
maintenance dependencies.
+
+## Compatibility And Permissions {#compatibility-and-permissions}
+
+| Check | Current contract |
+| --- | --- |
+| Consumer lifecycle | A draft/new service plan or fresh HBase service in
initial state. Converting a data-bearing local HBase deployment is not
supported. |
+| Stack and versions | Consumer and provider use active BIGTOP 3.3.0
repositories with nonempty, equal resolved version metadata and compatible
client features. A matching display version alone is insufficient. |
+| Provider readiness | The selected service is installed and healthy before
snapshot approval. |
+| HDFS features | Federation and Observer NameNode clients are rejected by the
managed binding validator. Do not infer support from their availability
elsewhere in Ambari. |
+| Security | Both sides are unsecured, or satisfy the dedicated same-realm
Kerberos checks. Mixed secure/insecure and cross-realm bindings are rejected. |
+| Network | Every current HBase daemon host can resolve and reach the
configured NameNode RPC, DataNode data-transfer and ZooKeeper endpoints. Use
the actual provider configuration, not assumed default ports. |
+| Consumer authority | Modification and identity planning require
`SERVICE.MODIFY_CONFIGS` and `SERVICE.SET_SERVICE_USERS_GROUPS`; Add Service
additionally requires `SERVICE.ADD_DELETE_SERVICES`. |
+| Provider authority | Discovery requires service-view authorization;
preparation/mutation requires `SERVICE.RUN_CUSTOM_COMMAND` on the provider
cluster. Consumer-only administration is insufficient. |
+
+Installer drafts require global cluster-creation authority. Installation,
Start and service checks also retain their ordinary operation permissions; the
table lists dependency-specific prerequisites, not an exhaustive role grant
recipe.
+
+The initial secure path adds HBase to an **already Kerberized consumer
cluster**. A new cluster installation does not automatically establish a usable
secure dependency plan. Same-realm support includes identity mapping, provider
policy proof, credential issuance and verification; the existence of source
support does not close the real-KDC acceptance gap.
+
+## Choose And Review Providers {#choose-and-review-providers}
+
+1. Start a new cluster installation or open **Add Service** in the intended
consumer cluster and select HBase.
+2. In service selection, review the separate **Storage** and **ZooKeeper**
choices. Keep the local default for any dependency that should remain local.
+3. For a managed dependency, open the authorized provider list. Verify the
provider cluster, service, compatibility result and any returned reasons before
selecting it.
+4. Save the selection and preview the plan. The wizard can release local
daemon services selected solely to satisfy HBase, but retains services
explicitly selected or required by another local consumer. Client packages
remain necessary.
+5. At configuration, inspect the managed client values and edit ordinary HBase
properties as appropriate. Change provider-owned values through provider
selection/review, not by copying complete provider configurations.
+6. At Review, verify consumer identity, provider ownership, private paths,
host placement and the current compatibility result. A changed provider or
topology invalidates the old preview.
+7. Submit the reviewed plan, then follow the Server-owned deployment. Do not
start HBase manually while dependency preparation or verification is incomplete.
+
+Adding an unrelated service beside an existing HBase deployment preserves its
dependency ownership; it does not offer a migration opportunity. Unsupported
choices should be resolved before provisioning.
+
+## Private Configuration And Data Paths {#private-configuration-and-data-paths}
+
+For each binding, the Server derives private paths from its UUID:
+
+```text
+HDFS binding:
+ hdfs://<provider-authority>/apps/ambari-managed/hbase/<hdfs-binding-id>/root
+ hdfs://<provider-authority>/apps/ambari-managed/hbase/<hdfs-binding-id>/wal
+
+ZooKeeper binding:
+ /ambari-managed-hbase/<zk-binding-id>/hbase
+```
+
+The HDFS and ZooKeeper binding IDs are independent. Root and WAL paths are
distinct; the ZooKeeper binding has a private container and coordination child.
Ambari also maintains ownership/fencing records. Do not manually delete those
records or reuse the reserved paths for another application.
+
+Only allowlisted client settings enter the approved snapshot. The HBase
overlay does not overwrite an unrelated local service's Hadoop configuration.
Provider administrative principals and keytabs are not copied to consumers.
Read the returned namespace and planned identity instead of inventing an HBase
user or path convention.
+
+## Deployment Sequence {#deployment-sequence}
+
+
+
+| Stage | What must be established |
+| --- | --- |
+| Save and preview | Exact draft/service-plan revision, selected providers and
current fingerprints. |
+| Approve and prepare | Persisted binding snapshot; provider preparation for
its exact namespace and identity. |
+| Install/configure | Approved clients and private configuration on the
intended consumer hosts; durable request/task association. |
+| Credentials and verification | Credential completion when required; NameNode
RPC plus DataNode write/read checks, ZooKeeper session/private-znode checks,
and current client/identity evidence. |
+| Ready and Start | All managed bindings ready and evidence valid for **every
current HBase daemon host**. |
+| Service checks and completion | Exact Start and service-check request/task
results associated with the same durable deployment. |
+
+`READY` on one binding does not imply deployment completion. Inspect the
deployment's `completed` field, current request/task results and operation
identity. `INSTALL_ONLY` is a deliberate branch and does not mean `COMPLETE`.
+
+## Updates, Maintenance And Detach {#updates-maintenance-and-detach}
+
+Open HBase's **Dependencies** tab, or use the dependency link in the Services
directory. The page shows ownership, phase, desired/applied snapshot versions,
readiness and permitted next actions.
+
+For provider configuration drift, use **Review changes**, inspect the proposed
snapshot, and apply the reviewed changes when allowed. A concurrency conflict
requires a new preview. **Retry preparation** retries the current binding
through the supported operation; it must not reuse an unrelated task result.
+
+Before stopping or restarting a provider, review its dependent consumers and
confirm the current impact revision. Hidden consumers may appear as an
anonymous count when you lack permission to see their names; an empty
visible-name list does not imply no impact. Provider deletion is blocked while
active bindings remain.
+
+Stop HBase before **Detach provider**. Detach preserves provider services and
stored data, and the detached dependency cannot be used to restart HBase.
Detach is not a data migration or data-erasure command. Plan consumer
retirement, data retention and any later cleanup explicitly; real
detach/retention acceptance remains a qualification item.
+
+## Source References {#source-references}
+
+See the [snapshot
validator](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencySnapshotValidator.java),
[namespace
allocation](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyNamespace.java),
[dependency API client](https://github.com/apache/am [...]
diff --git a/versioned_docs/version-3.1.0/multi-cluster/operations.md
b/versioned_docs/version-3.1.0/multi-cluster/operations.md
new file mode 100644
index 0000000..d206ce3
--- /dev/null
+++ b/versioned_docs/version-3.1.0/multi-cluster/operations.md
@@ -0,0 +1,141 @@
+---
+title: Operations And Recovery
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Operations And Recovery {#operations-and-recovery}
+
+Operate on the explicit cluster and the exact saved operation. A successful
HTTP submission, a zero process exit, a log message or an unrelated completed
request does not prove that the intended workflow finished. Use the Server's
structured state and identifiers.
+
+This runbook complements [cluster creation](./getting-started.md) and [managed
HBase dependencies](./managed-dependencies.md). The [architecture
guide](./architecture.md#evidence-and-remaining-qualification) distinguishes
historical runtime evidence from remaining qualification.
+
+## Read-only API Examples {#read-only-api-examples}
+
+The following are HTTP request targets for an already authenticated API
client. Replace the example cluster name and identifier placeholders with
values returned for your operation; preserve the deployment's authentication
and proxy settings. Do not put credentials in scripts or shared diagnostic
output.
+
+```http
+GET
/api/v1/clusters?fields=Clusters/cluster_id,Clusters/cluster_name,Clusters/provisioning_state
+GET /api/v1/clusters/analytics-a/hosts?fields=Hosts/host_name
+GET /api/v1/clusters/analytics-a/services/HBASE/dependencies
+GET /api/v1/clusters/analytics-a/services/HBASE/dependencies/{bindingId}
+GET
/api/v1/clusters/analytics-a/services/HBASE/dependencies/deployments/{deploymentId}
+GET /api/v1/clusters/analytics-a/requests/{requestId}
+GET /api/v1/clusters/analytics-a/requests/{requestId}/tasks
+```
+
+| Observation | Read and validate |
+| --- | --- |
+| Cluster inventory | `Clusters.cluster_id` and `Clusters.cluster_name`; a
name change must preserve the numeric identity. |
+| Binding list | `items`; ownership may be `managed`, `local`, `unmanaged` or
`unknown`. A missing managed binding does not prove a local dependency is
healthy. |
+| Binding detail | `binding_id`, `consumer`, `provider`, `phase`,
`row_version`, `operation_epoch`, desired/applied snapshot versions and
operation identity. |
+| Binding readiness | `readiness` identifies required, prepared and verified
daemon hosts; `capabilities`, `allowed_actions` and `next_action` describe
permitted progression. |
+| Deployment | `deployment_id`, `cluster_id`, `attempt_id`, `request_id`,
`history`, `state`, `phase`, `failure_code`, `retry_allowed`, `completed` and
`install_only`. |
+| Task completion | Read the exact request's tasks and owning cluster. Confirm
the task/host/operation association and terminal results rather than searching
all recent requests. |
+
+A structured dependency error has `code` and `message`. Branch on the HTTP
status and exact error code; the message is diagnostic text. Missing fields,
malformed values or foreign identities must remain an error or unresolved
observation.
+
+## Mutation Contract For Integrators {#mutation-contract-for-integrators}
+
+Prefer the UI for ordinary administration. For automation, use the pinned [API
client](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-web/latest/src/api/serviceDependenciesApi.ts)
and [REST
service](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/api/services/ManagedServiceDependencyService.java)
as the payload contract.
+
+In the table, `D` means
`/api/v1/clusters/{clusterName}/services/HBASE/dependencies`.
+
+| Method and resource | Contract |
+| --- | --- |
+| `GET D/candidates?type=HDFS` | Discover authorized provider candidates for
an existing HBase consumer; ZooKeeper uses its own dependency type. |
+| `POST D/preview` | Preview one selection or the complete selection set; not
approval or provisioning. |
+| `POST D` | Approve exact binding IDs, provider identity, preview schema
version and returned fingerprints, with an operation UUID. Supports a one- or
two-item collection. |
+| `POST D/deployments/{deploymentId}` | Persist/launch exact targets and an
explicit install-only mode under an immutable deployment UUID. |
+| `POST D/deployments/{deploymentId}/actions/retry` | Retry that deployment
with an operation UUID only when the returned capability permits it. |
+| `GET D/{bindingId}/preview-update` | Read a fresh update proposal before
approving provider configuration changes. |
+| `POST D/{bindingId}/actions/update` | Submit the fresh preview's
row/snapshot versions, fingerprints, approval and schema version with the
operation UUID. |
+| `POST D/{bindingId}/actions/retry` | Submit an operation UUID and the
expected current row version. |
+| `POST D/{bindingId}/actions/verify-credentials` | Verify credentials against
the expected current epoch, when the workflow permits manual credential
handling. |
+| `DELETE D/{bindingId}` | Detach with an operation UUID and expected row
version after satisfying lifecycle guards; does not erase provider data. |
+
+Draft and Add Service discovery use `/api/v1/service-dependencies/candidates`
and `/api/v1/service-dependencies/preview`, with the appropriate draft or
service-plan scope and expected revision. Do not create a dummy HBase service
simply to make discovery work.
+
+Provider-side reads use
`/api/v1/clusters/{clusterName}/services/{serviceName}/dependents` and
`/api/v1/clusters/{clusterName}/services/{serviceName}/dependency-impact`.
Stop/Restart confirmation is bound to the current impact revision and exact
provider/action. Re-read impact if another consumer changes.
+
+Persist launch/retry IDs before submission. Following a timeout, read the
original resource before deciding whether to retry; retain an immutable retry
identity for the same attempt. An acknowledged deployment later returning 404
must not trigger a replacement launch.
+
+## Binding Phases {#binding-phases}
+
+| Phase | Operator interpretation |
+| --- | --- |
+| `PREVIEWED` | The binding has not established provider preparation. |
+| `PROVIDER_PREPARING` | Provider work is in progress; inspect its associated
request. |
+| `PROVIDER_PREPARED` | Preparation is available; consumer installation and
verification still have gates. |
+| `ZOOKEEPER_HANDOFF_RECONCILING` | Follow the specific ZooKeeper handoff
reconciliation; do not treat it as ready. |
+| `CONSUMER_VERIFYING` | Current client, identity and connectivity evidence is
being collected. |
+| `READY` | Binding readiness is established for the current approved inputs;
deployment completion is a separate observation. |
+| `STALE` | Approved inputs/evidence no longer match current provider or
consumer state; review changes. |
+| `FAILED` | Inspect failure details and permitted retry actions. |
+| `FENCING_UNCERTAIN` | Existing operation ownership cannot be established
safely; investigate before further mutation. |
+| `DETACHING`, `RETIRED`, `DETACHED`, `TOMBSTONED` | Retirement/detach
lifecycle phases; none imply automatic data deletion or permission to restart
the old dependency. |
+
+Use returned capabilities with the phase. A phase name alone is not a
substitute for topology, snapshot, identity and permission checks.
+
+## Recovery Cases {#recovery-cases}
+
+| Symptom or exact code | Inspect | Recovery |
+| --- | --- | --- |
+| Installer refresh or lost create response | Original draft UUID, owner,
revision and saved cluster association. | Resume the original draft; re-enter
requested secrets. Do not adopt a same-name cluster without the association. |
+| Workflow revision conflict | Latest saved scope/revision and another active
editor. | Reload the authoritative checkpoint, review differences, then submit
current edits. |
+| `DEPENDENCY_OPERATION_STALE` | Current operation, row version, snapshot and
epoch. | Reload; preview again when inputs changed. Do not replay an old
approval against new state. |
+| `DEPENDENCY_VERSION_UNSUPPORTED` | Both active repository records and
resolved version metadata. | Select a compatible provider or correct
repositories; do not bypass the validator. |
+| `DEPENDENCY_SECURITY_MISMATCH` or `CROSS_REALM_NOT_SUPPORTED` |
Consumer/provider security modes and realms. | Use a supported topology; do not
copy provider keytabs to bypass the mismatch. |
+| `DEPENDENCY_CONSUMER_NOT_READY` | Every required daemon host's package,
config, credentials and verification evidence. | Repair the failing
prerequisite and use the offered preparation/verification action. |
+| `DEPENDENCY_NAMENODE_RPC_FAILED` or `DEPENDENCY_DATANODE_READ_WRITE_FAILED`
| Configured endpoints, network, identity and exact structured probe result. |
Correct the reported cause, then reverify the affected current plan. |
+| `DEPENDENCY_ZOOKEEPER_SESSION_FAILED` or
`DEPENDENCY_ZOOKEEPER_AUTHORIZATION_FAILED` | Ensemble connectivity, client
identity and private-znode policy. | Correct connectivity/authorization and
follow the supported verification path. |
+| `DEPENDENCY_FENCING_UNCERTAIN` | Persisted operation and provider ownership
records. | Preserve uncertain state and obtain operator investigation; never
delete journals to force success. |
+| Deployment `UNRESOLVED` | Exact deployment history and missing/mismatched
request/task lineage. | Preserve evidence and investigate; retry only if the
Server explicitly permits it. |
+| Provider stop/delete blocked | Current dependents and impact; consumer
stop/detach requirements. | Coordinate maintenance, review the current impact
or retire/detach consumers through supported flows. |
+| One cluster's directory data fails | That cluster's authorization and failed
read. | Retry that scope without discarding successful authorized rows. |
+
+Capture exact cluster, draft, binding, deployment, operation, epoch, request
and task IDs when relevant, plus sanitized structured responses. Logs can help
explain failure but must not establish workflow success. Never include
credentials or raw keytabs in an issue.
+
+## Blueprint Handoff {#blueprint-handoff}
+
+A managed Blueprint declares required dependency types through its settings:
+
+```json
+{
+ "settings": [
+ {
+ "managed_dependencies": [
+ {"consumer_service": "HBASE", "dependency_type": "HDFS"},
+ {"consumer_service": "HBASE", "dependency_type": "ZOOKEEPER"}
+ ]
+ }
+ ]
+}
+```
+
+Provision with `provision_action: PREPARE_ONLY`, wait for actual host
placement and topology configuration, then preview the complete HBase
selection, apply reviewed configuration, approve the exact binding fingerprints
and launch a durable deployment with exact targets. Provider IDs and
credentials do not belong in the reusable template. The ordinary local
Blueprint path retains its default actions.
+
+This is the handoff contract, not a complete provisioning payload. Use the
[Blueprint
implementation](https://github.com/apache/ambari/blob/fc07b5cb873dc154c48349085494e664baf6b9d1/ambari-server/src/main/java/org/apache/ambari/server/controller/dependencies/ManagedDependencyBlueprintPlan.java)
and the [general Blueprint guide](../ambari-design/blueprints/index.md) when
building an integration.
+
+## Upgrade And Acceptance Work {#upgrade-and-acceptance-work}
+
+Back up the shared database and Server configuration before an upgrade.
Validate exclusive host ownership and the scoped-workflow/dependency schema
migration. Do not “repair” duplicates by deleting membership rows without
establishing the correct owner.
+
+Before relying on a deployment, verify two-cluster host and permission
isolation, two-tab navigation, exact draft recovery, per-host managed readiness
and the provider maintenance paths you will use. Secure installations
additionally need real KDC/credential tests. Exercise network loss and Server
restart using saved operation IDs.
+
+Still-needed release documentation includes the final artifact/tag matrix,
supported upgrade/database combinations, real-KDC results, managed
detach/data-retention evidence, and failure-injection/broker-revocation
results. Add those only after the corresponding tests run; the historical
source review is not a substitute.
diff --git a/versioned_docs/version-3.1.0/release-baseline.md
b/versioned_docs/version-3.1.0/release-baseline.md
index d971ee4..1cbf306 100644
--- a/versioned_docs/version-3.1.0/release-baseline.md
+++ b/versioned_docs/version-3.1.0/release-baseline.md
@@ -26,6 +26,7 @@ limitations under the License.
| Previous release source tag | `release-3.0.0`,
`3acb048b3f6e209d6d1e5ac54efcbd30f1b25c57` |
| Community trunk reviewed on 2026-09-07 |
`94c6389a96b38bccef0b6a08269481a086b63ca1` |
| Monitoring target baseline, PR #4182 |
`4e95d2e33493ac934d7d98a14a81d86c0f1bc0c4` |
+| Multi-cluster follow-up reviewed on 2026-09-22 |
`fc07b5cb873dc154c48349085494e664baf6b9d1`, including AMBARI-26656 / PR #4216 |
| Maven development version in the reviewed trunk | `3.1.0.0-SNAPSHOT` |
For this documentation, PR #4182 is included in the intended 3.1.0 feature
baseline. A release candidate must contain the selected community changes and
monitoring implementation together; a reference SHA in this table is not an
instruction to replace newer community work with an older feature branch.
@@ -66,6 +67,12 @@ The React parity baseline distinguishes implementation,
static comparison, and r
Documentation build and browser checks validate this website's routes,
translations, labels, and assets. They do not execute an Ambari cluster
upgrade, Maven/RPM production build, or monitoring failure drill.
+## Multi-cluster Follow-up {#multi-cluster-follow-up}
+
+The [multi-cluster guides](./multi-cluster/architecture.md) use the newer
pinned trunk revision above for cluster isolation, durable wizard recovery,
Admin management and managed HBase dependencies. This is a focused source
follow-up, not a rerun of the original whole-release review or a fresh RPM
acceptance run.
+
+The guides distinguish final packaged independent-cluster evidence from the
earlier managed-HBase deployment with overlays. They also document the
remaining real-KDC, detach/data-retention, fault-injection and
broker-revocation gates. The [operations
guide](./multi-cluster/operations.md#upgrade-and-acceptance-work) lists the
evidence still needed before publishing final support claims.
+
## Before Publishing A Release {#before-publishing-a-release}
Update this baseline after the release candidate is selected. Record final
source tags, signed artifact/checksum locations, package target matrix,
supported upgrade paths, test results, and the release vote outcome. Only then
replace the preview designation with the released version.
diff --git a/versioned_docs/version-3.1.0/release-notes.md
b/versioned_docs/version-3.1.0/release-notes.md
index a0ff375..118e003 100644
--- a/versioned_docs/version-3.1.0/release-notes.md
+++ b/versioned_docs/version-3.1.0/release-notes.md
@@ -47,6 +47,12 @@ Monitoring uses the new datasource and dashboard model.
Legacy AMS/Ganglia widge
Default entry and packaging:
[#4198](https://github.com/apache/ambari/pull/4198). See the [React user
guide](./frontend/react-ui.md) for workflow coverage and acceptance boundaries.
+### Isolated Multi-cluster Management {#multi-cluster-management}
+
+One Ambari Server can manage independent clusters with exclusive host
ownership, explicit cluster URLs, scoped permissions and recoverable
installation drafts. Global cluster/service directories and Admin inventory
make ownership visible. New HBase deployments can optionally use managed HDFS
and ZooKeeper providers through approved snapshots, private namespaces and
persistent readiness checks.
+
+Implementation: [AMBARI-26656 /
#4216](https://github.com/apache/ambari/pull/4216). See the
[architecture](./multi-cluster/architecture.md), [usage
guide](./multi-cluster/getting-started.md), [HBase compatibility
limits](./multi-cluster/managed-dependencies.md) and [recovery
runbook](./multi-cluster/operations.md). Independent-cluster and
shared-provider evidence have different qualification boundaries; neither adds
Server high availability.
+
### Java Baseline And Independent JDK Selection {#java-baseline}
Source builds require **JDK 17 and Maven 3.9.x**, enforced by Maven. Shared
dependency management updates the Spring/Spring Security, Jetty, Jersey, Guice,
logging, persistence, and Jakarta API foundations. These changes also require
reviewing custom Java extensions and their transitive dependencies; replacing
the JDK alone is not a complete migration.
diff --git a/versioned_sidebars/version-3.1.0-sidebars.json
b/versioned_sidebars/version-3.1.0-sidebars.json
index ddf2764..c4d5d92 100644
--- a/versioned_sidebars/version-3.1.0-sidebars.json
+++ b/versioned_sidebars/version-3.1.0-sidebars.json
@@ -25,6 +25,17 @@
"quick-start/mailing-list"
]
},
+ {
+ "type": "category",
+ "label": "Multi-cluster Management",
+ "collapsed": false,
+ "items": [
+ "multi-cluster/architecture",
+ "multi-cluster/getting-started",
+ "multi-cluster/managed-dependencies",
+ "multi-cluster/operations"
+ ]
+ },
{
"type": "category",
"label": "Monitoring",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
