feat(provision): kongctl bootstrap scripts for OpenMeter catalog by eliteprox · Pull Request #53 · livepeer/clearinghouse

eliteprox · 2026-06-30T17:05:46Z

Summary

Add openmeter-collector/provision/ — idempotent Konnect metering bootstrap via kongctl api (catalog, customers, plan publishing)
Update root README to reference the new scripts instead of the Go clearinghouse-bootstrap CLI

Replaces #51's scope with a clean branch off main (no collector or identity-webhook changes).

Manual test walkthrough (verified)

End-to-end test against a fresh Konnect org so the catalog starts empty.

1. Create a new Konnect org

From the org picker, click + Create to provision a clean Metering & Billing workspace.

2. Name the org

Example used for this test: Clearinghouse Example Org.

3. Create a Personal Access Token for bootstrap

Profile menu → Personal access tokens → Generate.

Name: admin provisioning (or similar)
Expiration: e.g. 30 days
Copy the kpat_… token immediately — it is shown only once.

4. Set the env file

cp openmeter-collector/.env.example openmeter-collector/.env
# edit OPENMETER_API_KEY=kpat_…  (the PAT from step 3)

The bootstrap scripts auto-load openmeter-collector/.env — no need to source it.

5. Run catalog bootstrap (first run)

cd openmeter-collector/provision
./bootstrap.sh catalog

Observed output (fresh org — all objects created):

