Add Provider

Add Provider

Orchestrates adding a new Grafana product provider — from API discovery through verified implementation. Four stages with human approval gates.

When to Use

• User wants to add CLI support for a Grafana Cloud product
• User says "add provider", "new provider", "integrate [product]"
• A bead task references provider implementation

When NOT to use: If the product exposes a K8s-compatible /apis endpoint, it already works with gcx resources — no provider needed.

First: Check references/decision-tree.md to confirm a provider is the right approach.

Workflow

Discover ──gate──> Design ──gate──> Implement ──gate──> Verify
   │                  │                  │                  │
   v                  v                  v                  v
research report    ADRs + spec       code per stage     smoke tests

Prerequisites

Confirm with the user before starting:

• Product name — which Grafana product to integrate
• Access — do they have a running Grafana instance with the product enabled?
• Scope — full provider or single resource type first?

---

Stage 1: Discover

Guide: docs/reference/provider-discovery-guide.md Sections 1.1–1.6

1a. Gather User Context

Before autonomous research, ask what the user already knows:

1. Source code access — which repo? 2. API documentation — OpenAPI specs, Grafana docs URLs? 3. Terraform resources — does the Terraform provider support this product? 4. Go SDK — existing Go client library? 5. Known quirks — non-standard auth, async ops, unusual pagination?

Use answers to skip known areas and focus research on gaps.

1b. Research

Follow provider-discovery-guide.md Sections 1.1–1.6:

• Map API surface (base path, auth, endpoints, pagination)
• Check existing tooling (Terraform schemas, Go SDK)
• Inspect source code (undocumented endpoints, enum values)
• Identify auth model
• Map resource relationships
• Test API behavior with real calls

1c. Write Research Report

Write findings to docs/research/YYYY-MM-DD-{product}-provider.md using the template at docs/_templates/research.md. Must include:

• API endpoints and response shapes discovered
• Auth model analysis
• Resource relationships
• At least one successful API call result
• Confidence assessment per finding

Gate: User Approves Research

Present the research report. Do not proceed to design until approved.

---

Stage 2: Design

Guide: docs/reference/provider-discovery-guide.md Section 2

2a. Design Decisions

Answer each decision from the guide, grounded in research findings:

1. Auth strategy — reuse Grafana token or separate credentials? 2. Client type — plugin API, K8s API, or external service? 3. Envelope mapping — how do API objects map to K8s envelope? 4. Command surface — CRUD + which beyond-CRUD commands? 5. Package layout — flat or subpackaged? 6. Staging — how to break into shippable stages?

For beyond-CRUD commands: brainstorm based on real APIs found in research (status, timeline, validation, etc.). Present options to user — include "CRUD only for now" as an option.

2b. Write ADRs

For each significant decision, write an ADR in docs/adrs/{product}-provider/NNN-{decision}.md using the template at docs/_templates/adr.md. At minimum, create ADRs for:

• Auth strategy choice
• Client type choice (plugin API vs K8s vs external)

Other decisions can be captured in the spec if they're straightforward.

2c. Write Spec

Write the implementation plan in docs/specs/{product}-provider/:

• Top-level plan with all stages, file tree, and decisions summary
• Per-stage docs with scope, files to create, and acceptance criteria

Reference implementations for plan structure:

• SLO: docs/specs/slo-provider/2026-03-04-slo-provider-plan.md
• Synth: docs/specs/synth-provider/2026-03-06-synth-provider-plan.md

2d. Write Smoke Test Plan

Every stage doc MUST include a Verification section with concrete smoke test commands using real values (not placeholders). These are executed in Stage 4 after implementation.

Example pattern (replace with real product/resource names in actual spec):

# Provider appears in list
gcx providers | grep {name}

# Config secrets are redacted
gcx config view | grep {name}

# CRUD operations work
gcx {name} {resource} list
gcx {name} {resource} get <test-id>
gcx {name} {resource} push ./testdata/{resource}.yaml
gcx {name} {resource} pull -d ./tmp/
gcx {name} {resource} delete <test-id> --yes

# Unified resources path works
gcx resources get {alias}

Gate: User Approves Design

Present ADRs and spec. Do not proceed to implementation until approved.

---

Stage 3: Implement

Guide: docs/reference/provider-guide.md (Steps 1–7)

UX Guide: docs/reference/design-guide.md (all [CURRENT] and [ADOPT] items)

Implement one stage at a time per the approved spec. Each stage's doc is self-contained enough to resume in a fresh session.

