SkyWalking OAP 动态配置：基于 Kubernetes ConfigMap 的动态配置中心实践与源码解析

可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载本篇指南围绕 SkyWalking OAP 的 Kubernetes ConfigMap 动态配置实现k8s-configmap展开讲解如何以 ConfigMap 作为动态配置中心DCC在不重启 OAP 的情况下动态下发与热更新告警规则、慢 SQL 阈值、Apdex 阈值、端点分组规则等配置。读者阅读后可以掌握application.yml中相关参数的含义与配置方法、Single/Group 两类配置在 ConfigMap 中的组织与存储方式并能通过源码理解其底层同步机制与实现原理。动态配置机制概述SkyWalking OAP 的大部分配置通过application.yml和操作系统环境变量设置但部分配置支持由上游管理系统动态下发Dynamic Configuration。该功能依赖上游服务因此默认处于关闭状态需要通过configuration.selector显式启用。在 dynamic-config.md 中可以看到SkyWalking 支持两类动态配置Single Configuration单一配置一个配置键对应一个配置值逻辑结构为{configKey}:{configValue}Group Configuration分组配置一个配置键对应一组子配置项逻辑结构为{configKey}: |{subItemKey1}:{subItemValue1} ...。Kubernetes ConfigMap 是官方支持的动态配置中心实现之一除此之外还支持 Zookeeper、Etcd、Consul、Apollo、Nacos 以及内置的 Dynamic Configuration ServiceDCS。对于已经运行在 Kubernetes 集群中的 SkyWalking 部署直接复用 ConfigMap 作为配置中心可以避免引入额外的中间件依赖。启用 ConfigMap 动态配置在 OAP 的application.yml的configuration段中进行如下配置configuration: selector: ${SW_CONFIGURATION:k8s-configmap} # [example] oap-server/server-configuration/configuration-k8s-configmap/src/test/resources/skywalking-dynamic-configmap.example.yaml k8s-configmap: # Sync period in seconds. Defaults to 60 seconds. period: ${SW_CONFIG_CONFIGMAP_PERIOD:60} # Which namespace is configmap deployed in. namespace: ${SW_CLUSTER_K8S_NAMESPACE:default} # Labelselector is used to locate specific configmap labelSelector: ${SW_CLUSTER_K8S_LABEL:appcollector,releaseskywalking}各参数含义如下参数环境变量默认值说明selectorSW_CONFIGURATIONnone不启用选择动态配置中心实现这里必须为k8s-configmapperiodSW_CONFIG_CONFIGMAP_PERIOD60配置同步周期秒OAP 会按此周期从 ConfigMap 拉取并比对配置namespaceSW_CLUSTER_K8S_NAMESPACEdefaultConfigMap 所属的 Kubernetes 命名空间即下文{namespace}labelSelectorSW_CLUSTER_K8S_LABELappcollector,releaseskywalking标签选择器用于定位哪些 ConfigMap 会被选中即下文{labelSelector}其中{namespace}是 ConfigMap 所属的 k8s 命名空间{labelSelector}用于标识哪些 ConfigMap 会被选中。注意namespace与labelSelector两项的默认环境变量名沿用了集群模块的命名SW_CLUSTER_K8S_NAMESPACE、SW_CLUSTER_K8S_LABEL说明在典型的 SkyWalking 集群部署场景下ConfigMap 通常与 OAP 集群位于同一命名空间、使用同一套标签体系便于统一管理。例如以下两个 ConfigMap 都会被上述配置选中apiVersion: v1 kind: ConfigMap metadata: name: skywalking-dynamic-config namespace: default labels: app: collector release: skywalking data: configKey1: configValue1 configKey2: configValue2 ...apiVersion: v1 kind: ConfigMap metadata: name: skywalking-dynamic-config2 namespace: default labels: app: collector release: skywalking data: configKey3: configValue3 ...底层实现原理源码级k8s-configmap模块位于 oap-server/server-configuration/configuration-k8s-configmap共包含 4 个核心类整体工作链路为Provider 启动校验 → Informer 监听 ConfigMap → WatcherRegister 周期拉取 → configuration-api 分发变更。模块入口与参数校验ConfigmapConfigurationProvider.java 是模块的 Provider 入口name()返回k8s-configmap与application.yml中的selector值对应在initConfigReader()中首先校验labelSelector与namespace是否为空任一为空都会抛出ModuleStartException(the settings of configmap configuration is illegal.)拒绝启动这解释了为什么这两个参数是必填项校验通过后构建ConfigurationConfigmapInformer与ConfigmapConfigurationWatcherRegister并返回。配置项的载体是 ConfigmapConfigurationSettings.java包含namespace、labelSelector、period三个字段分别对应application.yml中的同名配置。Informer 监听机制ConfigurationConfigmapInformer.java 负责与 Kubernetes API Server 交互通过SharedKubernetesClient来自 library-kubernetes-support 模块获取共享的 fabric8 Kubernetes 客户端使用configMaps().inNamespace(namespace).withLabelSelector(labelSelector).inform()建立Informer 监听即以 watch 机制持续跟踪目标命名空间下符合标签选择器的所有 ConfigMapconfigMapData()方法通过Lister列出所有被监听的 ConfigMap并把它们的data字段合并到同一个MapString, String中返回。从源码可以看出多个 ConfigMap 的 data 会被合并为一张全局键值表因此动态配置可以分散存放在 1 个或多个 ConfigMap 文件中只要它们的标签匹配labelSelector即可。周期同步与读取逻辑ConfigmapConfigurationWatcherRegister.java 继承自 FetchingConfigWatcherRegister.java后者是周期性拉取型配置监听器的通用基类start()会创建一个名为ConfigWatcherSync的守护线程以scheduleAtFixedRate方式按period默认 60 秒周期执行configSync()configSync()分别调用singleConfigsSync()与groupConfigsSync()从配置中心读取全部已注册 watcher 关心的配置键并与当前值比对、触发变更通知从registerConfigChangeWatcher的逻辑可以看到watcher 按WatchType.SINGLE/WatchType.GROUP分表注册重复注册同一配置键会抛出IllegalStateException。ConfigMap 实现只需覆写两个抽象方法readConfig(SetString keys)对每个关心的配置键从合并后的 ConfigMap data 中取值组装成ConfigTablereadGroupConfig(SetString keys)对每个分组配置键遍历合并后的 data凡是以key .开头的条目都被归入该分组并以key.length() 1截取子项键名。例如core.default.endpoint-name-grouping-openapi.customerAPI-v1会被解析为分组core.default.endpoint-name-grouping-openapi下的子项customerAPI-v1。这一前缀匹配规则是整个分组配置机制的核心也正是下一节中 ConfigMap data 键命名规范的设计依据。测试验证模块自带的单元测试 ConfigmapConfigWatcherRegisterTest.java 覆盖了多个场景当 Informer 数据为空或不可用时readConfig/readGroupConfig仍返回包含全部注册键的ConfigTable/GroupConfigTable值为null或子项为空即拉不到配置不报错只是保持空值当 Informer 正常工作时readConfig能取到 4 个单配置键的值readGroupConfig能按前缀把分散在多个 ConfigMap 中的 3 个子项customerAPI-v1、productAPI-v1、productAPI-v2聚合到core.default.endpoint-name-grouping-openapi分组下。测试使用的示例数据正是 src/test/resources 下的三个 YAML 文件可当作现成的配置模板参考。配置存储与 ConfigMap 设计动态配置以 ConfigMap 的 data 条目形式存储如上文示例所示。配置可以组织在 1 个或多个 ConfigMap 文件中。Single Config单一配置在configmap.data下使用如下键值结构configKey: configValue例如动态配置项为{agent-analyzer.default.slowDBAccessThreshold}:{default:200,mongodb:50}对应的 ConfigMap 为apiVersion: v1 kind: ConfigMap metadata: name: skywalking-dynamic-config namespace: default labels: app: collector release: skywalking data: agent-analyzer.default.slowDBAccessThreshold: default:200,mongodb:50即data 的键是配置键configKeydata 的值是配置值configValueOAP 按period周期读取并热更新。Group Config分组配置分组配置的data key由配置键与子项键拼接而成用.分隔以标识其属于某个分组configKey.subItemKey1: subItemValue1 configKey.subItemKey2: subItemValue2 ...例如动态分组配置为{core.default.endpoint-name-grouping-openapi}:|{customerAPI-v1}:{value of customerAPI-v1} |{productAPI-v1}:{value of productAPI-v1} |{productAPI-v2}:{value of productAPI-v2}该分组配置可以拆分为 2 个 ConfigMap 存储。第一个 ConfigMap 存放前两个子项apiVersion: v1 kind: ConfigMap metadata: name: skywalking-dynamic-config namespace: default labels: app: collector release: skywalking data: core.default.endpoint-name-grouping-openapi.customerAPI-v1: value of customerAPI-v1 core.default.endpoint-name-grouping-openapi.productAPI-v1: value of productAPI-v1第二个 ConfigMap 存放第三个子项apiVersion: v1 kind: ConfigMap metadata: name: skywalking-dynamic-config2 namespace: default labels: app: collector release: skywalking data: core.default.endpoint-name-grouping-openapi.productAPI-v2: value of productAPI-v2由于 Informer 会把所有匹配标签的 ConfigMap 的 data 合并后再按前缀解析分组因此同一个分组配置的子项可以分布在多个 ConfigMap 中只要它们都满足labelSelectorOAP 就能聚合出完整的组配置。参考测试资源 skywalking-group-dynamic-configmap.example-serviceA.yaml 与 skywalking-group-dynamic-configmap.example-serviceB.yaml可以看到core.default.endpoint-name-grouping-openapi的三个子项customerAPI-v1.yaml、productAPI-v1.yaml、productAPI-v2.yaml正是这样分别存放在两个 ConfigMap 中的且每个子项的值是 OpenAPI 3.0 规范的 YAML 文件内容。支持的动态配置项无论是 Single 还是 Group 配置data中的configKey都必须与 OAP 内已注册的配置键精确匹配否则会被 FetchingConfigWatcherRegister.java 以 WARN 日志doesnt match any WatchType.SINGLE watcher, ignore. 忽略。以下为 dynamic-config.md 中列出的全部受支持配置键。Single 类型配置键Config Key值含义值格式示例agent-analyzer.default.slowDBAccessThreshold慢数据库语句阈值覆盖application.yml中agent-analyzer/default/slowDBAccessThresholddefault:200,mongodb:50agent-analyzer.default.uninstrumentedGateways未接入探针的网关列表覆盖gateways.yml与 uninstrumented-gateways.md 中gateways.yml格式相同alarm.default.alarm-settings告警规则设置覆盖alarm-settings.yml与 backend-alarm.md 中alarm-settings.yml格式相同core.default.apdexThresholdApdex 阈值设置覆盖service-apdex-threshold.yml与 apdex-threshold.md 中service-apdex-threshold.yml格式相同core.default.endpoint-name-grouping端点名称分组规则覆盖endpoint-name-grouping.yml与 endpoint-grouping-rules.md 中endpoint-name-grouping.yml格式相同core.default.log4j-xmllog4j 日志配置覆盖log4j2.xml与 dynamical-logging.md 中log4j2.xml格式相同core.default.searchableTracesTags可检索的 Trace 标签配置覆盖application.yml中core/default/searchableTracesTagshttp.method,http.status_code,rpc.status_code,db.type,db.instance,mq.queue,mq.topic,mq.brokeragent-analyzer.default.traceSamplingPolicy默认与服务维度的采样策略覆盖trace-sampling-policy-settings.yml与 trace-sampling.md 中trace-sampling-policy-settings.yml格式相同configuration-discovery.default.agentConfigurationsConfigurationDiscovery 设置参见 SkyWalking Java Agent 的 configuration-discovery 文档Group 类型配置键Config Key子项键含义值含义值格式示例core.default.endpoint-name-grouping-openapi与 OpenAPI 定义文件相关的服务名例如serviceA若一个服务对应多个文件则为每个文件增加一个子项子项键用.拼接服务名与文件名如serviceA.API-file1、serviceA.API-file2OpenAPI 定义文件内容YAML 格式用于生成端点名称分组规则与 endpoint-grouping-rules.md 中productAPI-v2.yaml格式相同在测试资源 skywalking-dynamic-configmap.example.yaml 中可以看到 Single 类型配置的完整写法agent-analyzer.default.slowDBAccessThreshold使用default:200,mongodb:50这样的行内格式而alarm.default.alarm-settings、core.default.apdexThreshold、agent-analyzer.default.uninstrumentedGateways等包含多行内容的配置则使用 YAML 的|-块标量语法把整段规则文本作为 data 值。这也是把告警规则等结构化配置放入 ConfigMap 时的推荐写法——data 值是整段文件内容的字符串。运行前提与注意事项从实现与配置中可以归纳出以下前提与限制默认关闭动态配置依赖上游服务configuration.selector默认值为none。要启用 ConfigMap 实现必须显式设置selector: ${SW_CONFIGURATION:k8s-configmap}必填参数namespace与labelSelector缺一不可缺失时 OAP 会因ModuleStartException拒绝启动见 ConfigmapConfigurationProvider.java监听范围Informer 只监听namespace指定命名空间内、标签匹配labelSelector的 ConfigMap新创建的符合条件的 ConfigMap 会被自动纳入删除或修改则会反映到下一次周期同步中同步延迟配置变更后OAP 最多在下一个period默认 60 秒周期内完成拉取与热更新并非秒级实时键必须精确匹配ConfigMap data 的键必须与受支持配置键完全一致多余的条目会被忽略Kubernetes 权限从实现看OAP 通过 fabric8 Informer 对目标命名空间的 ConfigMap 执行 list/watch 操作因此运行 OAP 的 ServiceAccount 需要具备对相应 ConfigMap 的读取权限具体权限模型取决于部署时的 RBAC 配置。小结Kubernetes ConfigMap 为 SkyWalking OAP 提供了一种零额外依赖的动态配置中心方案通过namespacelabelSelector圈定配置来源以period周期同步实现配置热更新并借助data 键前缀匹配机制天然支持 Single 与 Group 两类动态配置。配合 dynamic-config.md 中列出的受支持配置项运维人员可以在不重启 OAP 的前提下调整告警规则、慢 SQL 阈值、Apdex 阈值与端点分组规则等关键参数适合已深度使用 Kubernetes 的 SkyWalking 生产部署。赞分享可观测性APM链路追踪指标监控日志分析微服务【免费下载链接】skywalkingAPM, Application Performance Monitoring System项目地址https://gitcode.com/gh_mirrors/sk/skywalking点击查看免费下载相关推荐Apache SkyWalking 动态配置之 Kubernetes ConfigMap 实现原理、配置与实战Apache SkyWalking 动态配置之 Kubernetes ConfigMap 实现原理、配置与实战 导读 Apache SkyWalking OA可观测性后端微服务云原生SkyWalking OAP 动态配置中心接入 Consul 完整指南配置、存储模型与源码实现SkyWalking OAP 动态配置中心接入 Consul 完整指南配置、存储模型与源码实现 本文以 Apache SkyWalking OAP 后端内置的可观测性后端微服务云原生Apache SkyWalking OAP 接入 Apollo 配置中心实现动态配置Dynamic Configuration Apollo ImplementationApache SkyWalking OAP 接入 Apollo 配置中心实现动态配置Dynamic Configuration Apollo Implemen可观测性后端微服务云原生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考