== catalog (https://us.api.konghq.com/v3/openmeter) ==
meter   network_fee_usd_micros — created
meter   billable_usd_micros — created
meter   signed_ticket_count — created
feature network_spend — created
feature billable_spend — created
plan    clearinghouse_default_ppu — created (draft)
plan    clearinghouse_default_ppu — published
done.

6. Re-run — idempotency confirmed

./bootstrap.sh catalog

Observed output (existing objects left untouched):

== catalog (https://us.api.konghq.com/v3/openmeter) ==
meter   network_fee_usd_micros — exists
meter   billable_usd_micros — exists
meter   signed_ticket_count — exists
feature network_spend — exists
feature billable_spend — exists
plan    clearinghouse_default_ppu — active
done.

Test plan

Prerequisites

kongctl and jq installed (command -v kongctl jq)
Konnect Personal Access Token (kpat_…) with Metering & Billing access
openmeter-collector/.env configured with OPENMETER_API_KEY

Catalog bootstrap

./bootstrap.sh catalog on fresh org — all meters/features/plan created
Re-run ./bootstrap.sh catalog — all lines exists / active, no errors

Customer provisioning

./bootstrap.sh customer demo-client demo-user "Demo User"
./bootstrap.sh all demo-client demo-user "Demo User" --subscribe

README

Root README bootstrap section links to openmeter-collector/provision/README.md
Quick-start ./bootstrap.sh commands match the provision README

Replace the Go clearinghouse-bootstrap CLI with thin cross-platform kongctl scripts and a JSON catalog for idempotent Konnect metering setup.

rickstaa

@eliteprox looks good to me. I good it working with the instructions. I did however run into one issue though. The .env.example does not contain the OPENMETER_URL placeholder which will cause it to always fallback to https://us.api.konghq.com/v3/openmeter which will print the following:

== catalog (https://us.api.konghq.com/v3/openmeter) ==
meter   network_fee_usd_micros — exists
meter   billable_usd_micros — exists
meter   signed_ticket_count — exists
feature network_spend — exists
feature billable_spend — exists
plan    clearinghouse_default_ppu — active
done.

But not create anything on my org as I'm in the eu region. Could be your script is not handling errors correctly.

Good to be merged if you handled my comments.

…scripts - Updated `README.md` to reflect changes in OpenMeter environment variables, including the addition of `OPENMETER_URL`. - Modified `openmeter-collector/.env.example` to include `OPENMETER_URL` and clarify its usage. - Enhanced `bootstrap.ps1` and `bootstrap.sh` scripts to derive `OPENMETER_URL` from `OPENMETER_INGEST_URL` if not set, improving flexibility. - Added error handling and response validation in API helper functions within the bootstrap scripts for better reliability.

…R review" This reverts commit 97552cc.

Copilot

Pull request overview

Adds an OpenMeter/Konnect provisioning workflow to bootstrap the metering catalog and customers using kongctl api, and updates top-level docs/env examples to point users at the new provisioning path instead of the old Go bootstrap CLI.

Changes:

Add openmeter-collector/provision/ with idempotent bootstrap scripts (bash + PowerShell) plus a data-driven catalog.json.
Document the provisioning workflow and Konnect setup in a new provision README (including identity/subject-key contract).
Update root README.md and openmeter-collector/.env.example to reference OPENMETER_URL and the new bootstrap commands/docs.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Updates bootstrap instructions to point at the new `kongctl` provision scripts and references the new catalog data file.
openmeter-collector/provision/README.md	New docs for running the catalog/customer bootstrap (bash + PowerShell), configuration, and identity contract.
openmeter-collector/provision/catalog.json	Declares meters/features/plan configuration consumed by the bootstrap scripts.
openmeter-collector/provision/bootstrap.sh	New bash bootstrap script implementing catalog/customer provisioning via `kongctl api` + `jq`.
openmeter-collector/provision/bootstrap.ps1	New PowerShell bootstrap script implementing the same provisioning flow on Windows.
openmeter-collector/.env.example	Adds `OPENMETER_URL` and clarifies env expectations for collector vs bootstrap scripts.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

eliteprox · 2026-06-30T20:50:09Z

@eliteprox looks good to me. I good it working with the instructions. I did however run into one issue though. The .env.example does not contain the OPENMETER_URL placeholder which will cause it to always fallback to https://us.api.konghq.com/v3/openmeter which will print the following:
== catalog (https://us.api.konghq.com/v3/openmeter) ==
meter   network_fee_usd_micros — exists
meter   billable_usd_micros — exists
meter   signed_ticket_count — exists
feature network_spend — exists
feature billable_spend — exists
plan    clearinghouse_default_ppu — active
done.
But not create anything on my org as I'm in the eu region. Could be your script is not handling errors correctly.

Good to be merged if you handled my comments.

Fixed in c5609da

Root cause: .env.example only had OPENMETER_INGEST_URL (not OPENMETER_URL), so bootstrap defaulted to the US API. On an EU org that could look like success (exists / active) without actually provisioning your workspace. This is fixed in PR 36 with a7f9f31

Added OPENMETER_URL to .env.example with US/EU examples
Bootstrap scripts derive OPENMETER_URL from OPENMETER_INGEST_URL if unset
API helpers now check kongctl exit codes and surface errors instead of failing silently

For EU orgs, set both to the eu host:

OPENMETER_URL=https://eu.api.konghq.com/v3/openmeter
OPENMETER_INGEST_URL=https://eu.api.konghq.com/v3/openmeter/events

…cs with collector - Add soft kapi helpers (bash + PowerShell) for publish, subscription, and feature-recreate delete so optional paths warn instead of aborting the run - Fix header comment: scripts warn on missing subject_keys, never mutate them - Derive OPENMETER_URL from ingest URL using trailing-only /events strip (ps1) - Remove usage_subject from catalog dimensions; use external_user_id to match collector.yaml; clarify billable_usd_micros is phase-2 (not yet emitted) - Fix provision README identity contract and remove broken screenshot links

…rap scripts - Modified the subscription creation logic in both PowerShell and Bash scripts to use a new structured format for the request body, enhancing clarity and consistency. - The new format encapsulates customer and plan details in a more organized manner, improving maintainability of the code.

- Changed the paths for the environment file in both PowerShell and Bash bootstrap scripts to point to the repo-root `.env` instead of the previous relative paths. - Updated the README to reflect the new location of the `.env` file, clarifying the setup instructions for users.

feat(provision): add kongctl bootstrap scripts for OpenMeter catalog

a14bec8

Replace the Go clearinghouse-bootstrap CLI with thin cross-platform kongctl scripts and a JSON catalog for idempotent Konnect metering setup.

eliteprox mentioned this pull request Jun 30, 2026

feat(OpenMeter): add kongctl bootstrap scripts #51

Closed

22 tasks

eliteprox requested a review from rickstaa June 30, 2026 17:12

docs(provision): add Konnect bootstrap test screenshots for PR review

97552cc

rickstaa reviewed Jun 30, 2026

View reviewed changes

Comment thread openmeter-collector/provision/README.md

rickstaa reviewed Jun 30, 2026

View reviewed changes

Comment thread openmeter-collector/provision/bootstrap.sh Outdated

rickstaa requested changes Jun 30, 2026

View reviewed changes

Comment thread openmeter-collector/provision/bootstrap.ps1 Outdated

rickstaa self-requested a review June 30, 2026 20:11

rickstaa approved these changes Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 20:41

Revert "docs(provision): add Konnect bootstrap test screenshots for P…

e08ac37

…R review" This reverts commit 97552cc.

Copilot started reviewing on behalf of eliteprox June 30, 2026 20:42 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 30, 2026 20:45

Copilot started reviewing on behalf of eliteprox June 30, 2026 20:46 View session

Copilot AI reviewed Jun 30, 2026

View reviewed changes

eliteprox added 2 commits June 30, 2026 16:54

Copilot AI review requested due to automatic review settings June 30, 2026 21:11

Copilot started reviewing on behalf of eliteprox June 30, 2026 21:12 View session

eliteprox added 2 commits June 30, 2026 17:26

Merge branch 'main' into feat/openmeter-provision-bootstrap

de45b3a

eliteprox merged commit 615441f into main Jun 30, 2026

eliteprox deleted the feat/openmeter-provision-bootstrap branch June 30, 2026 21:39

eliteprox removed the request for review from Copilot June 30, 2026 21:49

eliteprox linked an issue Jun 30, 2026 that may be closed by this pull request

deploy/: Port OpenMeter/Konnect meter bootstrap scripts #25

Closed

This was referenced Jul 17, 2026

Evaluate OpenMeter Entitlements as an alternative to Subscription Discounts for trial credits #67

Open

Trial credits granted on first authentication #11

Closed

Uh oh!

Conversation

eliteprox commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Manual test walkthrough (verified)

1. Create a new Konnect org

2. Name the org

3. Create a Personal Access Token for bootstrap

4. Set the env file

5. Run catalog bootstrap (first run)

6. Re-run — idempotency confirmed

Test plan

Prerequisites

Catalog bootstrap

Customer provisioning

README

Uh oh!

Uh oh!

Uh oh!

rickstaa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eliteprox commented Jun 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

eliteprox commented Jun 30, 2026 •

edited

Loading

rickstaa left a comment •

edited

Loading