If /build-spec or /build-task skills are available, use them to drive implementation. Otherwise, follow provider-guide.md Steps 1–7 directly. Summary of the key steps:

1. Provider interface + init() + configLoader (copy from SLO reference) 2. Config keys + validation 3. Commands with UX compliance 4. Types + client + adapter per resource type 5. Register (blank import + ResourceAdapter) 6. Tests (interface compliance, adapter round-trip, client httptest)

Key patterns (see provider-guide.md for details):

• Hand-roll HTTP client (~200 LOC) — don't use generated OpenAPI clients
• Copy full configLoader from internal/providers/slo/provider.go
• Config key names use hyphen-case
• Adapter must strip server-generated fields on Create/Update

Gate: Stage Complete

Per stage: make all passes, no regressions.

---

Stage 4: Verify

4a. Run Smoke Tests

Execute every smoke test command from the Stage 2d verification plan against a real Grafana instance. Record results (pass/fail + output).

4b. Run Checklists

From docs/reference/design-guide.md Section 7 and docs/reference/provider-guide.md:

Interface: All 5 Provider methods, Name() lowercase/unique, ConfigKeys complete, secrets marked, Validate returns actionable errors, blank import added.

UX: -o json/yaml support, text table default, actionable error suggestions, no os.Exit(), cmdio status messages, help text standards, push idempotent, format-agnostic data fetching, promql-builder for PromQL.

Build: make all, gcx providers lists it, config view redacts.

4c. Update Architecture Docs

Follow docs/reference/doc-maintenance.md structural checks — a new provider adds packages to internal/ and commands to cmd/, so architecture docs need updating.

Gate: All Green

All smoke tests pass, all checklists green, docs updated.

---

Reference Implementations

Spec plans: docs/specs/slo-provider/, docs/specs/synth-provider/

Common Pitfalls

Decision Tree: Provider vs Resources Command

When should you create a new provider vs using the existing gcx resources command?

Quick Decision

Does the product expose a K8s-compatible API via Grafana's /apis endpoint?
├── YES → Use existing `gcx resources` command (no provider needed)
│         The resource is already discoverable and manageable.
│
└── NO → Does the product have its own REST API?
    ├── YES → Create a new provider
    │         The provider wraps the product's REST API and translates
    │         to/from the K8s envelope format.
    │
    └── NO → The product likely has no external API.
              Check if it's a UI-only feature or if the API is internal.
              → Cannot integrate without an accessible API.

Detailed Criteria

Use gcx resources (NO provider needed) when:

• The product registers K8s-style CRDs accessible via /apis/{group}/{version}/...
• Resources appear in gcx resources schemas
• Standard CRUD operations work via the dynamic client
• No product-specific auth beyond the Grafana service account token

Examples: Dashboards, Folders, AlertRules, ContactPoints — these all use Grafana's native K8s API and need no provider.

Create a new provider when:

• The product uses a plugin API (/api/plugins/{id}/resources/...)
• The product requires product-specific authentication or configuration
• The product's API returns non-K8s response envelopes
• You need product-specific commands beyond basic CRUD (e.g., status, timeline)
• The product has multiple related resource types that should be grouped

Examples: SLO (plugin API, custom status commands), Synthetic Monitoring (separate service URL + token), OnCall (separate API).

Important: CRUD via unified resources path. Once a provider implements ResourceAdapter and registers a static descriptor (via adapter.Register() in its init() function), its resource types become accessible through the unified gcx resources command:

gcx resources get slo           # replaces: gcx slo definitions list
gcx resources get slo/<uuid>   # replaces: gcx slo definitions get <uuid>
gcx resources push slo -p ./   # replaces: gcx slo definitions push
gcx resources pull slo -p ./   # replaces: gcx slo definitions pull
gcx resources delete slo/<id>  # replaces: gcx slo definitions delete <id>

The provider-specific top-level commands (gcx slo, gcx synth, gcx alert) remain available for backward compatibility but print a deprecation warning to stderr. New providers should implement ResourceAdapter alongside the existing command tree from the start.

Edge cases

Auth Decision Matrix

Validation

Before committing to a provider, verify with a real API call:

# Test if K8s API works (if yes → no provider needed)
curl -s -H "Authorization: Bearer $TOKEN" \
  "$GRAFANA_URL/apis/" | jq '.groups[].name' | grep {product}

# Test plugin API (if this works → provider needed)
curl -s -H "Authorization: Bearer $TOKEN" \
  "$GRAFANA_URL/api/plugins/{product}-app/resources/v1/"

If neither works, investigate the product's source code for route registration.