v3.10版本升级指引

[breezelxp]

v3.10版本升级指引

1. 概述

v3.10版本是一个大的迭代版本。首先，解决了低版本中在模型实例管理中存在的2个关键问题:

• 模型实例唯一管理；
• 模型实例存储的性能问题；

此外，随着产品形态的演进，对部分产品形态做了调整。主要如下：

• 调整了主机快照数据的管理模型，bk-cmdb将只采集管理静态主机数据信息，动态信息的管理能力将由蓝鲸监控来承载。
• 升级了事件服务能力。下线了原有的"事件订阅"产品形态，事件的管理能力，由现在的"事件Watch"功能来承载

最后，原生支持了"蓝鲸监控"的自定义上报能力，可将CMDB系统内的服务异常运行状态实时上报蓝鲸监控，并进行告警。

由上可知，在由低版本的bk-cmdb升级到v3.10版本时，需要大家仔细、深入的了解这个**"大版本"**的产品形态变化、影响面、做好全面的升级评估后，才能进行真正的版本升级。

由于本次升级涉及到数据的升级，所以需要**"停服"**升级。

接下来，将分别介绍一下这个版本里主要的产品形态调整的背景，以及在升级过程中需要关注的事项。

2. 重大调整(Breaking Change)

2.1 通用模型实例

2.1.1 背景

低版本在模型实例管理中存在以下2个方面的问题：

• 唯一管理：
  在模型实例中，可以多维度的标识一个资源的唯一性；比如在主机中，固资号可以唯一标识一台主机，而内网IP与云区域也可以唯一的标识一台主机。在之前的版本中，由于各种原因是通过逻辑层的校验去处理这种“唯一”的数据，来保证数据的唯一性。但这存在几个问题：
  (1) 模型实例数据的唯一性没法从根本上保证，在高并发的场景下，可能会出现唯一数据不唯一的问题。
  (2) 模型实例数据的创建、更新效率低，无法满足高并发、低延迟的操作需求。系统的稳定性和负载能力较差。
  (3) 参与模型实例唯一校验的字段没有进行规范化的管理，使得一些不合理的字段也可以参与唯一校验。

• 数据存储：

  以前通用模型实例的数据集中存储在同一个表中，这种方式在管理小体量的数据时，降低了数据的管理和维护成本。但是，随着CMDB纳管的资源数量以数量级的力度增加时，就会带来几个问题：

  (1) 单模型实例查询效率低；

  (2) 唯一的管理只能在逻辑层去管理，也存在上面说的一些问题；

  (3) 数据层面横向扩展难、管理难；

2.1.2 能力升级

由于以上两个问题的存在，v3.10版本对模型实例与关系相关的的产品形态、功能管理、数据存储等进行了全面的梳理；并结合后续bk-cmdb对资源数据的管理需求增长的需求，对通用模型实例与关系管理的后台架构进行了调整，并对产品侧做了一些调整、优化。主要体现在以下几个方面：

• 存储架构：

  将通用模型实例的存储结构，由混合集中存储调整为按**"模型+租户"**两个维度进行拆分存储。通过对底层存储框架的升级，在同一个开发商下，一个模型就有一个独立的模型实例及实例关系存储表。通过这种方式可以大大提供模型实例的管理能力，提高模型实例的管理读写能力。此外，在可预见的将来，这种存储框架的升级为后续更大体量的数据管理能力打下了基础，使得整个系统在DB层面能够进行横向扩展。

