From 448454beb5c07fd5c3783dbc7140bf2bdcd44455 Mon Sep 17 00:00:00 2001 From: Drew Raines Date: Sat, 25 Apr 2026 16:47:49 +0000 Subject: [PATCH 1/3] feat(datum-platform): add analyze-gcp-spend skill and cost-analyst agent Weekly GCP cost report covering datum-cloud staging and production. Queries BigQuery billing exports and live cluster state (node pools, PVCs, Cloud SQL), generates mermaid xychart-beta trend charts for the trailing 4 months, and files a PR to datum-cloud/engineering. Includes cadence logic to produce a full prior-month retrospective when run in the first 7 days of a month. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 6 + README.md | 6 +- .../datum-platform/.claude-plugin/plugin.json | 2 +- plugins/datum-platform/agents/cost-analyst.md | 36 ++++ .../skills/analyze-gcp-spend/SKILL.md | 68 ++++++ .../skills/analyze-gcp-spend/queries.md | 178 ++++++++++++++++ .../skills/analyze-gcp-spend/report-format.md | 197 ++++++++++++++++++ 7 files changed, 489 insertions(+), 4 deletions(-) create mode 100644 plugins/datum-platform/agents/cost-analyst.md create mode 100644 plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md create mode 100644 plugins/datum-platform/skills/analyze-gcp-spend/queries.md create mode 100644 plugins/datum-platform/skills/analyze-gcp-spend/report-format.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e5917d9..078d53c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ Notable changes to the Datum Cloud Claude Code plugins. +## [1.7.0] - 2026-04-25 + +### Added + +- **GCP spend analysis skill** (`analyze-gcp-spend`) — Weekly GCP cost report covering datum-cloud staging and production. Queries BigQuery billing exports and live cluster state, generates mermaid trend charts for the trailing 4 months, and files a PR to `datum-cloud/engineering`. Includes a dedicated `cost-analyst` agent and full report-format and query reference. + ## [1.6.0] - 2026-04-12 ### Added diff --git a/README.md b/README.md index 127e526..af13e81 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A marketplace for Claude Code plugins providing platform engineering tools and a | Plugin | Description | Version | |--------|-------------|---------| -| [datum-platform](./plugins/datum-platform/) | Kubernetes platform engineering automation with aggregated API servers, controller patterns, and GitOps deployment | 1.6.0 | +| [datum-platform](./plugins/datum-platform/) | Kubernetes platform engineering automation with aggregated API servers, controller patterns, and GitOps deployment | 1.7.0 | | [datum-gtm](./plugins/datum-gtm/) | Go-to-market automation with commercial strategy, product discovery, and customer support | 1.0.0 | | [milo-activity](./plugins/milo-activity/) | Query audit logs, investigate incidents, and author ActivityPolicies using the Milo Activity service | 1.0.0 | @@ -123,8 +123,8 @@ claude-code-plugins/ Kubernetes platform engineering automation with aggregated API servers, controller patterns, and GitOps deployment for the Datum Cloud platform. **Features:** -- 6 specialized agents (api-dev, frontend-dev, sre, test-engineer, code-reviewer, tech-writer) -- 26 skill modules covering Kubernetes patterns, Go conventions, deployment workflows, and more +- 7 specialized agents (api-dev, frontend-dev, sre, test-engineer, code-reviewer, tech-writer, cost-analyst) +- 27 skill modules covering Kubernetes patterns, Go conventions, deployment workflows, and more - Pipeline orchestration for structured feature development - Automatic learning engine for pattern extraction diff --git a/plugins/datum-platform/.claude-plugin/plugin.json b/plugins/datum-platform/.claude-plugin/plugin.json index dd112e0..5e5821d 100644 --- a/plugins/datum-platform/.claude-plugin/plugin.json +++ b/plugins/datum-platform/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "datum-platform", "description": "Kubernetes platform engineering automation with aggregated API servers, controller patterns, GitOps deployment, and platform capabilities", - "version": "1.6.0", + "version": "1.7.0", "author": { "name": "Datum Cloud", "url": "https://github.com/datum-cloud" diff --git a/plugins/datum-platform/agents/cost-analyst.md b/plugins/datum-platform/agents/cost-analyst.md new file mode 100644 index 0000000..25e7c86 --- /dev/null +++ b/plugins/datum-platform/agents/cost-analyst.md @@ -0,0 +1,36 @@ +--- +name: cost-analyst +description: > + Use when producing or updating a weekly GCP spend report for datum-cloud infrastructure. + Triggered by phrases like "gcp spend", "cost report", "analyze costs", "cloud spend", + "monthly spend", or "cost analysis". Covers both production and staging, queries BigQuery + billing exports and live cluster state, generates mermaid trend charts for the trailing + 4 months, and files a PR to the engineering repo. +tools: Read, Write, Edit, Grep, Glob, Bash +model: sonnet +--- + +# Cost Analyst Agent + +Senior SRE responsible for GCP cost visibility across datum-cloud infrastructure. +Produces weekly spend reports and identifies optimization opportunities. + +## Workflow + +Load `analyze-gcp-spend` skill, then follow its workflow: + +1. **Determine cadence** — check today's date; select full-month (day ≤ 7) or MTD mode +2. **Query BigQuery** — billing data for both `datum-cloud-prod` and `datum-cloud-staging` +3. **Query live state** — node pools, PVCs, Cloud SQL from both clusters +4. **Build 4-month trend** — trailing-4-months BigQuery query → mermaid chart data +5. **Draft report** — compute section totals, write Top Issues, fill mermaid charts +6. **Open PR** — write to `/workspace/engineering`, commit, push, create PR + +## Skills + +- `analyze-gcp-spend` — billing queries, live state commands, report format, PR workflow + +## Output + +A pull request to `/workspace/engineering` at `reports/gcp-spend/YYYY-MM-DD-gcp-spend.md`. +Branch: `ops/gcp-spend-YYYY-MM-DD`. See `analyze-gcp-spend/report-format.md` for full conventions. diff --git a/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md b/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md new file mode 100644 index 0000000..845e1f1 --- /dev/null +++ b/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md @@ -0,0 +1,68 @@ +--- +name: analyze-gcp-spend +description: > + Produces a GCP spend report covering all datum-cloud infrastructure across staging and production. + On the first week of the month (run date ≤ day 7), performs a full retrospective for the prior + calendar month. Otherwise produces an MTD snapshot. Queries BigQuery billing exports and live + cluster state, generates mermaid trend charts for the trailing 4 months, and files a PR to + the engineering repo. +--- + +# GCP Spend Analysis + +Produces a GCP spend report for all datum-cloud infrastructure (staging + production). +Run weekly on Mondays. On the first week of the month (run date ≤ day 7), produces a full +retrospective for the prior calendar month. All other weeks produce a month-to-date snapshot. + +## Cadence Logic + +| Run date | Reporting period | Report type | +|----------|-----------------|-------------| +| Day 1–7 of month | Previous calendar month (full) | Full monthly retrospective | +| Day 8+ of month | Current month-to-date | MTD snapshot | + +## Scope + +| Environment | GCP Project ID | Cluster | Region | +|-------------|---------------|---------|--------| +| Production | `datum-cloud-prod` | `datum-prod` | us-east4 | +| Staging | `datum-cloud-staging` | `datum-staging` | us-east4 | + +Edge clusters (dfw, tyo, syd, etc.) run outside GCP — exclude from this analysis. + +## Workflow + +1. **Determine period** — check today's date; select full-month (day ≤ 7) or MTD mode +2. **Query billing** — run BigQuery queries from `queries.md` for services, SKUs, and storage +3. **Query live state** — pull current node pools, PVC inventory, and Cloud SQL from both clusters +4. **Compute 4-month trend** — run the trailing-4-months query; populate mermaid chart data +5. **Identify issues** — compare billing data to live state; flag IaC drift, oversized resources, + generation-penalty instances (n1 vs n2), and unexpected on-demand pools +6. **Draft report** — follow the structure and mermaid templates in `report-format.md` +7. **File PR** — write to `/workspace/engineering` and open a PR via `gh pr create` + +## What to Flag + +- **IaC drift** — node pools or resources visible in the cluster but absent from Pulumi/IaC config +- **Generation penalty** — n1 instances cost ~15% more than equivalent n2; flag and quantify savings +- **Spot vs on-demand transitions** — note any pools that switched from spot to on-demand; compute delta +- **Oversized storage** — PVCs provisioned much larger than workload requirements (flag if detectable) +- **Single points of failure on premium storage** — hyperdisk-balanced or pd-ssd on unreplicated nodes +- **Month-over-month deltas** — any service that increased >10% MoM warrants a note in Top Issues + +## Infrastructure + +- **Billing source**: BigQuery billing export — see `queries.md` for table discovery +- **Live state**: `gcloud`, `kubectl` — commands in `queries.md` +- **Target repo**: `/workspace/engineering` +- **Output path**: `reports/gcp-spend/YYYY-MM-DD-gcp-spend.md` + +## Sub-topics + +- `queries.md` — BigQuery billing SQL, gcloud and kubectl commands, 4-month trend queries +- `report-format.md` — report sections, mermaid chart templates, PR workflow and git commands + +## Related Skills + +- `operational-review` — Weekly traffic and latency report for the Envoy edge ingress +- `capability-quota` — Quota system that can gate resource consumption and bound costs diff --git a/plugins/datum-platform/skills/analyze-gcp-spend/queries.md b/plugins/datum-platform/skills/analyze-gcp-spend/queries.md new file mode 100644 index 0000000..b659c93 --- /dev/null +++ b/plugins/datum-platform/skills/analyze-gcp-spend/queries.md @@ -0,0 +1,178 @@ +# GCP Billing Queries + +## Finding the Billing Export Table + +```bash +bq ls --project_id datum-cloud-prod billing +``` + +The export table is typically named `gcp_billing_export_resource_v1_{ACCOUNT_ID}`. Replace +`{BILLING_TABLE}` throughout this file with the fully-qualified table reference, e.g.: +`datum-cloud-prod.billing.gcp_billing_export_resource_v1_XXXXXX_XXXXXX_XXXXXX` + +## GCP Projects in Scope + +| Environment | Project ID | +|-------------|-----------| +| Production | `datum-cloud-prod` | +| Staging | `datum-cloud-staging` | + +## Period Parameters + +Set `@period_start` and `@period_end` based on the cadence rule in `SKILL.md`: + +| Mode | @period_start | @period_end | +|------|--------------|-------------| +| Full month (day ≤ 7) | First day of prior month | First day of current month | +| MTD (day ≥ 8) | First day of current month | Tomorrow | + +## Cost by Service + +```sql +SELECT + project.id AS project, + service.description AS service, + SUM(cost) AS total_cost +FROM `{BILLING_TABLE}` +WHERE + DATE(_PARTITIONTIME) >= @period_start + AND DATE(_PARTITIONTIME) < @period_end + AND project.id IN ('datum-cloud-prod', 'datum-cloud-staging') +GROUP BY project, service +ORDER BY total_cost DESC +``` + +## Cost by SKU (Compute + GKE Detail) + +```sql +SELECT + project.id AS project, + service.description AS service, + sku.description AS sku, + SUM(cost) AS total_cost +FROM `{BILLING_TABLE}` +WHERE + DATE(_PARTITIONTIME) >= @period_start + AND DATE(_PARTITIONTIME) < @period_end + AND project.id IN ('datum-cloud-prod', 'datum-cloud-staging') + AND service.description IN ('Compute Engine', 'Kubernetes Engine') +GROUP BY project, service, sku +ORDER BY total_cost DESC +LIMIT 50 +``` + +## Storage Breakdown + +```sql +SELECT + project.id AS project, + sku.description AS sku, + SUM(cost) AS total_cost +FROM `{BILLING_TABLE}` +WHERE + DATE(_PARTITIONTIME) >= @period_start + AND DATE(_PARTITIONTIME) < @period_end + AND project.id IN ('datum-cloud-prod', 'datum-cloud-staging') + AND service.description = 'Compute Engine' + AND (sku.description LIKE '%Storage%' OR sku.description LIKE '%Disk%') +GROUP BY project, sku +ORDER BY total_cost DESC +``` + +## 4-Month Trend by Service + +Returns monthly totals for the trailing 4 calendar months to power the mermaid trend charts. +Run this query regardless of cadence mode — trend always covers the trailing 4 full months. + +```sql +SELECT + DATE_TRUNC(DATE(_PARTITIONTIME), MONTH) AS month, + project.id AS project, + service.description AS service, + SUM(cost) AS total_cost +FROM `{BILLING_TABLE}` +WHERE + DATE(_PARTITIONTIME) >= DATE_TRUNC(DATE_SUB(CURRENT_DATE(), INTERVAL 3 MONTH), MONTH) + AND project.id IN ('datum-cloud-prod', 'datum-cloud-staging') +GROUP BY month, project, service +ORDER BY month, total_cost DESC +``` + +Aggregate service rows into three buckets for charting: + +| Chart bucket | Billing service rows | +|-------------|---------------------| +| Compute | Compute Engine, Kubernetes Engine | +| Storage | Cloud Storage, Filestore, plus storage/disk SKUs within Compute Engine | +| Other | Cloud SQL, Networking, and everything else | + +## Cloud SQL Inventory + +```bash +gcloud sql instances list \ + --project datum-cloud-prod \ + --format="table(name, databaseVersion, tier, settings.availabilityType, state, diskSizeGb)" + +gcloud sql instances list \ + --project datum-cloud-staging \ + --format="table(name, databaseVersion, tier, settings.availabilityType, state, diskSizeGb)" +``` + +Cloud SQL cost from billing is often understated if disk size isn't exported. Use the +`diskSizeGb` field above to sanity-check storage costs. + +## Live Node Pool Inventory + +```bash +# Production +gcloud container node-pools list \ + --cluster datum-prod \ + --region us-east4 \ + --project datum-cloud-prod \ + --format="table(name, config.machineType, config.spot, autoscaling.minNodeCount, autoscaling.maxNodeCount, initialNodeCount)" + +# Staging +gcloud container node-pools list \ + --cluster datum-staging \ + --region us-east4 \ + --project datum-cloud-staging \ + --format="table(name, config.machineType, config.spot, autoscaling.minNodeCount, autoscaling.maxNodeCount, initialNodeCount)" +``` + +Cross-reference the node pool list against the Pulumi/IaC config in the infrastructure repo. +Any pool not present in IaC should be flagged as drift in the Top Issues section. + +## Live PVC Inventory + +```bash +# Production +kubectl get pvc --all-namespaces --context datum-prod \ + -o custom-columns="NS:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.storageClassName,CAPACITY:.status.capacity.storage" + +# Staging +kubectl get pvc --all-namespaces --context datum-staging \ + -o custom-columns="NS:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.storageClassName,CAPACITY:.status.capacity.storage" +``` + +Sum capacity by storage class; reconcile against the Storage section of the billing query output. +Significant gaps between provisioned and billed storage can indicate orphaned volumes. + +## GCP List Prices (us-east4 Reference) + +Use these for cost decomposition when billing data is aggregated and you need to back-calculate +per-node or per-GiB costs. These are on-demand list prices — actual bill may reflect CUDs or SUDs. + +| Resource | Price | +|----------|-------| +| n1-standard-8 (on-demand) | ~$277/month | +| n2-standard-8 (on-demand) | ~$239/month | +| n2d-standard-8 (on-demand) | ~$228/month | +| n2d-standard-2 (on-demand) | ~$57/month | +| n2d-standard-2 (spot) | ~$17/month | +| c4d-standard-8 (on-demand) | ~$312/month | +| n2-standard-4 (on-demand) | ~$139/month | +| hyperdisk-balanced | $0.12/GiB/month | +| pd-ssd (`premium-rwo`) | $0.17/GiB/month | +| pd-balanced (`standard-rwo`) | $0.10/GiB/month | +| pd-standard | $0.04/GiB/month | +| GKE cluster fee | $72/month per cluster | diff --git a/plugins/datum-platform/skills/analyze-gcp-spend/report-format.md b/plugins/datum-platform/skills/analyze-gcp-spend/report-format.md new file mode 100644 index 0000000..944d4b8 --- /dev/null +++ b/plugins/datum-platform/skills/analyze-gcp-spend/report-format.md @@ -0,0 +1,197 @@ +# Report Format and Publishing + +## File Convention + +| Attribute | Value | +|-----------|-------| +| Repo | `/workspace/engineering` | +| Path | `reports/gcp-spend/YYYY-MM-DD-gcp-spend.md` | +| Branch | `ops/gcp-spend-YYYY-MM-DD` | +| PR title (full month) | `Ops Review: GCP spend [Month YYYY] — full month` | +| PR title (MTD) | `Ops Review: GCP spend YYYY-MM-DD` | + +`YYYY-MM-DD` is today's date (the run date). The reporting period is described inside the report. + +## Report Structure + +```markdown +# GCP Spend Analysis — [Month YYYY | MTD YYYY-MM-DD] +*As of YYYY-MM-DD. Computed from BigQuery billing export × live cluster state (us-east4). +[No CUD discounts applied. | CUD/SUD discounts reflected.]* + +## Summary: ~$X,XXX/month + +| Environment | Cost | +|-------------|------| +| Production | $X,XXX | +| Staging | $X,XXX | +| **Total** | **$X,XXX** | + +--- + +## Compute: $X,XXX/month + +| Count | Instance | Type | Pool | $/month | +|-------|----------|------|------|---------| +| N× | machine-type | ON-DEMAND / SPOT | pool-name | $X,XXX | + +## Storage: $X,XXX/month + +| Storage class | Total | Rate | $/month | +|--------------|-------|------|---------| +| `hyperdisk-balanced` | N GiB | $0.12/GiB | $X,XXX | +| `premium-rwo` (pd-ssd) | N GiB | $0.17/GiB | $X,XXX | +| `standard-rwo` (pd-balanced) | N GiB | $0.10/GiB | $X,XXX | + +## Cloud SQL: ~$XXX/month (estimated) + +[Tier, HA config, disk size if available. Note if disk size unknown and why.] + +--- + +## 4-Month Spend Trend + +### Total Monthly Spend (Production + Staging) + +Replace x-axis labels with the actual trailing 4 month abbreviations and fill in dollar totals. + +```mermaid +xychart-beta + title "GCP Monthly Spend — datum-cloud (prod + staging)" + x-axis ["Mon-1", "Mon-2", "Mon-3", "Mon-4"] + y-axis "USD" 0 --> UPPER + bar [TOTAL-1, TOTAL-2, TOTAL-3, TOTAL-4] +``` + +### Spend by Category (Production) + +Three series: Compute, Storage, Other. Pull from the 4-month trend query bucketed by category. + +```mermaid +xychart-beta + title "Production: Monthly Spend by Category" + x-axis ["Mon-1", "Mon-2", "Mon-3", "Mon-4"] + y-axis "USD" 0 --> UPPER + line [COMPUTE-1, COMPUTE-2, COMPUTE-3, COMPUTE-4] + line [STORAGE-1, STORAGE-2, STORAGE-3, STORAGE-4] + line [OTHER-1, OTHER-2, OTHER-3, OTHER-4] +``` + +*Series order: Compute Engine + GKE, Storage, Cloud SQL + Networking* + +### Production vs Staging Split + +```mermaid +xychart-beta + title "Monthly Spend: Production vs Staging" + x-axis ["Mon-1", "Mon-2", "Mon-3", "Mon-4"] + y-axis "USD" 0 --> UPPER + bar [PROD-1, PROD-2, PROD-3, PROD-4] + bar [STAGING-1, STAGING-2, STAGING-3, STAGING-4] +``` + +*First bar series = Production, second bar series = Staging* + +**Chart tips:** +- Set `UPPER` to the maximum monthly total rounded up by ~20% so bars aren't clipped +- Use abbreviated month names: Jan, Feb, Mar, Apr (or whichever 4 trailing months apply) +- Omit chart series that are zero or negligible (< 1% of total) + +--- + +## Top Issues + +Sort descending by dollar impact. Include an estimate for each. + +### 1. [Issue Name] — ~$X,XXX/month [combined | estimated] +- Bullet: specific resource or pool driving the cost +- Bullet: question or finding (e.g. is utilization matching provisioned capacity?) +- Bullet: comparison to prior month if notable + +[Repeat for each significant cost driver. Aim for 4–6 issues.] + +--- + +## Recent Changes That Drove Cost + +| Date | Change | Impact | +|------|--------|--------| +| YYYY-MM-DD | Description | +/- ~$X/month | + +Pull from git log of the infrastructure/Pulumi repo and compare to prior period node pool and +PVC state. Flag spot→on-demand transitions, new pools, and PVC resizes. + +--- + +## Optimization Opportunities + +| Action | Estimated Saving | +|--------|-----------------| +| Description | ~$X/month | + +--- + +## Notes + +- Edge clusters excluded (non-GCP infrastructure) +- List prices used; actual bill may be lower with active CUDs or negotiated rates +- [Any estimates or unknowns, e.g. Cloud SQL disk size not exported to billing] +``` + +## Mermaid Chart Guidelines + +- Use `xychart-beta` — it renders in GitHub PR previews +- X-axis: abbreviated month names for the trailing 4 months (e.g. `["Jan", "Feb", "Mar", "Apr"]`) +- Y-axis upper bound (`UPPER`): round the maximum value up by ~20% +- `bar` for total and per-environment breakdown; `line` for multi-series category breakdown +- Keep x-axis labels consistent across all three charts in the same report +- If a month is partial (current MTD), label it `"Apr*"` with a footnote + +## PR Body Template + +```markdown +## Ops Review — GCP Spend Analysis + +[Full month retrospective for {Month YYYY} | MTD snapshot through {YYYY-MM-DD}] + +## Summary + +- **$X,XXX total** (production $X,XXX · staging $X,XXX) +- **Top cost driver:** {driver} (~$X,XXX/month) +- **{N} optimization opportunities** identified (~$X,XXX combined potential savings) +- {One-line notable finding, e.g. IaC drift} +- {One-line notable finding, e.g. generation-penalty nodes} + +## Report + +`reports/gcp-spend/YYYY-MM-DD-gcp-spend.md` +``` + +## Git Workflow + +```bash +# From /workspace/engineering +git checkout main && git pull +git checkout -b ops/gcp-spend-YYYY-MM-DD +mkdir -p reports/gcp-spend +# Write the report file, then: +git add reports/gcp-spend/YYYY-MM-DD-gcp-spend.md +git commit -m "ops: add GCP spend report for YYYY-MM-DD" +git push -u origin ops/gcp-spend-YYYY-MM-DD +gh pr create \ + --title "Ops Review: GCP spend YYYY-MM-DD" \ + --body "$(cat <<'EOF' +## Ops Review — GCP Spend Analysis +... +EOF +)" +``` + +## Incremental Updates + +If run a second time in the same period (e.g. to correct a figure or add a section): + +1. Check out the existing branch: `git checkout ops/gcp-spend-YYYY-MM-DD` +2. Update only the changed figures or add the new section in the appropriate position +3. Commit: `ops: update GCP spend report YYYY-MM-DD — {what changed}` +4. Push — the existing PR updates automatically; no new PR needed From e784bd93121a28f81c628ef15307fb7fd3c43adb Mon Sep 17 00:00:00 2001 From: Drew Raines Date: Sat, 25 Apr 2026 17:41:01 +0000 Subject: [PATCH 2/3] fix(analyze-gcp-spend): correct cluster names and add preflight checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cluster names datum-prod/datum-staging do not exist; correct to infrastructure-control-plane-{prod,staging} in SKILL.md and queries.md (node pool and PVC inventory commands). Add a Preflight Checks section to SKILL.md that validates BigQuery billing export access before proceeding. BigQuery is a hard requirement — storage and Cloud SQL costs are invisible without it, causing the report to understate spend by $2,000–$3,000/month. The skill now requires stopping and surfacing the access error rather than publishing an estimate-based report as authoritative. --- .../skills/analyze-gcp-spend/SKILL.md | 47 +++++++++++++++---- .../skills/analyze-gcp-spend/queries.md | 8 ++-- 2 files changed, 42 insertions(+), 13 deletions(-) diff --git a/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md b/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md index 845e1f1..de40dbe 100644 --- a/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md +++ b/plugins/datum-platform/skills/analyze-gcp-spend/SKILL.md @@ -25,21 +25,50 @@ retrospective for the prior calendar month. All other weeks produce a month-to-d | Environment | GCP Project ID | Cluster | Region | |-------------|---------------|---------|--------| -| Production | `datum-cloud-prod` | `datum-prod` | us-east4 | -| Staging | `datum-cloud-staging` | `datum-staging` | us-east4 | +| Production | `datum-cloud-prod` | `infrastructure-control-plane-prod` | us-east4 | +| Staging | `datum-cloud-staging` | `infrastructure-control-plane-staging` | us-east4 | Edge clusters (dfw, tyo, syd, etc.) run outside GCP — exclude from this analysis. +## Preflight Checks + +Run these before doing any work. If BigQuery fails, stop and report — do not proceed +with estimates in place of real billing data. + +```bash +# 1. Verify BigQuery billing export is accessible +bq ls --project_id datum-cloud-prod billing +# Expected: lists at least one table named gcp_billing_export_resource_v1_* +# Failure → stop. Fix: grant bigquery.jobs.create + bigquery.tables.getData +# on the billing dataset to the active service account or user. + +# 2. Verify prod cluster is reachable +gcloud container clusters list --project datum-cloud-prod --format="value(name)" +# Expected: infrastructure-control-plane-prod +# Failure → note in report, use IaC config for prod compute section only + +# 3. Verify staging cluster is reachable +gcloud container clusters list --project datum-cloud-staging --format="value(name)" +# Expected: infrastructure-control-plane-staging +# Failure → note in report, use IaC config for staging compute section only +``` + +**BigQuery is a hard requirement.** Storage and Cloud SQL are only visible in the billing +export — without it the report is missing $2,000–$3,000/month of spend. A report produced +without billing data will be materially wrong. Stop and surface the access error; do not +publish an estimate-based report as if it were authoritative. + ## Workflow -1. **Determine period** — check today's date; select full-month (day ≤ 7) or MTD mode -2. **Query billing** — run BigQuery queries from `queries.md` for services, SKUs, and storage -3. **Query live state** — pull current node pools, PVC inventory, and Cloud SQL from both clusters -4. **Compute 4-month trend** — run the trailing-4-months query; populate mermaid chart data -5. **Identify issues** — compare billing data to live state; flag IaC drift, oversized resources, +1. **Preflight** — run the checks above; halt on BigQuery failure +2. **Determine period** — check today's date; select full-month (day ≤ 7) or MTD mode +3. **Query billing** — run BigQuery queries from `queries.md` for services, SKUs, and storage +4. **Query live state** — pull current node pools, PVC inventory, and Cloud SQL from both clusters +5. **Compute 4-month trend** — run the trailing-4-months query; populate mermaid chart data +6. **Identify issues** — compare billing data to live state; flag IaC drift, oversized resources, generation-penalty instances (n1 vs n2), and unexpected on-demand pools -6. **Draft report** — follow the structure and mermaid templates in `report-format.md` -7. **File PR** — write to `/workspace/engineering` and open a PR via `gh pr create` +7. **Draft report** — follow the structure and mermaid templates in `report-format.md` +8. **File PR** — write to `/workspace/engineering` and open a PR via `gh pr create` ## What to Flag diff --git a/plugins/datum-platform/skills/analyze-gcp-spend/queries.md b/plugins/datum-platform/skills/analyze-gcp-spend/queries.md index b659c93..0a7013c 100644 --- a/plugins/datum-platform/skills/analyze-gcp-spend/queries.md +++ b/plugins/datum-platform/skills/analyze-gcp-spend/queries.md @@ -126,14 +126,14 @@ Cloud SQL cost from billing is often understated if disk size isn't exported. Us ```bash # Production gcloud container node-pools list \ - --cluster datum-prod \ + --cluster infrastructure-control-plane-prod \ --region us-east4 \ --project datum-cloud-prod \ --format="table(name, config.machineType, config.spot, autoscaling.minNodeCount, autoscaling.maxNodeCount, initialNodeCount)" # Staging gcloud container node-pools list \ - --cluster datum-staging \ + --cluster infrastructure-control-plane-staging \ --region us-east4 \ --project datum-cloud-staging \ --format="table(name, config.machineType, config.spot, autoscaling.minNodeCount, autoscaling.maxNodeCount, initialNodeCount)" @@ -146,11 +146,11 @@ Any pool not present in IaC should be flagged as drift in the Top Issues section ```bash # Production -kubectl get pvc --all-namespaces --context datum-prod \ +kubectl get pvc --all-namespaces --context infrastructure-control-plane-prod \ -o custom-columns="NS:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.storageClassName,CAPACITY:.status.capacity.storage" # Staging -kubectl get pvc --all-namespaces --context datum-staging \ +kubectl get pvc --all-namespaces --context infrastructure-control-plane-staging \ -o custom-columns="NS:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.storageClassName,CAPACITY:.status.capacity.storage" ``` From 9ce2f89a3b889dd191dd701507bfafb3f25acc49 Mon Sep 17 00:00:00 2001 From: Drew Raines Date: Mon, 11 May 2026 13:17:42 +0000 Subject: [PATCH 3/3] fix(operational-review): comment on oncall issue when traffic report PR is opened --- CHANGELOG.md | 6 ++++++ README.md | 2 +- plugins/datum-platform/.claude-plugin/plugin.json | 2 +- .../skills/operational-review/report-format.md | 14 +++++++++++++- 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 078d53c..be9b32b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ Notable changes to the Datum Cloud Claude Code plugins. +## [1.7.1] - 2026-05-11 + +### Changed + +- **Operational review skill** (`operational-review`) — After opening the traffic report PR, now finds the current on-call issue in `datum-cloud/engineering` (open issue titled "on-call: week of …") and posts a comment linking the review. + ## [1.7.0] - 2026-04-25 ### Added diff --git a/README.md b/README.md index af13e81..c1808e1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A marketplace for Claude Code plugins providing platform engineering tools and a | Plugin | Description | Version | |--------|-------------|---------| -| [datum-platform](./plugins/datum-platform/) | Kubernetes platform engineering automation with aggregated API servers, controller patterns, and GitOps deployment | 1.7.0 | +| [datum-platform](./plugins/datum-platform/) | Kubernetes platform engineering automation with aggregated API servers, controller patterns, and GitOps deployment | 1.7.1 | | [datum-gtm](./plugins/datum-gtm/) | Go-to-market automation with commercial strategy, product discovery, and customer support | 1.0.0 | | [milo-activity](./plugins/milo-activity/) | Query audit logs, investigate incidents, and author ActivityPolicies using the Milo Activity service | 1.0.0 | diff --git a/plugins/datum-platform/.claude-plugin/plugin.json b/plugins/datum-platform/.claude-plugin/plugin.json index 5e5821d..eb956d2 100644 --- a/plugins/datum-platform/.claude-plugin/plugin.json +++ b/plugins/datum-platform/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "datum-platform", "description": "Kubernetes platform engineering automation with aggregated API servers, controller patterns, GitOps deployment, and platform capabilities", - "version": "1.7.0", + "version": "1.7.1", "author": { "name": "Datum Cloud", "url": "https://github.com/datum-cloud" diff --git a/plugins/datum-platform/skills/operational-review/report-format.md b/plugins/datum-platform/skills/operational-review/report-format.md index d37b1b7..8c8d58e 100644 --- a/plugins/datum-platform/skills/operational-review/report-format.md +++ b/plugins/datum-platform/skills/operational-review/report-format.md @@ -124,7 +124,19 @@ mkdir -p reports/traffic git add reports/traffic/YYYY-MM-DD-datum-traffic.md git commit -m "ops: add weekly traffic report for YYYY-MM-DD" git push -u origin ops/traffic-report-YYYY-MM-DD -gh pr create --title "Ops Review: Weekly traffic report YYYY-MM-DD" --body "..." +PR_URL=$(gh pr create --title "Ops Review: Weekly traffic report YYYY-MM-DD" --body "..." | tail -1) + +# Find the current on-call issue and drop a comment linking the review +ONCALL_ISSUE=$(gh issue list \ + --repo datum-cloud/engineering \ + --search "on-call: week of" \ + --state open \ + --json number,title \ + --jq '.[0].number') + +gh issue comment "$ONCALL_ISSUE" \ + --repo datum-cloud/engineering \ + --body "Weekly traffic report open for review: $PR_URL" ``` ## Incremental Updates