## 概述 Kubernetes 的 Gateway API 暴露清单导出器 — 将 Gateway→Listener→HTTPRoute→Service 映射到 `exposed_route_info` Prometheus/OTel 指标中。 **自动发现并监控所有外部暴露的 Kubernetes 服务。通过 Gateway API 跟踪每个暴露的 endpoint 和服务，以洞察您的外部攻击面。** ## 功能 - **Controller-Runtime Informers:** 使用原生的 K8s 缓存，而不是轮询 API 服务器。 - **语义解析：** 评估已接受的 Route 父级、listener 附加规则、hostname 交集、ReferenceGrants 和 Service 后端。 - **多协议：** 支持 Prometheus `/metrics` endpoint 和 OpenTelemetry gRPC 推送。 - **强化运行时：** Distroless 镜像、非 root 执行、只读文件系统、HTTP 超时和只读 RBAC。 - **独立于提供商：** 从标准的 `Gateway.status.addresses` 字段读取地址，而无需依赖云提供商的 API。 - **规范驱动：** 通过 [OpenSpec](./openspec/specs/) 管理文档和需求。 ## 快速开始 ### 构建与测试 ``` make fmt make test make build ./bin/exporter ``` ### 部署 使用已发布的 OCI chart（已签名，请参阅[验证](./docs/verification.md)）： ``` VERSION=0.1.2 # Replace with the release you want to install helm upgrade --install gateway-exporter \ oci://ghcr.io/tokanize/charts/kubernetes-gateway-exporter --version "${VERSION}" \ --namespace monitoring --create-namespace ``` 或者从本地源码部署： ``` helm upgrade --install gateway-exporter ./deploy/chart/kubernetes-gateway-exporter \ --namespace monitoring \ --create-namespace ``` ## 指标 主要指标是 `exposed_route_info`（Gauge），它明确标识了究竟是哪个 route、listener 和 hostname 产生了暴露关系。 它描述的是逻辑上的 Gateway API 路由关系，而不是 Pod IP 或 `EndpointSlice` 成员。一个由 5 个 Pod 提供支持的 Service 对于每一个有效的 listener/hostname/path/backend 组合，依然只会生成一个时间序列，而不是 5 个 Pod 级别的序列。 它包含以下标签： - `namespace`：HTTPRoute 的 namespace，保留用于资源身份标识和向后兼容。 - `gateway_name`：父级 Gateway 名称。 - `route_name`：HTTPRoute 的 `metadata.name`。 - `hostname`：有效的交集 hostname。 - `listener_name`：附加的 Gateway listener。 - `http_path`：Route 路径匹配。 - `service_name`：后端 Service 名称。 - `backend_namespace`：后端 namespace。 - `backend_port`：目标后端端口。 - `lb_type`：`internal` 或 `external`，根据 GatewayClass 名称进行启发式推断。 - `ip_address`：取自 `Gateway.status.addresses` 的第一个 IP；如果不可用，则为空字符串。 用户可以通过运行以下命令来定位生成特定指标序列的源 YAML 文件 （替换 `namespace` 和 `route_name` 标签的值）： ``` ROUTE_NAMESPACE=default ROUTE_NAME=my-route kubectl get httproute -n "$ROUTE_NAMESPACE" "$ROUTE_NAME" -o yaml ``` ## 供应链安全 每个版本都会将多架构容器镜像发布到 `ghcr.io/tokanize/kubernetes-gateway-exporter`，并通过 cosign 无密钥签名（GitHub OIDC —— 无需长期密钥）按摘要进行签名。每个版本还包含针对镜像、chart、二进制归档文件和 SBOMs 的 GitHub Artifact Attestations（构建来源）。SPDX SBOMs（`sbom-image.spdx.json`，`sbom-source.spdx.json`）和二进制归档文件由强化工作流生成的已签名 `checksums.txt` 在发布中提供保护。 **快速镜像签名检查：** ``` VERSION=0.1.2 # Replace with the release you want to verify SOURCE_REF="refs/tags/v${VERSION}" # 1. 为 tag 解析不可变 digest IMAGE=ghcr.io/tokanize/kubernetes-gateway-exporter DIGEST=$(docker buildx imagetools inspect "${IMAGE}:${VERSION}" \ --format '{{json .}}' | jq -r '.manifest.digest') # 2. 验证 cosign signature cosign verify \ --certificate-identity "https://github.com/tokanize/kubernetes-gateway-exporter/.github/workflows/release.yml@${SOURCE_REF}" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \ "${IMAGE}@${DIGEST}" ``` 这些检查确立了制品的来源和完整性；它们并不能保证 软件没有漏洞，也不能保证您的环境 符合安全策略。 如需完整可直接复制粘贴的验证步骤（镜像、二进制文件、校验和、SBOMs），请参阅 [docs/verification.md](./docs/verification.md)。有关 CI 扫描层（静态分析、容器扫描、依赖审计），请参阅 [docs/security-scanning.md](./docs/security-scanning.md)。如需报告漏洞，请参阅 [SECURITY.md](./SECURITY.md)。 ## 文档目录 欢迎来到 Kubernetes Gateway Exporter 文档的中心入口。所有项目规范、架构决策和 API schema 都在以下各个部分中维护： ### 1. 综合与架构 - **[架构与概述](./docs/architecture.md)**：将 Gateway -> Listener -> HTTPRoute -> Service 进行映射的概念模型。 - **[架构决策记录 (ADRs)](./docs/adrs/)**：技术设计选择及其理由。 ### 2. API 与需求 - **[OpenAPI Schema](./docs/api/openapi.yaml)**：metrics API endpoint 的严格结构化定义。 - **[OpenSpec 需求](./openspec/specs/)**：由 BDD 场景（GIVEN/WHEN/THEN）驱动的功能需求，用于验证 metrics、informers、probes 和 IP 解析。 ### 3. Agent 指令 我们采用多 Agent LLM 系统来维护此仓库。Agent 角色及其操作准则如下： - **[Agent 路由中心](./AGENTS.md)**：自动化助手的主枢纽。 - **[Gemini 约束](./GEMINI.md)** - **[Codex 约束](./CODEX.md)** - **[Claude 约束](./CLAUDE.md)** ### 4. 安全与发布 - **[安全扫描 (CI)](./docs/security-scanning.md)**：CI 中的静态分析、容器扫描和依赖审计。 - **[发布验证](./docs/verification.md)**：验证镜像签名、构建来源、校验和与 SBOMs 的分步指南。 - **[安全策略](./SECURITY.md)**：漏洞报告流程与支持的版本。 - **[贡献指南](./CONTRIBUTING.md)**：开发工作流、代码规范和 pull request 流程。 ### 5. 指南 - **[在 kind 上进行本地测试](./docs/testing-on-kind.md)**：模拟 Gateway API controller 行为的 E2E 本地验证指南。 ### 6. 代码智能 该仓库内置了两个互补的代码导航辅助工具，多 Agent 助手相比于原生 `grep`/`find` 更倾向于使用它们： - **CodeGraph MCP**：当 CodeGraph MCP 服务器可用时，Agent 会查询它（`codegraph_explore`）以进行实时的、按需的结构查找。其索引缓存（`.codegraph/`）仅在本地保留，从不提交。 - **[graphify 知识图谱](https://github.com/safishamsi/graphify)**：位于 [`graphify-out/`](./graphify-out/) 下已提交且可查询的代码库知识图谱（包含 `graph.json`、交互式的 `graph.html` 和 `GRAPH_REPORT.md`）。运行 `graphify query ""`、`graphify path "" ""` 或 `graphify explain ""` 获取范围受限的子图；在代码变更后使用 `graphify update .` 重建（仅基于 AST，无 API 成本）。相关基本原理请参阅 [ADR-007](./docs/adrs/007-knowledge-graph.md)，本地设置请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。

由 @tokanize 构建以解决个人的可观测性需求。过度设计？也许吧。有用吗？绝对的。