Google Cloud Pub/Sub Emulator

To develop and test your application locally, you can use the Google Cloud Pub/Sub emulator, which provides local emulation of the production Google Cloud Pub/Sub environment. You run the Google Cloud Pub/Sub emulator using the gcloud command-line tool.

To run your application against the emulator, you need to do some configuration first, such as starting the emulator and setting environment variables.

Prerequisites

You must have the following to use the Google Cloud Pub/Sub emulator:

Installing the emulator

Install the emulator from a command prompt:

gcloud components install pubsub-emulator
gcloud components update

Starting the emulator

Start the emulator by invoking pubsub start from a command prompt:

gcloud beta emulators pubsub start [options]

where [options] are command line arguments supplied to the gcloud command-line tool. See gcloud beta emulators pubsub start for a complete list of options.

After you start the emulator, you should see a message that resembles the following:

...
[pubsub] This is the Google Pub/Sub fake.
[pubsub] Implementation may be incomplete or differ from the real system.
...
[pubsub] INFO: Server started, listening on 8538

Setting environment variables

After you start the emulator, you need to set environment variables so that your application connects to the emulator instead of the production environment. Set these environment variables on the same machine that you use to run your application.

You need to set the environment variables each time you start the emulator. The environment variables depend on dynamically assigned port numbers that could change when you restart the emulator.

Automatically setting the variables

If your application and the emulator run on the same machine, you can set the environment variables automatically:

Linux / macOS

Run env-init using command substitution:

$(gcloud beta emulators pubsub env-init)

Windows

Create and run a batch file using output from env-init:

gcloud beta emulators pubsub env-init > set_vars.cmd && set_vars.cmd

Your application will now connect to the Cloud Pub/Sub emulator.

Manually setting the variables

If your application and the emulator run on different machines, set the environment variables manually:

  1. Run the env-init command:

    gcloud beta emulators pubsub env-init
  2. On the machine that runs your application, set the environment variables and values as directed by the output of the env-init command. For example:

    Linux / macOS
    export PUBSUB_EMULATOR_HOST=localhost:8432
    export PUBSUB_PROJECT_ID=my-project-id
    Windows
    set PUBSUB_EMULATOR_HOST=localhost:8432
    set PUBSUB_PROJECT_ID=my-project-id

Your application will now connect to the Cloud Pub/Sub emulator.

Note: If you are using the Python App Engine Standard local development server, you must pass environment variables on the command line as follows:

Python

   dev_appserver.py app.yaml --env_var PUBSUB_EMULATOR_HOST=${PUBSUB_EMULATOR_HOST}

Accessing environment variables

In all languages except for Java and C#, if you have set PUBSUB_EMULATOR_HOST as described in Setting environment variables, the Google Cloud Pub/Sub client libraries automatically call the API running in the local instance instead of the production API.

However, C# and Java client libraries require you to modify your code to use the emulator:

C#

For more on installing and creating a Cloud Pub/Sub client, refer to Cloud Pub/Sub Client Libraries.

// For example, "localhost:8615"
string emulatorHostAndPort = Environment.GetEnvironmentVariable("PUBSUB_EMULATOR_HOST");
Channel channel = new Channel(emulatorHostAndPort, ChannelCredentials.Insecure);
PublisherClient client = PublisherClient.Create(channel);
client.CreateTopic(new TopicName("project", "topic"));
foreach (var topic in client.ListTopics(new ProjectName("project")))
{
    Console.WriteLine(topic.Name);
}

Java

For more on installing and creating a Cloud Pub/Sub client, refer to Cloud Pub/Sub Client Libraries.

String hostport = System.getenv("PUBSUB_EMULATOR_HOST");
ManagedChannel channel = ManagedChannelBuilder.forTarget(hostport).usePlaintext(true).build();
try {
  ChannelProvider channelProvider = FixedChannelProvider.create(channel);
  CredentialsProvider credentialsProvider = new NoCredentialsProvider();

  // Set the channel and credentials provider when creating a `TopicAdminClient`.
  // Similarly for SubscriptionAdminClient
  TopicAdminClient topicClient =
      TopicAdminClient.create(
          TopicAdminSettings.newBuilder()
              .setTransportProvider(
                  GrpcTransportProvider.newBuilder()
                      .setChannelProvider(channelProvider)
                      .build())
              .setCredentialsProvider(credentialsProvider)
              .build());

  TopicName topicName = TopicName.create("my-project-id", "my-topic-id");
  // Set the channel and credentials provider when creating a `Publisher`.
  // Similarly for Subscriber
  Publisher publisher =
      Publisher.defaultBuilder(topicName)
          .setChannelProvider(channelProvider)
          .setCredentialsProvider(credentialsProvider)
          .build();
} finally {
  channel.shutdown();
}

Stopping the emulator

To stop the emulator, press Ctrl+C.

Emulator command-line arguments

For details on command-line arguments for the Google Cloud Pub/Sub emulator, see gcloud beta emulators pubsub.

Known limitations

  • You cannot start or stop Publisher or Subscriber from your code.
  • IAM operations are not currently supported.

To file issues, visit the Google Cloud Pub/Sub forum.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Pub/Sub Documentation