KubeSphere WizTelemetry Data PipelineVector扩展安装与配置实战指南【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere本指南以 KubeSphere 仓库中的 skills/vector/SKILL.md 为核心系统讲解 WizTelemetry Data Pipeline基于 Vector 的数据管道扩展在 KubeSphere 中的安装、配置与运维方法。通过本文你将掌握如何为日志Logging、审计Auditing、事件Events与通知Notification等可观测性数据配置统一的采集、转换与路由管道并将数据稳定写入 OpenSearch。一、扩展定位可观测性数据管道的核心依赖WizTelemetry Data Pipeline 是 KubeSphere WizTelemetry 可观测性平台中基于 Vectorhttps://vector.dev/构建的扩展组件负责对可观测性数据进行采集collect、转换transform与路由route。它在整个可观测性体系中处于“地基”位置——官方文档明确指出它是 Logging、Auditing、Events、Notification 等其他 WizTelemetry 扩展的核心依赖core dependency必须优先安装。从 skills/whizard-logging/SKILL.md 的依赖声明可以看到WizTelemetry Logging 的依赖清单为WizTelemetry Platform Servicewhizard-telemetry必需WizTelemetry Data Pipelinevector必需OpenSearchopensearch必需其中OpenSearch 的 sink 配置endpoints、auth正是由vector扩展提供的。也就是说只要把 Vector 的 OpenSearch sink 配置好上游的 Logging、Events、Auditing、Notification 都可以复用这套连接信息无需重复填写。从 pkg/controller/core/installplan_controller.go 的源码可以看到该扩展的典型安装形态它声明为installationMode: Multicluster其agent组件tag 为agent会被部署到所有被选中的成员集群上而完整扩展tag 为extension部署在宿主集群。二、安装前置条件与三步准备官方文档强调在生成 InstallPlan 之前必须按顺序完成以下所有步骤。Step 1获取可用集群并确认目标集群kubectl get clusters -o jsonpath{.items[*].metadata.name}确定目标集群的规则如果用户在请求中明确指定了目标集群 → 直接使用进入 Step 2如果用户未指定→ 必须向用户确认要部署到哪些集群然后进入 Step 2。确认话术示例Available clusters: host, dev Which clusters do you want to deploy Vector to?Step 2获取 OpenSearch 端点与凭据必须执行如果用户已提供OpenSearch 端点与凭据 → 直接使用进入 Step 3如果用户未提供→ 必须向用户索取以下两项在两者都拿到之前不得进入 Step 3OpenSearch 端点 URL必填示例http://node-ip:30920或https://opensearch.example.com:9200OpenSearch 凭据必填用户名默认admin与密码关于默认端口 30920 与默认账号admin可参考 skills/opensearch/SKILL.mdOpenSearch 扩展默认通过 NodePort30920对外暴露opensearch-cluster-data服务默认用户名/密码为admin/admin。在安装 Vector 前确保 OpenSearch 已经部署且可从所有目标集群访问。Step 3获取 Vector 最新版本若用户未提供kubectl get extensionversions -l kubesphere.io/extension-refvector -o jsonpath{range .items[*]}{.spec.version}{\n}{end} | sort -V | tail -1该命令按语义化版本排序后取出最后一个即最新版本例如1.1.4记录下来供 InstallPlan 使用。三、生成 InstallPlan 安装 Vector 扩展在完成上述三个前置步骤后即可创建 InstallPlan。请注意以下关键约束InstallPlan 的metadata.name必须是vector不得使用其他名称config字段为YAML 格式必须严格按照模板的结构与层级不要添加模板之外的字段也不要修改结构所有占位符必须替换为真实值不允许保留占位符在占位符全部变为真实值之前不要生成 InstallPlan。基础安装模板apiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: vector spec: extension: name: vector version: VECTOR_VERSION # 来自 Step 3 enabled: true upgradeStrategy: Manual config: | agent: sinks: opensearch: auth: strategy: basic user: OPENSEARCH_USER password: OPENSEARCH_PASSWORD endpoints: - OPENSEARCH_ENDPOINT clusterScheduling: placement: clusters: - TARGET_CLUSTERS占位符替换说明占位符来源示例VECTOR_VERSIONStep 3 查询所得1.1.4OPENSEARCH_ENDPOINT用户提供的端点http://node-ip:30920OPENSEARCH_USER用户提供的用户名adminOPENSEARCH_PASSWORD用户提供的密码实际密码TARGET_CLUSTERS用户确认的集群名host,dev创建后执行kubectl apply -f installplan-vector.yaml即可触发安装。安装流程的源码级原理InstallPlan 并不是直接执行安装而是由 KubeSphere 的控制器驱动完成。从 pkg/controller/core/installplan_controller.go 可以看到完整调用链控制器 Watch 到 InstallPlan 后读取对应的ExtensionVersionextension-name-version命名计算目标命名空间未指定时默认为extension-name见 installplan_controller.go对于spec.ClusterScheduling非空的安装控制器会为每个目标集群调用syncClusterSchedulingStatus并分别执行 agent 组件的安装见 installplan_controller.go多集群场景下成员集群上的 Helm release 名称为%s-agent格式agentReleaseFormat即vector-agent见 installplan_controller.go 与 installplan_controller.go宿主集群安装extension标签对应的子图成员集群安装agent标签对应的子图二者通过tags.extension/tags.agent的 Helm overrides 互斥开关控制见 installplan_controller.go。InstallPlan的 Spec 结构定义在 staging/src/kubesphere.io/api/core/v1alpha1/types.go包含extensionnameversion、enabled、upgradeStrategy默认Manual、config与clusterScheduling。其中clusterScheduling.placement支持两种方式——显式列出clusters或使用clusterSelector标签选择器批量匹配集群见 types.go。启用指标导出可选如需将 Vector 自身的指标导出可在config中追加agent.exportMetrics.enabled: trueapiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: vector spec: extension: name: vector version: VECTOR_VERSION # 来自 Step 2 enabled: true upgradeStrategy: Manual config: | agent: sinks: opensearch: auth: strategy: basic user: OPENSEARCH_USER password: OPENSEARCH_PASSWORD endpoints: - OPENSEARCH_ENDPOINT exportMetrics: enabled: true clusterScheduling: placement: clusters: - TARGET_CLUSTERS四、等待部署完成并核对结果应用 InstallPlan 后必须等待部署完成# 在每个集群上等待 Vector Pod 就绪超时 300 秒 kubectl wait --forconditionReady pods -n kubesphere-logging-system -l app.kubernetes.io/instancevector --timeout300s # 核对部署状态 kubectl get pods -n kubesphere-logging-system -l app.kubernetes.io/instancevector部署完成后向用户展示如下摘要Vector 被部署到了哪些集群使用的 OpenSearch 端点Pod 状态Ready/Total。五、配置参数详解Agent 参数参数类型默认值说明agent.rolestringAgent角色标识agent.image.tagstring0.53.0-debianVector 镜像标签agent.resources.requests.cpustring100mCPU 请求量agent.resources.requests.memorystring100Mi内存请求量agent.resources.limits.cpustring2000mCPU 上限agent.resources.limits.memorystring2000Mi内存上限agent.service.portslist见 values.yaml服务端口agent.exportMetrics.enabledboolfalse是否启用指标导出Agent Sinks OpenSearch 参数参数类型必填说明agent.sinks.opensearch.endpointslist是OpenSearch 端点 URL 列表agent.sinks.opensearch.auth.strategystring是认证策略固定设为basicagent.sinks.opensearch.auth.userstring是认证用户名agent.sinks.opensearch.auth.passwordstring是认证密码agent.sinks.opensearch.tls.verifybool否是否开启 TLS 校验默认false配置示例agent: sinks: opensearch: endpoints: - http://node-ip:30920 auth: strategy: basic user: admin password: admin tls: verify: falseDocker Root 目录配置如果节点的 Docker root 目录不是默认的/var/lib需要挂载额外的宿主机路径以便 Vector 正确读取容器日志agent: extraVolumes: - name: docker-root hostPath: path: /path/to/docker type: extraVolumeMounts: - name: docker-root mountPath: /path/to/docker配置对下游扩展的影响sink 凭据复用Vector 安装后其 OpenSearch sink 配置会以 Secret 的形式保存在kubesphere-logging-system命名空间中。这一点在 skills/whizard-telemetry/scripts/generate-config.sh 中有直接体现该脚本通过读取vector-sinksSecretkubectl get secret vector-sinks -n kubesphere-logging-system -o jsonpath{.data.opensearch}来提取端点、用户名与密码并以此为 Logging、Events、Auditing、Notification 等生成对应的 OpenSearch 存储配置索引前缀分别为{{ .cluster }}-logs、{{ .cluster }}-events、{{ .cluster }}-auditing、{{ .cluster }}-notification-history。因此正确配置 Vector 的 OpenSearch sink是整个 WizTelemetry 可观测性数据落盘的前提。六、扩展运维操作查看扩展状态# 查看扩展安装状态 kubectl get installplan vector # 查看扩展版本 kubectl get extensionversions -l kubesphere.io/extension-refvector查看 Pod 状态# 查看所有 Vector Pod kubectl get pods -n kubesphere-logging-system -l app.kubernetes.io/namevector # 查看 agent Pod kubectl get pods -n kubesphere-logging-system -l app.kubernetes.io/namevector,app.kubernetes.io/componentagent查看日志kubectl logs -n kubesphere-logging-system -l app.kubernetes.io/namevector,app.kubernetes.io/componentagent --tail100更新配置修改spec.config版本不变即为配置更新然后重新 applyapiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: vector spec: extension: name: vector version: VECTOR_VERSION enabled: true upgradeStrategy: Manual config: | agent: sinks: opensearch: auth: strategy: basic user: OPENSEARCH_USER password: OPENSEARCH_PASSWORD endpoints: - OPENSEARCH_ENDPOINT clusterScheduling: placement: clusters: - TARGET_CLUSTERS从源码看配置更新会触发控制器重新执行安装/升级流程控制器会对config计算哈希plan.Status.ConfigHash hashutil.FNVString(values)当配置或版本发生变化时自动发起新的 Helm 执行 Job见 installplan_controller.go 与 installplan_controller.go。卸载扩展从所有集群卸载kubectl delete installplan vector从指定集群卸载将目标集群从clusterScheduling.placement.clusters中移除后重新 applyapiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: vector spec: extension: name: vector version: VECTOR_VERSION enabled: true upgradeStrategy: Manual config: | agent: sinks: opensearch: auth: strategy: basic user: OPENSEARCH_USER password: OPENSEARCH_PASSWORD endpoints: - OPENSEARCH_ENDPOINT clusterScheduling: placement: clusters: - REMAINING_CLUSTERS # 移除想要卸载的集群这一行为的底层逻辑同样在控制器中syncClusterSchedulingStatus会对比当前目标集群集合与status.clusterSchedulingStatuses中已部署的集群对不再属于目标集合的集群调用uninstallClusterAgent执行卸载见 installplan_controller.go 与 installplan_controller.go。七、重要注意事项依赖关系Vector 是 WizTelemetry 各扩展的核心依赖必须先于 Logging、Auditing、Events、Notification 安装OpenSearch 必填必须由用户提供 OpenSearch 端点与凭据否则无法配置 sink多集群模式扩展使用installationMode: Multiclusteragenttag 为 agent会部署到所有被选中的成员集群Agent 调度Agent Pod 配置了亲和性以避免调度到边缘节点并容忍所有污点跨集群访问必须确保所有部署 Vector 的集群都能访问到 OpenSearch 端点。八、故障排查检查 Vector 配置# 查看 Vector ConfigMap kubectl get configmap -n kubesphere-logging-system -l app.kubernetes.io/namevector # 查看具体配置 kubectl get configmap -n kubesphere-logging-system vector-config -o yaml验证 Sink# 检查 sink 是否配置正确 kubectl get secret -n kubesphere-logging-system vector-sinks -o yaml该 Secret 正是下游 whizard-telemetry 自动生成配置时的数据来源见上文第五节可据此核对端点、用户名与密码是否与预期一致。常见问题对照表问题解决方案Pod 无法启动检查 OpenSearch 是否可访问数据不流动验证 sink 配置与网络连通性Agent 未出现在成员集群检查多集群安装设置内存不足OOM在配置中调大资源上限九、延伸阅读skills/vector/SKILL.md本文核心依据WizTelemetry Data Pipeline 官方操作文档skills/opensearch/SKILL.mdOpenSearch 扩展安装与端点/凭据获取方式skills/whizard-logging/SKILL.mdLogging 扩展如何复用 Vector 的 OpenSearch sink 配置skills/whizard-telemetry/SKILL.md 与 skills/whizard-telemetry/scripts/generate-config.sh下游扩展如何读取vector-sinksSecret 自动生成存储配置skills/kubesphere-extension-management/SKILL.mdExtension / ExtensionVersion / InstallPlan 三大 CRD 的通用操作与最佳实践pkg/controller/core/installplan_controller.goInstallPlan 控制器实现含多集群 agent 调度、配置哈希与卸载逻辑staging/src/kubesphere.io/api/core/v1alpha1/types.goInstallPlan 与 ClusterScheduling 的 API 类型定义。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考