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 local credentials that grant no Google Cloud access.

Get started
Architecture

Follow a request through the local stack.

Start at the cluster, then trace the service mapping, local credentials and testing controls.

  • Use familiar Kubernetes tools against the kind cluster.
  • Follow each service to its emulator or implementation.
  • See where local credentials and testing controls apply.
CloudBurrow Architecture
At a glance

The local stack

Cluster
kind in Docker
Cloud Run adapter
Knative Serving
Cluster tools
kubectl and Helm
Inside architecture

Go straight to the detail you need.

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 own server. v0.1.0 used 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 own server. v0.1.0 used 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 0ea2594.

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. The adapter refuses unsupported fields by name. It stores some settings, such as VPC access and encryption keys, without applying them.

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

The adapter also serves tested jobs, worker pools and standalone instances, which use Kubernetes batch Jobs or Deployments. Service-level scaling maps onto Knative's scale bounds, and worker-pool automatic scaling is driven on the pods' CPU utilization. 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, and no token grants any Google Cloud access.

IAM Credentials also serves signJwt and signBlob with each service account's own key, and checks the caller's grants before it impersonates an account. Cloud Storage verifies signed URLs against the instance's ADC key and those service accounts' certificates, so a URL signed through signBlob works locally (#1787). A token or signature made here verifies only against this instance's certificates.

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

Exposure and access

Safety defaults

Exposure, in docs/configuration.md

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

Built for testing

Develop locally

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