• 唯一管理：

  首先，通过对底层存储框架的升级，为调整模型实例唯一校验的管理方案打下了基础。使得系统可以摆脱"在逻辑层保证唯一"的管理方式，调整为在DB层面利用"唯一索引"的能力进行唯一的管理。降低了管理的复杂程度，同时能够保证数据的唯一性；此外，也使得在数据的"写"性能方面得到了数量级的提升。

  其次，规范了对能够参与唯一校验模型字段的管理，抛弃原有的粗放的管理方式。新的管理方式，对单模型字段的唯一索引和组合模型字段的唯一索引进行了细化，力求在满足用户需求的基础上，帮助用户更合理、有效的管理"唯一校验"的规则。调整后的模型字段唯一字段管理规则详情见这里，建议仔细了解下。

  再次，为了规范、统一用户对"唯一"的认识，更好的管理实例数据的唯一性。**"下线"**了原有版本中支持的"模型实例字段'空值'不参与唯一校验"的特性。主要原因是：(1)在唯一这个层面，'空值'也是值。如果这个字段要参与唯一校验，就应该有实际的值。(2) 不同的人对'空值'的理解不一致；而且不同的数据类型对'空值'的定义也不同。移除这个特殊的'空值'唯一校验，可以统一产品形态规则，统一认识，督促用户合理的规划、使用、管理资源的唯一数据。

以上是关于模型实例管理相关的主要调整，当然实际调整的内容比这个要复杂、困难的多，这里做了简化描述。但是基于以上2点的描述，我们可以看到在这次升级需要对原有数据进行升级、并进行规范化的数据梳理、管理。

2.1.3 升级必看

• 升级前准备
  基于2.1.2的描述，模型实例的唯一校验规则进行了调整。所以需要用户在升级前规范存量的模型实例数据，主要为：
  （1）盘点是否有使用'空值'参与唯一校验的规则，如上所述，该形态已经不再支持。如果有，需要用户根据自己的使用场景，去掉或者调整该规则，同时需要对现有的存量数据进行盘点，将这些参与'唯一校验'空值校验的实例字段值补充对应的数据。只有补充了对应的值，才能进行正常的升级操作；否则一定会升级失败。

  （2）盘点是否有不满足唯一校验管理字段规则的（具体见这里）。如有，需要按需进行调整或者删除。

  （3）盘点是否有不满足唯一校验的数据是否存在，如有，需要进行修复处理，在满足唯一校验规则的情况下，才可以进行正常的升级流程，否则版本升级过程一定会失败。

  （4）盘点是否有没有进程关系的进程数据存在，如有，需要进行修复处理，在满足进程都有进程关系的情况下，才可以进行正常的升级流程，否则版本升级过程一定会失败。

  为了方便大家进行升级前的数据检查工作，我们开发了一个小工具，方便用户在升级前进行数据的检查工作。这个工具，随包发出，在bin目录下。

  在升级前，可以将现网DB数据导出，在测试环境中利用bin目录下的too_ctl工具的migrate-check命令对数据进行校验，具体使用方式为：

  1. 对全部数据进行校验，包括唯一校验规则和无进程关系的进程数据的校验，会输出第二个和第三个命令的汇总结果：

  ./tool_ctl migrate-check --check-all=true --mongo-uri={mongo URI} --mongo-rs-name={rsname}

  2. 仅校验唯一校验规则，输出不符合规则的数据：

  ./tool_ctl migrate-check unique --mongo-uri={mongo URI} --mongo-rs-name={rsname}

  3. 仅校验无进程关系的进程数据，输出不符合规则的数据：

  ./tool_ctl migrate-check process --mongo-uri={mongo URI} --mongo-rs-name={rsname}

  4. 【可选】如果确认第三个命令输出的没有进程关系的进程数据全部都可以清理，可以用这个命令清理这些进程数据。如果不可以，则需要手动处理这些进程数据：

  ./tool_ctl migrate-check process --clear-proc=true --mongo-uri={mongo URI} --mongo-rs-name={rsname}

  执行校验唯一校验规则的命令后，会自动对所有模型的唯一校验规则进行全量校验，对于不符合规则的数据，会直接进行报错提示。用户根据具体的报错信息，处理对应的数据或者规则，直到不再报任何错误。

  执行校验无进程关系的进程数据的命令后，会自动对所有进程数据进行全量校验，对于不符合规则的数据，会直接进行报错提示。用户需要根据具体的报错信息，确认是否可以清理，如果可以，则需要执行清理这些进程数据的命令，如果不可以，则需要处理这些数据直到不再报任何错误。

  **当且仅当所有的校验都通过时**才可以进行正常的升级流程。

