Grafana Cloud vending machine with Crossplane
This repository is a portable reference architecture for vending Grafana Cloud stacks through a
small, declarative Kubernetes API. Argo CD owns the objects in Git, Crossplane renders and
reconciles Grafana Cloud resources, and External Secrets Operator (ESO) moves credentials between
Kubernetes and an external secret store. It supports Grafana Cloud only; self-managed Grafana is
out of scope.
One vending-machine installation can serve several registered Grafana Cloud organizations. Each
stack selects one immutable organization, region, usage, and platform profile. The baseline gives a
stack rotating administrator and telemetry credentials, deletion protection, starter content, SSO,
reports, plugins, incident relay resources, teams, roles, and content access. The top-level
enabled/ directory starts empty, so copying or installing this repository cannot create a stack
until a user copies an inert catalog example, edits it, reviews the render, and commits the request.
platform.example.org is a documentation placeholder. Replace it with a domain your organization
controls in the XRDs, Compositions, examples, Argo CD health configuration, and requests before
adopting this API.
Quickstart
The next release is a breaking one. GrafanaProvisioningRepository requests written against 1.x must be restructured; see Migrating to 2.0. No other request kind changes.
Read Getting started for prerequisites and the copy-edit-review-commit
path to a first request. Use Installation first when the controllers,
provider, secret store, and organization ProviderConfig objects are not already healthy.
Retain protects external objects, not MR-owned in-cluster connection Secrets. Kubernetes garbage
collection removes those Secrets when their managed-resource owners are removed. Before authorizing
any MR removal, operators must prove required Secret retention and consumer handoff; see
the pinned-runtime explanation and removal-approval checklist.
Documentation map
| Page | Covers |
|---|
| Documentation home | Who this is for, the request-to-stack flow, baseline capabilities, and the full reading map |
| Core concepts | The Crossplane, GitOps, reconciliation, and ownership terms used by this reference |
| Getting started | Prerequisites and the first request |
| Installation | Direct and Argo CD installation, pins, signatures, releases, and upgrades |
| Configuration | Platform policy, profiles, and the organization registry |
| Architecture | Composition model, renderer registry, resource graph, reconciliation, and provider ownership |
| Request schema | Per-API fields, CompositeResourceDefinitions, short names, admission guards, and status |
| Catalog | Every inert catalog example and its adaptation boundary |
| Secrets | Organization credentials, rotating tokens, ESO, and AWS permissions |
|
Catalog directories are documented in examples/README.md. The project is
available under the Apache License 2.0.
