CloudBurrow
Get started
Get started
How it works

How CloudBurrow works.

Google's own emulators, Knative and CloudBurrow's own services in one local kind cluster, wired to the official SDKs, with credentials that authorise nothing.

A real Kubernetes cluster underneath

cloudburrow up creates a kind cluster in Docker. It starts Google's own emulators where they exist and CloudBurrow's own services where they don't, then wires them together. Because it is real Kubernetes, kubectl, Helm charts and operators work against it directly.

How CloudBurrow fits together On your machine: the official SDKs; the cloudburrow CLI, which runs cluster lifecycle, Cloud Tasks, Secret Manager, Cloud Run v2 adapter, metadata server + ADC, web console; and kubectl and helm. Across the ground line, in the kind cluster: Cloud Storage (CloudBurrow's server, next release; v0.1.0: fake-gcs-server); Pub/Sub (Google's emulator); Cloud Run (Knative Serving); Firestore, Datastore, Bigtable, Spanner (Google's emulators, opt-in); BigQuery (community emulator, opt-in); Cloud SQL (PostgreSQL and MySQL, opt-in); Memorystore (Valkey, opt-in); local AI runtime (opt-in); Kubernetes API (direct). The SDKs call the services in the cluster; kubectl and helm talk to the Kubernetes API directly. Each part is tagged ours when CloudBurrow builds it and upstream when it is integrated. your machine kind cluster official SDKs Google's client libraries, unmodified upstream cloudburrow CLI ours cluster lifecycle Cloud Tasks Secret Manager Cloud Run v2 adapter metadata server + ADC web console kubectl / helm upstream Cloud Storage CloudBurrow's server, next release; v0.1.0: fake-gcs-server ours Pub/Sub Google's emulator upstream Cloud Run Knative Serving upstream Firestore, Datastore, Bigtable, Spanner Google's emulators, opt-in upstream BigQuery community emulator, opt-in upstream Cloud SQL PostgreSQL and MySQL, opt-in upstream Memorystore Valkey, opt-in upstream local AI runtime opt-in upstream ours Kubernetes API direct upstream

Redrawn from How it fits together, in the README at 82a2eb9.

Reuse over rewrite

Google's own emulators are integrated, not reimplemented. CloudBurrow builds only where no upstream exists, and records the evidence for each choice, with the measurements behind it, in docs/upstream-evaluation.md.

Cloud Run on Knative

The Cloud Run v2 API is served by CloudBurrow's adapter, which maps each service onto Knative Serving in the cluster. What the adapter cannot map is refused with the field named, never silently dropped.

Cloud Run v2 fields and where they land on Knative Mapped onto Knative: image to container image; env to env; env from Secret Manager to secretKeyRef to a Kubernetes Secret; min-instances to min-scale (Verified); max-instances to max-scale annotation (mapped, not load-tested); concurrency to containerConcurrency (mapped, not load-tested); timeout to timeoutSeconds (mapped, not load-tested); limits to resources.limits (mapped, not load-tested). Refused, with the field named: traffic splitting, service account, VPC, volumes, CMEK, Binary Authorization, session affinity. Cloud Run v2 Knative image container image env env env from Secret Manager secretKeyRef to a Kubernetes Secret min-instances min-scale Verified max-instances max-scale annotation mapped, not load-tested concurrency containerConcurrency mapped, not load-tested timeout timeoutSeconds mapped, not load-tested limits resources.limits mapped, not load-tested Refused, with the field named traffic splitting refused, field named service account refused, field named VPC refused, field named volumes refused, field named CMEK refused, field named Binary Authorization refused, field named session affinity refused, field named

Cloud Run: what is mapped, and what is refused

Credentials

Where the credentials come from The app reads the ADC file, which leads it to the local metadata server. The metadata server issues a token, and the app sends it to the emulator. Stamped across it: tokens authorise nothing. token App official client library ADC file generated by cloudburrow env local metadata server GCE_METADATA_HOST emulator accepts every caller tokens authorise nothing

cloudburrow env points tooling at a local ADC fixture and a GCE metadata server. A test fails if a real ya29. token ever appears. IAM Credentials generateAccessToken and generateIdToken come from a local signer; signBlob is Unimplemented. The tokens authorise nothing.

Credentials and the local metadata server, in docs/credentials.md

Safety defaults

  • Binds loopback by default; --allow-remote is required to bind anything else
  • Never touches your current kubecontext
  • A DNS-rebinding Host check (#676) next release
  • The admin API needs a per-instance token (#553) next release
  • No authentication on the emulated APIs

Exposure, in docs/configuration.md

Built for testing

Build against Google Cloud APIs, locally

Free and open source under Apache-2.0. No account, no sign-up, no Google Cloud bill.

Get started View on GitHub
Get started