• 接口适配

  为了适配后台的存储架构调整，对现有的几个ESB接口进行了调整。

  参数调整的接口：

  主要是对入参进行了调整，新增了必填入参字段:bk_obj_id。涉及到的接口列表如下，ESB openpaas的对应版本为v2.12.17。

  • delete_instance_association
  • delete_related_inst_asso
  • find_instance_association
  • search_related_inst_asso

  下线的接口：

  • search_inst_by_object
  • find_instance_association

  若用到这些接口，在进行升级前，需要对这些接口进行适配，避免升级后，这些接口无法正常调用。

  除了对以上接口的调整外，v3.10版本，又新增了一批模型实例与关系的新查询接口，这些接口在性能上比原有的查询接口更优一些。具体接口列表如下，ESB openpaas的对应版本为v2.12.17。

  • count_instance_associations
  • count_object_instances
  • search_instance_associations
  • search_object_instances

  大家可以根据自己的需求进行接口迁移。

• 数据迁移

  由于上文所述的存储方式的调整，在实际升级到v3.10版本的过程中，会将原有的通用模型实例数据进行迁移，迁移到新的实例表中。为了保证在迁移过程中模型实例数据的准确、完整性。在版本升级过程中，需要进行停服。数据升级迁移的时长受数据量、DB等环境因素的影响，若想具体了解实际的数据迁移时长，可以将数据导出在测试环境中进行测试、验证。

• 验证

  待升级流程执行完成后，观察cmdb_adminserver的日志文件，如果cmdb_adminserver.ERROR日志文件没有关于表或者索引相关的错误，则表明整个数据升级完成，未出现数据异常。否则，需要根据具体的错误信息，调整唯一校验规则，或者修复相关的异常数据。

2.2 事件管理

2.2.1 背景

原有的事件订阅订阅业务形态，是一种基于推送机制的事件管理方式，存在诸多的问题：

• 数据幂等

  接收方的数据幂等无法进行有效的进行保证。服务端无法真实的知道客户端是否真的拿到事件数据，无法进行有效的重试操作；客服端在拿到事件后，无法有效保证事件处理的后续流程的幂等，或者说成本非常高。

• 数据补偿

  基于推送的方式，使得客户方无法根据自己的消费场景，进行数据补偿、回溯。事件丢了就只能丢了，数据的可靠性无法保证。

• 消费能力不一致

  由于每个消费者对事件的消费能力不一致，使得服务端对每个客户端的数据进行有效管理，同时大幅提升了系统的复杂程度和稳定性。不利于系统的稳定、长期运行。

基于以上原因，产品侧下线了原有的事件订阅所有相关产品形态，提供一种新的服务形态来满足用户对资源事件变更感知的需求。

根据用户实际的应用场景，结合事件订阅服务存在的问题，v3.10版本提供一种能够满足用户对事件数据服务的一致性、可靠性、稳定性更好的服务形态，同时能够屏蔽客户端的能力差异。

2.2.2 能力升级

v3.10版本提供一种基于拉取机制的事件watch服务，事件的订阅方(客户端)可以根据自己的需求场景，进行数据的重试、回溯、控制事件拉取频率等，满足各用户差异化的需求场景，同时屏蔽用户差异化的消费能力。使得事件管理服务更加灵活、稳定、高效。事件watch服务由ESB接口resource_watch提供，该功能的主要特性如下：

• 在有限的时间内（目前为3小时,可能会调整，请勿依赖此时间）为用户提供高可用的数据变更watch服务。

• 在有限时间内，用户可以根据自己上一次事件的cursor(游标)进行事件回溯或者追数据，适用于异常数据回溯，或者系统变更进行数据补录。

• 支持根据时间点进行变更数据回溯，支持根据游标进行变更数据回溯，支持从当前时间点进行数据变更watch。

• 支持根据事件类型进行watch的能力，包括增、删、改。事件中包含全量的数据。

• 支持主机与主机关系数据变化的事件watch能力。

• 采用短长链的设计，当用户通过游标进行事件watch时，如果没有事件，则会保持会话连接，在20s内有事件变更则直接直接将事件推回。避免用户不断请求，同时保证用户能及时的拿到变更的数据。

