Prepare and test your skills
Prepare and test your skills
Emulator installation and lifecycle management is the process of adding, starting, connecting to, and stopping local copies of Google Cloud services for development and testing. The Google Cloud SDK (opens in a new tab) distributes these copies as emulator components, and gcloud beta emulators and gcloud emulators commands create local instances that simulate production behavior. Because work happens locally, teams save costs, avoid changing production services, and iterate faster while debugging before deployment.
Available local emulators are high-fidelity simulations of production services that run on a developer machine instead of Google Cloud. Applications connect to a local host and port rather than a Google Cloud endpoint, and resources created during a session exist only for that session. Stopping the emulator ends the isolated test environment.
Installing emulator components adds the emulator binaries to the Google Cloud CLI (gcloud CLI) through gcloud components commands. The update step ensures the command-line interface (CLI) has the latest features before the first start, and a missing Bigtable binary triggers a prompt to download and install it on first use. Installation must complete before a start command can bind a local host and port.
Pub/Sub uses gcloud components install pubsub-emulator followed by gcloud components update. Cloud Spanner uses gcloud components install cloud-spanner-emulator followed by gcloud components update. Bigtable uses gcloud components update beta before gcloud beta emulators bigtable start. Docker provides an alternative path by running the emulator from a container image instead of a local component install.
Starting an emulator creates a local server process that listens on a host and port on the developer machine. The start command prints the selected host and port, and the optional --host-port flag binds the emulator to a specific address when the default is unsuitable. When multiple emulators run at the same time, each start command must specify its host and port explicitly so the local endpoints do not conflict.
| Emulator | Start command | Default local endpoint |
|---|---|---|
| Bigtable emulator | gcloud beta emulators bigtable start | localhost:8086 |
| Cloud Spanner emulator | gcloud emulators spanner start | localhost:9010 for gRPC requests and localhost:9020 for REST requests |
| Pub/Sub emulator | gcloud beta emulators pubsub start --project=PUBSUB_PROJECT_ID | Port 8085 on IPv6 localhost ::1 |
The Pub/Sub project ID string does not need to represent a real Google Cloud project because execution stays local. Pub/Sub can listen on all addresses with --host-port=0.0.0.0:8085 or on IPv4 with --host-port=127.0.0.1:8085 when IPv6 is disabled. Docker maps container ports to the same local ports, such as running Bigtable with --host-port=0.0.0.0:8086 or running the Spanner image with -p 9010:9010 -p 9020:9020.
Exam tip: Set emulator environment variables again each time the emulator restarts, because the variables can depend on dynamically assigned ports that change between sessions.
Connecting applications to running emulators directs client libraries and command-line tools from production endpoints to the local endpoint. Client libraries check for an emulator host variable when the application starts, and traffic flows from the application to the emulator instead of Google Cloud when that variable is set. This boundary keeps test reads, writes, publishes, and subscriptions isolated from production data.
The Bigtable client libraries use BIGTABLE_EMULATOR_HOST=localhost:8086, and any project and instance name can then create tables and read or write data. The Cloud Spanner client libraries use SPANNER_EMULATOR_HOST=localhost:9010, which can also be set with $(gcloud emulators spanner env-init). The Pub/Sub client libraries use PUBSUB_EMULATOR_HOST, set automatically with $(gcloud beta emulators pubsub env-init) on the same machine or manually on a different machine with the value printed by env-init. The Bigtable emulator does not provide administrative APIs for instances and clusters, does not support a secure connection, and cannot be used in the HBase shell.
Cloud Spanner has an additional gcloud CLI connection path that overrides the API endpoint rather than using only an environment variable. A separate configuration disables credentials, sets the project, and sets api_endpoint_overrides/spanner to http://localhost:9020/, so later gcloud spanner commands flow to the emulator. Verification creates a test instance with the emulator instance config emulator-config, and gcloud config configurations activate emulator selects the emulator while gcloud config configurations activate default returns to production.
Stopping emulators ends the local server process and its session-scoped test state. The foreground process stops with Control-C, which ends Bigtable in-memory storage and Pub/Sub topics, subscriptions, and messages held for that session. The stop order matters: first stop the emulator process, then remove the local connection settings so later commands do not continue targeting a closed port.
After stopping Bigtable, unset BIGTABLE_EMULATOR_HOST so the client library returns to production behavior. After stopping Pub/Sub, unset PUBSUB_EMULATOR_HOST for the same reason, using unset on Linux or macOS and an empty set value on Windows. After Spanner local testing, activate the default gcloud CLI configuration to send commands to production instead of the emulator configuration. Leaving an emulator host variable set causes the next application run to attempt a connection to an emulator that is no longer listening.
Local testing workflows use Google Cloud emulators to run unit and integration tests against simulated services instead of production. The application connects to a local endpoint, exercises its logic for reads, writes, and messaging, and then discards or resets the test state. Data consistency in this model depends on understanding persistence, initialization, and session lifetime for each emulator.
Emulated services for local validation are the five backend emulators in the Google Cloud software development kit (SDK) (opens in a new tab) that cover database and messaging test cases. Each emulator simulates the behavior of its production service so tests run faster, cost nothing, and never affect production data. The shared benefit across all five emulators is isolation: development iterations happen locally while production projects, data, and quotas remain untouched.
Starting an emulator test session creates local network endpoints that receive the same API calls the application would send to Google Cloud. The two common launch methods are the Google Cloud CLI and Docker, with Docker mapping container ports to the same ports on the local host. Explicit host and port settings are required when multiple emulators run at the same time.
The Bigtable emulator (opens in a new tab) follows an ordered start and stop workflow with the gcloud CLI:
gcloud components update beta to get the latest emulator features and prompt for binary download if needed.gcloud beta emulators bigtable start, optionally with --host-port=HOST:PORT, and note the printed host and port, which defaults to localhost:8086.Other emulators use parallel commands with their own defaults. The Pub/Sub emulator starts with gcloud beta emulators pubsub start --project=PUBSUB_PROJECT_ID and listens on port 8085 on IPv6 localhost (::1) by default, with --host-port options for 0.0.0.0:8085 or 127.0.0.1:8085. The Spanner emulator starts with gcloud emulators spanner start and uses localhost:9010 for gRPC requests and localhost:9020 for REST requests. Docker equivalents pull or reuse the google/cloud-sdk or Spanner emulator image and map those same ports to the host.
Redirecting an application to an emulator means pointing its Cloud Client Libraries from Google Cloud endpoints to the local emulator endpoint. The client library automatically checks for an emulator host variable when the application starts and connects to the emulator if it is running. These variables must be set on the same machine that runs the application and must be set again each time the emulator restarts.
For Bigtable, the application sets BIGTABLE_EMULATOR_HOST=localhost:8086 and unsets it after testing with unset BIGTABLE_EMULATOR_HOST. For Spanner, the application sets SPANNER_EMULATOR_HOST=localhost:9010 or evaluates $(gcloud emulators spanner env-init) to populate the environment. For Datastore mode, the application sets its emulator variables plus GOOGLE_CLOUD_PROJECT, and initializes the local development server with --application=PROJECT_ID so the project ID matches the expected Google Cloud project. For Spanner use with the gcloud CLI, a separate configuration disables credentials and overrides the endpoint with api_endpoint_overrides/spanner set to http://localhost:9020/, which can be toggled with gcloud config configurations activate emulator and gcloud config configurations activate default.
Data persistence and initialization define what test data exists when a local session begins and what survives when it ends. The Bigtable emulator stores data only in memory, so tables and rows do not persist across runs and every restart begins empty. The Pub/Sub emulator keeps topics, subscriptions, and published messages for the lifetime of the emulator session, so state survives across individual test cases until the emulator stops.
Initialization is intentionally lightweight to support isolated unit tests. After the Bigtable emulator starts, any project and instance name can be used to create tables and read or write data because the emulator does not provide administrative APIs to create or manage instances and clusters. After the Pub/Sub emulator starts, the supplied project ID string does not need to represent a real Google Cloud project because all topic creation, publishing, and subscribing happen locally. Datastore mode supports importing data into the emulator so a test can start with pre-loaded entities, while Spanner tests verify setup by creating an instance with the emulator-only instance config emulator-config.
Exam tip: The Pub/Sub emulator accepts unencrypted http push endpoints for local testing, while production Pub/Sub allows only secure https push endpoints.
Validating application logic means executing the same data and messaging operations locally that the application will perform in production. Against Bigtable, tests create tables and read or write data through any Cloud Bigtable client library, often confirmed with hello world samples. Against Pub/Sub, tests create topics and subscriptions, publish messages, and receive them through Cloud Client Libraries without reaching Google Cloud. Against Spanner, tests run Getting Started operations while skipping project creation, authentication, and credential steps.
Emulated validation has explicit boundaries that affect test design. The Bigtable emulator does not support a secure connection and cannot be used in the HBase shell. The Pub/Sub emulator (opens in a new tab) warns that its implementation may be incomplete or differ from the real system, so final behavior checks still belong before deployment. Once local runs pass without errors, the workflow moves to testing on the hosted service and controlled rollout practices such as traffic splitting and monitoring for database issues.
Environment configuration and client library integration is the method for making a local application talk to an emulator instead of production Google Cloud. The application is built with Cloud Client Libraries, and an environment variable points those libraries to the emulator host address and port. When the variable is set, requests flow from the application through the client library to the local emulator endpoint; when it is not set, the same code flows to the production Google Cloud endpoint.
The local-to-production switch follows an ordered workflow:
Client library redirection means the client library checks for an emulator host variable when the application starts and chooses its destination automatically. If the variable is present and the emulator is running, the library sends creates, reads, writes, publishes, and subscribes to the emulator. If the variable is absent, the library sends the same operations to production, so no application code change is needed to switch targets.
This redirection depends on using a supported client library. The Pub/Sub emulator (opens in a new tab) works only with applications built with Cloud Client Libraries and does not support the Google Cloud console or gcloud pubsub commands. The Bigtable emulator (opens in a new tab) works with all Cloud Bigtable client libraries, stores data only in memory, and does not support a secure connection.
Service emulator host variables are environment variables that carry the local host address and port for each emulator. Each service uses its own variable name, and the application machine must use the matching value from the running emulator. Resources created in the emulator last only for the lifetime of the emulator session.
| Service | Host variable | Typical local endpoint |
|---|---|---|
| Bigtable emulator | BIGTABLE_EMULATOR_HOST | localhost:8086 |
| Spanner emulator | SPANNER_EMULATOR_HOST | localhost:9010 for gRPC requests |
| Pub/Sub emulator | PUBSUB_EMULATOR_HOST | localhost:8085 on IPv6 localhost, but the assigned port can change |
The Bigtable emulator defaults to localhost:8086 unless a different host and port are supplied with --host-port. The Spanner emulator (opens in a new tab) uses localhost:9010 for gRPC requests and localhost:9020 for REST requests. The Pub/Sub emulator listens on port 8085 by default, and Pub/Sub applications can also use PUBSUB_PROJECT_ID to select the project string used locally.
Exam tip: Set the host variable again every time you restart the emulator, because the dynamically assigned port can change between runs.
Setting variables automatically is the option when the application and the emulator run on the same machine. On Linux or macOS the shell evaluates the output of env-init with command substitution, such as $(gcloud beta emulators pubsub env-init) or $(gcloud emulators spanner env-init). On Windows the output of env-init is written to a batch file and then run, such as gcloud beta emulators pubsub env-init > set_vars.cmd && set_vars.cmd.
Setting variables manually is the option when the application and the emulator run on different machines. First run env-init where the emulator runs to see the required host and value, then set that value on the application machine with export PUBSUB_EMULATOR_HOST=[::1]:8432 on Linux or macOS or set PUBSUB_EMULATOR_HOST=[::1]:8432 on Windows. The same pattern applies to other services, such as export BIGTABLE_EMULATOR_HOST=localhost:8086 or export SPANNER_EMULATOR_HOST=localhost:9010. After testing is finished, stop the emulator and unset the variable so later runs do not keep pointing at the closed local endpoint.
localhost:8086, the Cloud Spanner emulator uses localhost:9010 for gRPC and localhost:9020 for REST, and the Pub/Sub emulator listens on port 8085.BIGTABLE_EMULATOR_HOST, SPANNER_EMULATOR_HOST, or PUBSUB_EMULATOR_HOST is set, and send traffic to production Google Cloud when the variable is absent.http push endpoints for local testing, while production Pub/Sub requires secure https push endpoints.The Bigtable emulator defaults to localhost:8086, the Cloud Spanner emulator uses localhost:9010 for gRPC requests and localhost:9020 for REST requests, and the Pub/Sub emulator listens on port 8085 on IPv6 localhost ::1. They are started with gcloud beta emulators bigtable start, gcloud emulators spanner start, and gcloud beta emulators pubsub start with a project ID string that does not need to represent a real project, and the optional host-port flag binds a specific address with explicit values required when multiple emulators run together.
Cloud Client Libraries send traffic to the local emulator when the matching emulator host variable is set and send traffic to production Google Cloud when the variable is absent, so no application code change is needed. Bigtable uses BIGTABLE_EMULATOR_HOST with localhost:8086, Spanner uses SPANNER_EMULATOR_HOST with localhost:9010, and Pub/Sub uses PUBSUB_EMULATOR_HOST, and the variables must be set on the same machine that runs the application and set again each time the emulator restarts.
The Bigtable emulator stores data only in memory so tables and rows do not persist after the emulator stops and every restart begins empty. The Pub/Sub emulator keeps topics, subscriptions, and published messages for the lifetime of the emulator session until the emulator stops, and stopping is done with Control-C followed by unsetting the host variable so later runs do not target a closed port.
Last updated