Backstage Kubernetes 插件审计事件Audit Events完全指南追踪集群与资源访问【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageKubernetes 后端插件backstage/plugin-kubernetes-backend内置了审计Audit能力会对集群信息获取、资源查询以及 Kubernetes API 代理请求等操作产生结构化审计事件帮助开发者追踪谁在何时访问了哪些集群与资源。本文将基于 docs/features/kubernetes/audit-events.md 展开结合仓库源码与测试用例完整梳理 Kubernetes 插件的cluster-fetch与resource-fetch两类事件、它们对应的 REST 端点、元数据字段、严重级别映射以及如何通过配置让低级别事件进入日志供安全审计与合规追踪使用。审计事件机制概览eventId queryType 两级分组Kubernetes 后端插件通过 Backstage 核心服务Auditor Servicedocs/backend-system/core-services/auditor.md发出审计事件。事件采用两级分类设计eventId逻辑分组标识代表一类操作集合。Kubernetes 插件目前使用cluster-fetch集群信息获取与resource-fetch资源查询两个eventId。meta.queryType在某个eventId分组内部进一步区分具体操作类型例如list、proxy、workloads、custom、services。这种命名方式与 Auditor Service 官方约定一致kebab-case 的eventIdmeta字段细分动作便于对审计日志按事件类型聚合、按查询类型过滤。从源码看事件创建统一通过auditor.createEvent({ eventId, request, meta })完成随后根据请求结果调用auditorEvent.success()或auditorEvent.fail({ error })收尾。集群事件Cluster Eventscluster-fetchcluster-fetch用于记录与集群信息相关的操作按queryType分为两类。queryType: list— 获取已配置集群列表触发端点GET /api/kubernetes/clusters默认严重级别low元数据queryType: list该事件在 KubernetesRouter.ts 的/clusters路由处理器中创建。处理流程为先以kubernetesClustersReadPermission做权限校验再通过clusterSupplier.getClusters()拉取集群明细并返回名称、标题、Dashboard URL、认证提供方等字段最终调用auditorEvent.success()若权限校验或数据获取抛错则调用auditorEvent.fail({ error })并向上抛出。queryType: proxy— 代理请求 Kubernetes API触发端点/api/kubernetes/proxy/*严重级别medium附加元数据clusterName集群名、methodHTTP 方法、path请求路径代理事件是唯一以medium级别记录的事件其实现集中在 ProxyAuditSession.ts每次代理请求进入 KubernetesProxy.ts 的请求处理器时都会启动一个ProxyAuditSession通过auditor.createEvent创建eventId: cluster-fetch、severityLevel: medium的事件并携带clusterName、method、path三个元数据字段。值得注意的实现细节URL 脱敏创建事件前会先剥离请求 URL 中的查询字符串split(?)[0]避免 token 等敏感参数进入审计元数据见 ProxyAuditSession.ts。HTTP 与 WebSocket 双路径终结普通 HTTP 代理请求通过监听响应对象的finish/close事件自动终结审计会话响应状态码 ≥ 400 或客户端提前断开时记为失败WebSocket 升级请求则通过onProxyReqWs钩子ProxyAuditSession.handleWebSocketProxyReq在upgrade、response、error、socketclose等事件上挂接终结逻辑见 KubernetesProxy.ts 与 ProxyAuditSession.ts。代理中间件显式设置ws: false正是为了让升级事件走 Express 路由、保证 WebSocket 请求也能被审计。集群名修正若请求头Backstage-Kubernetes-Cluster指定的集群与实际解析目标不一致终结时会用解析后的真实集群名覆盖clusterName元数据见 ProxyAuditSession.ts。在 KubernetesRouter.test.ts 中可以找到对上述事件的断言list事件断言createEvent携带eventId: cluster-fetch与meta: { queryType: list }并验证success/fail的调用proxy事件则断言severityLevel: medium及queryType: proxy元数据。资源事件Resource Eventsresource-fetchresource-fetch用于记录针对 Catalog 实体的 Kubernetes 资源查询按queryType分为三种默认严重级别均为low。除queryType外还可以通过meta.entityRef元数据识别被查询的 Catalog 实体格式为[kind]:[namespace]/[name]例如component:default/my-app。queryType: workloads— 查询实体的工作负载对象触发端点POST /api/kubernetes/resources/workloads/query元数据queryType: workloads、entityRef实现在 resourcesRoutes.ts路由处理器先从请求体取entityRef随后通过kubernetesResourcesReadPermission鉴权用catalog.getEntityByRef()解析实体再调用objectsProvider.getKubernetesObjectsByEntity()获取对象并返回成功调用auditorEvent.success()任何异常包括请求体缺少entityRef、实体不存在等InputError都会走auditorEvent.fail({ error })。queryType: custom— 查询实体的自定义资源触发端点POST /api/kubernetes/resources/custom/query元数据queryType: custom、entityRef同样实现在 resourcesRoutes.ts。相比 workloads它还校验请求体中的customResources字段必须是数组且至少包含 1 项否则抛出InputErrorcustomResources is a required field / must be an array / at least 1 customResource is required。校验通过后调用objectsProvider.getCustomResourcesByEntity()获取自定义资源。queryType: services— 按服务查询对象已废弃触发端点POST /api/kubernetes/services/:serviceId标记deprecated元数据queryType: services、entityRef、serviceId该端点在 KubernetesRouter.ts 中实现创建事件时除了entityRef还附带serviceId。其行为已被resource-fetch下的 workloads/custom 端点取代新代码不应再依赖此端点。在 resourceRoutes.test.ts 中workloads 与 custom 两种queryType的事件创建、成功/失败收尾、以及请求体缺失时仍先创建审计事件再失败等行为均有完整测试覆盖。严重级别与默认日志映射为什么默认看不到低级别事件Auditor Service 定义了四个严重级别见 docs/backend-system/core-services/auditor.md严重级别含义默认映射日志级别low低重要性事件通常为信息或调试级别debugmedium中等重要性事件需要一定关注infohigh高重要性事件可能暗示问题或安全事件infocritical关键事件需要立即关注info关键结论默认情况下Backstage 后端日志级别为info而low级别事件如cluster-fetch的list、全部resource-fetch事件被映射为debug级别因此默认不会出现在日志中。只有medium级别的cluster-fetchproxy事件会默认被记录。配置开启低级别审计事件日志若希望看到list与resource-fetch事件需要在app-config.yaml中将low严重级别映射到info日志级别backend: auditor: severityLogLevelMappings: low: info配置项位于backend.auditor.severityLogLevelMappings下支持只覆盖单个级别而不改动其余映射。完整的四级配置示例如下backend: auditor: severityLogLevelMappings: low: debug medium: info high: warn critical: error需要注意该配置的作用范围是全局的它会同时影响所有通过 Auditor Service 记录low级别事件的插件例如软件目录插件的entity-fetch等低级别事件也会一并进入日志因此在实际部署中应结合日志量与合规需求权衡。审计事件的完整生命周期create → success / fail理解 Kubernetes 插件的审计事件还需把握 Auditor Service 的使用模式同样适用于任何接入审计的插件const auditorEvent await auditor.createEvent({ eventId: resource-fetch, request: req, meta: { queryType: workloads, entityRef }, }); try { // ...鉴权与业务处理 await auditorEvent.success(); } catch (error) { await auditorEvent.fail({ error }); throw error; }从 Kubernetes 插件的源码与测试可以归纳出几个一致的工程实践先创建事件再执行业务逻辑即使后续鉴权失败或请求体缺失事件也必须存在以便完整记录失败的访问尝试测试用例中专门验证了请求体缺失时仍先创建事件再 fail。success/fail 二选一成功路径调用success()任何异常路径调用fail({ error })二者互斥。审计失败不影响业务success()或fail()的日志发出失败仅记录 error 日志不会改变 HTTP 响应结果测试中也有audit success emission rejects时仍返回 200 的用例。代理类长连接事件异步终结代理请求的事件在响应完成或 WebSocket 连接终结时才被 finalize避免长连接期间阻塞。实践建议与排查指引快速验证事件是否生效完成上述severityLogLevelMappings配置并重启后端后访问/api/kubernetes/clusters或任一资源查询端点观察后端日志中是否出现包含eventId与queryType的审计记录。区分事件来源想单独观察代理流量审计可直接查看medium级别的cluster-fetchqueryType: proxy事件其clusterName、method、path元数据可还原一次完整的 Kubernetes API 代理调用。按实体追踪资源访问审计日志中的entityRef字段格式[kind]:[namespace]/[name]可用于按 Catalog 实体聚合资源访问记录定位特定组件被查询的时间与频率。版本注意POST /api/kubernetes/services/:serviceId已标记deprecated请以 workloads/custom 端点为准进行监控与告警配置。通过上述机制Backstage Kubernetes 插件能够为集群访问提供一条结构清晰、可按eventId/queryType过滤、包含实体与集群上下文的审计链路结合 Auditor Service 的严重级别映射运维与安全团队可以按需控制审计日志的粒度实现集群与资源访问的可观测与可追溯。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage Kubernetes 插件审计事件（Audit Events）完全指南：追踪集群与资源访问
Backstage Kubernetes 插件审计事件Audit Events完全指南追踪集群与资源访问【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageKubernetes 后端插件backstage/plugin-kubernetes-backend内置了审计Audit能力会对集群信息获取、资源查询以及 Kubernetes API 代理请求等操作产生结构化审计事件帮助开发者追踪谁在何时访问了哪些集群与资源。本文将基于 docs/features/kubernetes/audit-events.md 展开结合仓库源码与测试用例完整梳理 Kubernetes 插件的cluster-fetch与resource-fetch两类事件、它们对应的 REST 端点、元数据字段、严重级别映射以及如何通过配置让低级别事件进入日志供安全审计与合规追踪使用。审计事件机制概览eventId queryType 两级分组Kubernetes 后端插件通过 Backstage 核心服务Auditor Servicedocs/backend-system/core-services/auditor.md发出审计事件。事件采用两级分类设计eventId逻辑分组标识代表一类操作集合。Kubernetes 插件目前使用cluster-fetch集群信息获取与resource-fetch资源查询两个eventId。meta.queryType在某个eventId分组内部进一步区分具体操作类型例如list、proxy、workloads、custom、services。这种命名方式与 Auditor Service 官方约定一致kebab-case 的eventIdmeta字段细分动作便于对审计日志按事件类型聚合、按查询类型过滤。从源码看事件创建统一通过auditor.createEvent({ eventId, request, meta })完成随后根据请求结果调用auditorEvent.success()或auditorEvent.fail({ error })收尾。集群事件Cluster Eventscluster-fetchcluster-fetch用于记录与集群信息相关的操作按queryType分为两类。queryType: list— 获取已配置集群列表触发端点GET /api/kubernetes/clusters默认严重级别low元数据queryType: list该事件在 KubernetesRouter.ts 的/clusters路由处理器中创建。处理流程为先以kubernetesClustersReadPermission做权限校验再通过clusterSupplier.getClusters()拉取集群明细并返回名称、标题、Dashboard URL、认证提供方等字段最终调用auditorEvent.success()若权限校验或数据获取抛错则调用auditorEvent.fail({ error })并向上抛出。queryType: proxy— 代理请求 Kubernetes API触发端点/api/kubernetes/proxy/*严重级别medium附加元数据clusterName集群名、methodHTTP 方法、path请求路径代理事件是唯一以medium级别记录的事件其实现集中在 ProxyAuditSession.ts每次代理请求进入 KubernetesProxy.ts 的请求处理器时都会启动一个ProxyAuditSession通过auditor.createEvent创建eventId: cluster-fetch、severityLevel: medium的事件并携带clusterName、method、path三个元数据字段。值得注意的实现细节URL 脱敏创建事件前会先剥离请求 URL 中的查询字符串split(?)[0]避免 token 等敏感参数进入审计元数据见 ProxyAuditSession.ts。HTTP 与 WebSocket 双路径终结普通 HTTP 代理请求通过监听响应对象的finish/close事件自动终结审计会话响应状态码 ≥ 400 或客户端提前断开时记为失败WebSocket 升级请求则通过onProxyReqWs钩子ProxyAuditSession.handleWebSocketProxyReq在upgrade、response、error、socketclose等事件上挂接终结逻辑见 KubernetesProxy.ts 与 ProxyAuditSession.ts。代理中间件显式设置ws: false正是为了让升级事件走 Express 路由、保证 WebSocket 请求也能被审计。集群名修正若请求头Backstage-Kubernetes-Cluster指定的集群与实际解析目标不一致终结时会用解析后的真实集群名覆盖clusterName元数据见 ProxyAuditSession.ts。在 KubernetesRouter.test.ts 中可以找到对上述事件的断言list事件断言createEvent携带eventId: cluster-fetch与meta: { queryType: list }并验证success/fail的调用proxy事件则断言severityLevel: medium及queryType: proxy元数据。资源事件Resource Eventsresource-fetchresource-fetch用于记录针对 Catalog 实体的 Kubernetes 资源查询按queryType分为三种默认严重级别均为low。除queryType外还可以通过meta.entityRef元数据识别被查询的 Catalog 实体格式为[kind]:[namespace]/[name]例如component:default/my-app。queryType: workloads— 查询实体的工作负载对象触发端点POST /api/kubernetes/resources/workloads/query元数据queryType: workloads、entityRef实现在 resourcesRoutes.ts路由处理器先从请求体取entityRef随后通过kubernetesResourcesReadPermission鉴权用catalog.getEntityByRef()解析实体再调用objectsProvider.getKubernetesObjectsByEntity()获取对象并返回成功调用auditorEvent.success()任何异常包括请求体缺少entityRef、实体不存在等InputError都会走auditorEvent.fail({ error })。queryType: custom— 查询实体的自定义资源触发端点POST /api/kubernetes/resources/custom/query元数据queryType: custom、entityRef同样实现在 resourcesRoutes.ts。相比 workloads它还校验请求体中的customResources字段必须是数组且至少包含 1 项否则抛出InputErrorcustomResources is a required field / must be an array / at least 1 customResource is required。校验通过后调用objectsProvider.getCustomResourcesByEntity()获取自定义资源。queryType: services— 按服务查询对象已废弃触发端点POST /api/kubernetes/services/:serviceId标记deprecated元数据queryType: services、entityRef、serviceId该端点在 KubernetesRouter.ts 中实现创建事件时除了entityRef还附带serviceId。其行为已被resource-fetch下的 workloads/custom 端点取代新代码不应再依赖此端点。在 resourceRoutes.test.ts 中workloads 与 custom 两种queryType的事件创建、成功/失败收尾、以及请求体缺失时仍先创建审计事件再失败等行为均有完整测试覆盖。严重级别与默认日志映射为什么默认看不到低级别事件Auditor Service 定义了四个严重级别见 docs/backend-system/core-services/auditor.md严重级别含义默认映射日志级别low低重要性事件通常为信息或调试级别debugmedium中等重要性事件需要一定关注infohigh高重要性事件可能暗示问题或安全事件infocritical关键事件需要立即关注info关键结论默认情况下Backstage 后端日志级别为info而low级别事件如cluster-fetch的list、全部resource-fetch事件被映射为debug级别因此默认不会出现在日志中。只有medium级别的cluster-fetchproxy事件会默认被记录。配置开启低级别审计事件日志若希望看到list与resource-fetch事件需要在app-config.yaml中将low严重级别映射到info日志级别backend: auditor: severityLogLevelMappings: low: info配置项位于backend.auditor.severityLogLevelMappings下支持只覆盖单个级别而不改动其余映射。完整的四级配置示例如下backend: auditor: severityLogLevelMappings: low: debug medium: info high: warn critical: error需要注意该配置的作用范围是全局的它会同时影响所有通过 Auditor Service 记录low级别事件的插件例如软件目录插件的entity-fetch等低级别事件也会一并进入日志因此在实际部署中应结合日志量与合规需求权衡。审计事件的完整生命周期create → success / fail理解 Kubernetes 插件的审计事件还需把握 Auditor Service 的使用模式同样适用于任何接入审计的插件const auditorEvent await auditor.createEvent({ eventId: resource-fetch, request: req, meta: { queryType: workloads, entityRef }, }); try { // ...鉴权与业务处理 await auditorEvent.success(); } catch (error) { await auditorEvent.fail({ error }); throw error; }从 Kubernetes 插件的源码与测试可以归纳出几个一致的工程实践先创建事件再执行业务逻辑即使后续鉴权失败或请求体缺失事件也必须存在以便完整记录失败的访问尝试测试用例中专门验证了请求体缺失时仍先创建事件再 fail。success/fail 二选一成功路径调用success()任何异常路径调用fail({ error })二者互斥。审计失败不影响业务success()或fail()的日志发出失败仅记录 error 日志不会改变 HTTP 响应结果测试中也有audit success emission rejects时仍返回 200 的用例。代理类长连接事件异步终结代理请求的事件在响应完成或 WebSocket 连接终结时才被 finalize避免长连接期间阻塞。实践建议与排查指引快速验证事件是否生效完成上述severityLogLevelMappings配置并重启后端后访问/api/kubernetes/clusters或任一资源查询端点观察后端日志中是否出现包含eventId与queryType的审计记录。区分事件来源想单独观察代理流量审计可直接查看medium级别的cluster-fetchqueryType: proxy事件其clusterName、method、path元数据可还原一次完整的 Kubernetes API 代理调用。按实体追踪资源访问审计日志中的entityRef字段格式[kind]:[namespace]/[name]可用于按 Catalog 实体聚合资源访问记录定位特定组件被查询的时间与频率。版本注意POST /api/kubernetes/services/:serviceId已标记deprecated请以 workloads/custom 端点为准进行监控与告警配置。通过上述机制Backstage Kubernetes 插件能够为集群访问提供一条结构清晰、可按eventId/queryType过滤、包含实体与集群上下文的审计链路结合 Auditor Service 的严重级别映射运维与安全团队可以按需控制审计日志的粒度实现集群与资源访问的可观测与可追溯。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考