• 支持批量事件watch能力，提升系统吞吐能力。

• 支持定制关注的事件数据字段，满足用户轻量级的watch需求。

目前支持watch的资源类型如下：

• host：主机详情变更事件
• host_relation：主机的关系变更事件
• biz：业务详情变更事件
• set：集群详情变更事件
• module：模块详情变更事件
• process：进程详情变更事件
• object_instance: 模型实例详情变更事件

该功能的定位是为平台级的服务提供事件订阅服务，所以在资源的权限管理上，以资源为管理维度，不再关注具体的资源所属关系，如主机所属的业务、集群所属的业务等。

2.2.3 升级必看

如果有服务使用了原有的"事件订阅'服务，由于"事件订阅服务"在该版本将全面下线，需要将原有订阅的资源事件迁移到新的形态上，即使用ESB的resource_watch接口循环拉取资源的事件数据，感知资源数据的变化。

此外，由于GSE的gse_syncdata服务默认在部署时会注册订阅bk-cmdb的主机身份事件，所以在升级bk-cmdb到v3.10版本前，需要将GSE的版本升级到v1.7.9+，否则在bk-cmdb升级到v3.10后会导致GSE的gse_syncdata服务无法正常的启动或者重启。

下线的原有事件订阅接口列表如下：

• search_subscription
• subscribe_event
• unsubcribe_event
• update_event_subscribe

2.3 主机快照

2.3.1 背景

主机采集的数据可以分为两类：

• 相对静态的数据：如操作系统类型，hostname，系统版本等。
• 动态数据：如实时的CPU,Mem,Disk实用率等。

期中动态数据属于监控范畴，在bk-cmdb中只看某一时刻的瞬时动态数据对用户提供的价值有限。所以，在产品形态上，bk-cmdb保留了静态数据的采集管理能力，移除了对动态数据的采集管理能力。将用户的动态数据管理需求全部迁移到"蓝鲸监控平台"去承载。

2.3.2 能力升级

调整了bk-cmdb的主机静态数据管理形态，调整了静态数据上报的协议、规则 ，同时依赖新的主机数据采集插件bkmonitorbeat进行主机的静态数据采集，大幅提升了主机静态数据的采集、管理能力。

此外，兼容了原有的basereport采集插件采集。但建议用户在将bk-cmdb升级到v3.10后，按排计划逐步升级basereport插件到bkmonitorbeat。bk-cmdb将会在2021年10月份下线对basereport的兼容逻辑。

2.3.3 升级必看

受上调整影响，下线了原有的主机快照相关的ESB接口，具体如下：

• find_host_snapshot_batch

如若你使用了以上接口，请移步"蓝鲸监控平台"查询相关数据。

2.4 自定义监控事件上报

v3.10版本新增了对接蓝鲸监控平台自定义事件上报的功能，使得bk-cmdb在运行过程中的一些重要的事件能够以事件告警的方式通知到用户。该功能的配置项在bk-cmdb的common.yaml配置文件中进行配置，具体的配置项内容如下：

# 监控配置，monitor配置项必须存在
monitor:
  # 监控插件名称，有noop，blueking， 不填时默认为noop
  pluginName: noop
  # 是否开启监控
  enableMonitor: false
  # 当使用blueking监控插件时，上报数据所需要的数据通道标识,如1500000
  dataID: 0
  # 采集数据后能够缓存的队列长度，设置范围为1～1000, 默认为100
  queueSize: 100
  # 采集数据用的gsecmdline命令绝对路径，默认版本需要大于等于2.0.2，默认路径： 
__BK_GSE_AGENT_HOME__/plugins/bin/gsecmdline
  gsecmdlinePath: __BK_GSE_AGENT_HOME__/plugins/bin/gsecmdline
  # 对应的domainsocket绝对路径，默认路径：__BK_GSE_AGENT_HOME__/agent/data/ipc.state.report
  domainSocketPath: __BK_GSE_AGENT_HOME__/agent/data/ipc.state.report
  # 用于对数据上报进行频率控制和限流
  # qps的设置范围为1～50，默认值为10
  # burst的设置范围为1～100，默认值为20
  rateLimiter:
    qps: 10
    burst: 20

