maddibilvasai4125/Apigee-OPDK-Platform-Support

# 企业级 Apigee OPDK 平台 — API 运维与事件响应 ## 目录 - [概述](#overview) - [平台架构](#platform-architecture) - [仓库结构](#repository-structure) - [事件响应与 RCA](#incident-response--rca) - [Proxy 开发标准](#proxy-development-standards) - [缓存策略](#caching-strategy) - [安全与证书管理](#security--certificate-management) - [KVM 实用 Proxy](#kvm-utility-proxy) - [分析与报告](#analytics--reporting) - [开发者与应用生命周期](#developer--app-lifecycle) - [目标服务器管理](#target-server-management) - [运维治理](#operations-governance) - [贡献](#contributing) ## 概述 本仓库包含运行 **生产环境 Apigee OPDK (On-Premises Deployment Kit)** 网关平台所需的所有运维脚本、Proxy 策略、分析工具、Runbook 和治理框架。 ### 本平台涵盖的内容 | 领域 | 能力 | |---|---| | **事件响应** | 针对 502/503/504 的 RCA Playbook、超时分类、tcpdump/trace 分析 | | **Proxy 标准** | OAuth2、JWT、条件流、统一错误规则、错误契约 | | **缓存** | ResponseCache + KVM 支持的 Lookup/Populate Cache 模式 | | **安全** | Keystore/Truststore 轮换、IP 白名单、F5/Proxy 层路由 | | **分析** | 月度流量/错误仪表板、Power Query 报告、MP 日志分析 | | **开发者生命周期** | 应用接入、API Key 签发/轮换、市场就绪 | | **目标服务器** | TargetServer 管理、健康检查、超时对齐 | | **KVM 实用工具** | 具有严格 RBAC 的 Break-glass KVM 读取器，用于读取加密值 | | **治理** | SLO/告警调优、DR 演练、Runbook、Google Support 协作 | ## 平台架构 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ APIGEE OPDK — PRODUCTION TOPOLOGY │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ INBOUND PATH │ │ │ │ │ │ │ │ Client → F5 LTM → Web Proxy Tier → Apigee Router → Message │ │ │ │ Processor │ │ │ └──────────────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────▼──────────────────────────────────┐ │ │ │ MESSAGE PROCESSOR │ │ │ │ │ │ │ │ PreFlow → Conditional Flows → PostFlow → FaultRules │ │ │ │ │ │ │ │ │ ├── sf-auth (OAuth2 / API Key / JWT) │ │ │ │ ├── sf-logging (Structured JSON → Splunk/Grafana) │ │ │ │ ├── sf-error (Unified Fault Rules + Error Contracts) │ │ │ │ ├── Cache Layer (ResponseCache / Lookup+Populate) │ │ │ │ └── KVM (Encrypted config / credentials) │ │ │ └──────────────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────────────▼──────────────────────────────────┐ │ │ │ OUTBOUND PATH (Target Servers) │ │ │ │ │ │ │ │ TargetServer → Backend APIs (keep-alive / timeout aligned) │ │ │ │ (migrated from MuleSoft / Forum Sentry) │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ PostgreSQL │ │ Grafana │ │ Power Query │ │ │ │ (Analytics) │ │ Dashboards │ │ Reports │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 超时架构 — 入站 vs 出站 ``` Client ──[connect timeout]──► Router ──[io.timeout]──► MP ──[connect.timeout]──► Target (F5 / LB side) (MP) (response.timeout) ``` | 超时设置 | 层级 | 建议值 | 备注 | |---|---|---|---| | `connection.timeout.millis` | MP → Target | 3000ms | 到后端的 TCP 连接 | | `io.timeout.millis` | MP | 55000ms | 总请求 I/O 预算 | | `response.timeout` | TargetServer | 50000ms | 后端响应窗口 | | F5 idle timeout | LB | 60000ms | 必须 > MP 总时间 | | Keep-alive (backend) | TargetServer | 匹配后端 | 防止过早重置 | ## 仓库结构 ``` enterprise-apigee-opdk-platform/ │ ├── README.md # This file │ ├── scripts/ │ ├── rca/ │ │ ├── triage-502-503-504.sh # Automated 5xx error triage │ │ ├── analyze-mp-logs.sh # Message Processor log analysis │ │ └── tcpdump-capture.sh # Network packet capture helper │ │ │ ├── health-check/ │ │ └── opdk-health-check.sh # Full OPDK component health check │ │ │ ├── cert-rotation/ │ │ └── rotate-keystore.sh # Zero-downtime keystore/truststore rotation │ │ │ ├── kvm-utility/ │ │ └── read-encrypted-kvm.sh # Break-glass KVM reader (RBAC-gated) │ │ │ └── target-servers/ │ └── manage-target-servers.sh # Create/update/validate TargetServers │ ├── policies/ │ ├── oauth2/ │ │ ├── OAuthV2-VerifyAccessToken.xml # OAuth2 token verification │ │ └── OAuthV2-GenerateAccessToken.xml # Token minting │ │ │ ├── jwt/ │ │ ├── JWT-VerifyToken.xml # JWT signature + expiry validation │ │ └── JWT-GenerateToken.xml # JWT minting with claims │ │ │ ├── cache/ │ │ ├── ResponseCache.xml # Full response caching │ │ ├── LookupCache.xml # KVM-backed cache lookup │ │ └── PopulateCache.xml # Cache population policy │ │ │ ├── fault-handling/ │ │ ├── RaiseFault-Standard.xml # Unified error response contract │ │ └── FaultRules.xml # Global fault rule ordering │ │ │ └── shared-flows/ │ ├── sf-error-handling/ # Centralized error normalization │ └── sf-logging/ # Structured JSON logging │ ├── proxies/ │ └── kvm-utility-proxy/ # Break-glass KVM reader proxy │ ├── apiproxy/ │ │ ├── KVMUtility.xml │ │ ├── policies/ │ │ └── proxies/ │ └── README.md │ ├── analytics/ │ ├── dashboards/ │ │ └── grafana-opdk-dashboard.json # Grafana: traffic, errors, latency │ └── reports/ │ └── monthly-report-template.md # Monthly analytics report template │ ├── kubernetes/ │ └── monitoring/ │ └── prometheus-alerts.yaml # Prometheus alert rules for OPDK │ └── docs/ ├── rca-playbook.md # RCA methodology + 5xx decision tree ├── timeout-matrix.md # All timeout values per environment ├── cert-rotation-runbook.md # Step-by-step cert rotation ├── developer-lifecycle.md # App onboarding + API key management └── ops-governance.md # SLO tuning, DR drills, change control ``` ## 事件响应与 RCA ### 5xx 错误决策树 ``` 502/503/504 Reported │ ├─ Is it inbound (client→MP) or outbound (MP→target)? │ │ │ ┌────▼───────────────────────────────────────┐ │ │ Check: MP logs → search for fault.name │ │ │ Check: Trace tool → identify failing step │ │ └────────────────────────────────────────────┘ │ ├─ 502 Bad Gateway │ └─ Target returned malformed response │ → tcpdump on MP → target port │ → Check keep-alive mismatch │ → Check TLS handshake failure │ ├─ 503 Service Unavailable │ └─ No healthy target / MP overload │ → Check TargetServer health check logs │ → Check MP thread pool exhaustion │ → Check DNS resolution failure │ └─ 504 Gateway Timeout └─ Target did not respond in time → Compare response.timeout vs backend SLA → Check io.timeout.millis value → tcpdump to verify TCP RST or silence ``` ### RCA 工具链 | 工具 | 用途 | 位置 | |---|---|---| | Apigee Trace | 策略级执行追踪 | Apigee Management UI | | `tcpdump` | 网络级数据包分析 | `scripts/rca/tcpdump-capture.sh` | | MP Logs | Message Processor 系统日志 | `scripts/rca/analyze-mp-logs.sh` | | PostgreSQL | 用于错误趋势的分析查询 | Apigee Analytics DB | | Grafana | 可视化流量 + 错误仪表板 | `analytics/dashboards/` | | Postman | 修复复现和验证 | `analytics/` 中的集合 | ## Proxy 开发标准 ### 策略执行顺序 (Fail-Fast 模式) ``` PreFlow Request: 1. sf-auth ← Authenticate first — reject early 2. sf-logging-start ← Capture request metadata 3. LookupCache ← Serve from cache if hit 4. [Conditional Flows — business logic] 5. PopulateCache ← Cache successful responses PostFlow Response: 6. sf-logging-end ← Log latency + status 7. [Response transforms] FaultRules (ordered): 1. Authentication errors → 401 2. Authorization errors → 403 3. Quota exceeded → 429 4. Target errors → 502/503/504 5. Default catch-all → 500 ``` ### 统一错误契约 所有 Proxy 返回一致的 JSON 错误信封： ``` { "error": { "code": 401, "status": "UNAUTHORIZED", "message": "Human-readable message for API consumers.", "details": [{ "reason": "TokenExpired", "domain": "apigee", "correlationId": "abc-123-xyz" }] } } ``` ## 缓存策略 | 缓存类型 | 策略 | 用例 | TTL | |---|---|---|---| | **ResponseCache** | `ResponseCache.xml` | 完整 GET 响应缓存 | 5–15 分钟 | | **LookupCache** | `LookupCache.xml` | KVM 支持的 Token/配置查找 | 10–30 分钟 | | **PopulateCache** | `PopulateCache.xml` | Mint 后存储 Access Token | Token TTL - 60s | ### Token 开销减少模式 ``` Request arrives │ ▼ LookupCache (key = client_id + scope) │ ├─ CACHE HIT → Skip token mint → forward cached token → saves ~100ms │ └─ CACHE MISS → Mint new token → PopulateCache → forward token ``` ## 安全与证书管理 ### 证书轮换 (零停机) ``` # Full zero-downtime 轮换 ./scripts/cert-rotation/rotate-keystore.sh \ --env prod \ --alias apigee-ssl-cert \ --new-cert /path/to/new-cert.pem \ --new-key /path/to/new-key.pem ``` 该脚本遵循 **蓝/绿 Keystore 策略**： 1. 使用新证书创建新的 Keystore 2. 更新 Virtual Host 引用至新的 Keystore 3. 在所有 Router 上验证 TLS 握手 4. 仅在验证通过后删除旧的 Keystore ### IP 白名单 通过 `AccessControl` 策略管理 — 特定环境的 IP 范围存储在 KVM 中： ``` ``` ## KVM 实用 Proxy 一个专用的 **Break-glass Proxy**，用于在事件期间读取加密的 KVM 值。 访问通过 RBAC 严格控制 — 只有具有 `kvm-reader` 角色的值班 SRE 才能调用它。 ``` # 读取加密的 KVM 值（需要 SRE token） curl -X GET \ "https://api.company.com/kvm-utility/v1/read" \ -H "Authorization: Bearer $SRE_TOKEN" \ -H "x-kvm-map: prod-secrets" \ -H "x-kvm-key: target-api-key" ``` ## 分析与报告 ### 月度报告内容 - 按流量排名的前 10 个 Proxy - 按错误率排名的前 10 个 Proxy (5xx + 4xx 分类) - 延迟趋势 (每个 Proxy 的 p50/p95/p99) - 新增 vs 回归的开发者应用 - 配额违规事件 - SLO 合规性摘要 ### Grafana 仪表板面板 - 请求速率 (RPS) — 所有环境 - 错误率热力图 (Proxy × 时间) - 延迟百分位 (p50/p95/p99) - 目标服务器响应时间 - 缓存命中/未命中率 - 活跃的开发者应用 ## 开发者与应用生命周期 ### 入职检查清单 ``` New Developer/App Onboarding ├─ [ ] Developer account created in Apigee Management UI ├─ [ ] App registered and linked to correct API Products ├─ [ ] API key issued and communicated via secure channel ├─ [ ] OAuth2 client credentials configured (if applicable) ├─ [ ] Rate limits set at API Product level (not hardcoded in proxy) ├─ [ ] Developer briefed on error contract and retry guidance └─ [ ] App listed in marketplace (if external-facing) API Key Rotation ├─ [ ] Generate new key pair in Management UI ├─ [ ] Communicate new key to developer (grace period = 7 days) ├─ [ ] Monitor old key traffic drops to zero └─ [ ] Revoke old key after confirmed cutover ``` ## 目标服务器管理 所有后端都注册为 **TargetServers** — Proxy 中不包含硬编码的 URL。 ``` # 注册新的 TargetServer ./scripts/target-servers/manage-target-servers.sh \ --action create \ --name payments-backend \ --host payments.internal.company.com \ --port 8443 \ --ssl true \ --env prod ``` ### 超时对齐检查清单 在注册任何新的 TargetServer 之前： - [ ] 与负责团队确认后端 P99 响应时间 - [ ] 设置 `connection.timeout.millis` = 3000ms - [ ] 设置 `response.timeout` = 后端 P99 + 20% 缓冲 - [ ] 启用健康检查端点 (`/health` 或 `/ping`) - [ ] Keep-alive 设置匹配后端 Web 服务器配置 - [ ] 首先在低环境中使用 Postman 进行验证 ## 运维治理 ### 变更控制流程 ``` Development → Code Review (2 approvals) → Staging Deploy → Smoke Test → Load Test (if traffic-heavy) → Change Ticket → Prod Deploy (change window) → Post-deploy Validation → Close Ticket ``` ### SLO 定义 | 指标 | 目标 | 告警阈值 | |---|---|---| | API 可用性 | 99.9% | < 99.5% 触发 P1 | | p99 延迟 | < 2s | > 2s 持续 5 分钟触发 P2 | | 5xx 错误率 | < 0.1% | > 0.5% 持续 5 分钟触发 P1 | | 证书过期时间 | > 30 天 | < 30 天触发 P3 | ### Google Apigee Support 协作 当升级到 Google Apigee Support 时： 1. 收集：Trace XML、MP Logs (`/opt/apigee/var/log/edge-message-processor/`)、时间戳 2. 尽可能在低环境中重现 3. 开启工单，包含：Apigee 版本、拓扑、重现步骤、附上日志 4. 在 Staging 环境中验证修复 → 在变更控制下推广 ## 👤 作者 **Bilva Sai Eswar Maddi** - 🐙 GitHub: [@maddibilvasai4125](https://github.com/maddibilvasai4125) - 💼 LinkedIn: [Bilva Sai Eswar Maddi](https://www.linkedin.com/in/bilva-sai-eswar-maddi/) - 📧 Email: catchbilvasaieswar@gmail.com - 🌐 作品集: [My Portfolio](https://bilvasaieswarmaddi.com/)

标签：4xx/5xx错误, Apigee, API管理, API网关, GitHub Advanced Security, JWT, KVM, OAuth2, OPDK, RCA, SamuraiWTF, Site Reliability Engineering, SRE, Target Server, 事件管理, 代码示例, 偏差过滤, 可视化看板, 安全, 安全加固, 应用安全, 性能优化, 故障响应, 数据分析, 根因分析, 检测绕过, 流量管理, 测试用例, 混合云, 缓存策略, 自定义请求头, 证书管理, 超时处理, 运维运营, 错误处理