请用户在将bk-cmdb升级到v3.10版本后，在蓝鲸监控配置相关的自定义事件上报服务，并在bk-cmdb打开此配置项。目前上报的异常事件主机包括通用模型实例的索引异常事件，事件watch异常事件等。这些都是bk-cmdb正常运行时核心服务，在条件允许的情况下，请用户务必配置使用此服务。

此功能依赖cmdb部署的机器安装有gse agent和gsecmdline命令。

3. 版本依赖

bk-cmdb 升级到v3.10对周边系统、组件的依赖明细如下：

组件	版本依赖	是否必须
ESB OpenPaas	>= v2.12.19	是
GSE	>= v1.7.9	是
IAM	后台> v.1.8.10；SaaS>v1.4.11	是
bkmonitorbeat(主机快照采集，basereport替代版)	>=v1.13.98	否
gsecmdline	>=v2.0.2	是
Monstache	>= v.6.7.5	是
Elasticsearch	>= v.7.0.0	是

Monstache的部署方式有调整，具体请见这里。

重要提醒：

用户将bk-cmdb升级到v3.10后，请排期将主机快照采集插件由basereport升级到bkmonitorbeat，bk-cmdb将会在2021年10月份下线对basereport的兼容逻辑。届时若未升级到bkmonitorbeat，将无法正常采集主机的静态数据。

[Hyakusenrenma]

镜像版还会更新嘛

[breezelxp]

@Hyakusenrenma v3.10版本正式发布后会更新镜像

[lvhaoran88]

当前再使用3.9.27，可不可以直接升到3.10？

[breezelxp]

当前再使用3.9.27，可不可以直接升到3.10？

可以的，按正常的升级流程走可以直接进行升级。

[lvhaoran88]

centos7平台 make ui 总是卡 [email protected] install: node build.js || nodejs build.js。请问怎么解决

[lvhaoran88]

centos7平台 make ui 总是卡 [email protected] install: node build.js || nodejs build.js。请问怎么解决
已解决
npm i node-gyp -g
npm i node-sass -g

[wjyfelen]

开源版本monstache以及monstache-plugin.so插件文件:
monstache-plugin.so.zip
monstache.zip

[wcy00000000000000]

如果migrate iam的时候出现如下报错：register system failed, code: 1901400, msg:bad request:json decode or validate fail, err=[0]: Key: 'resourceTypeSerializer.Name' Error:Field validation for 'Name' failed on the 'required' tag，请将coreservice升级并重启为对应的3.10版本后，重新执行migrate iam操作即可

[ganzaofang]

./tool_ctl  migrate-check --check-all=true  --mongo-uri="mongodb://$BK_CMDB_MONGODB_USERNAME:[email protected]:27017/cmdb" --mongo-rs-name="rs0"

[fox-says]

@Hyakusenrenma v3.10版本正式发布后会更新镜像

请问镜像版目前是哪个版本的？？

[xinkuanet]

3.10.18版本，MongoDB用的4.2.8，系统日志一直报下面这些
fail to watch children for path(/cc/services/endpoints/auth), err:zk: node does not exist
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/datacollection), err:zk: node does not exist
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/datacollection), err:zk: node does not exist
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/auth), err:zk: node does not exist
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/auth), err:zk: node does not exist
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/datacollection), err:zk: node does not exist
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/auth), err:zk: node does not exist
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/datacollection), err:zk: node does not exist
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/datacollection), err:zk: node does not exist
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/datacollection) is not exist, will watch after 5s
children node(/cc/services/endpoints/auth) is not exist, will watch after 5s
fail to watch children for path(/cc/services/endpoints/auth), err:zk: node does not exist

可是zookeeper都安装部署好了，这是为什么

[dujiaoyang]

开源版本monstache以及monstache-plugin.so插件文件: monstache-plugin.so.zip monstache.zip