Using Google Pub/Sub Messaging with AppScale

Posted by AppScale Staff on 7/19/18 11:23 AM

In a previous post, we explained how you can host your own version of Google Pub/Sub using an open source emulator. The emulator—provided by Google—implements the Pub/Sub API using Apache Kafka as a data streaming backend. The result is a distributed messaging system that is fully compatible with Pub/Sub apps without locking you into the Google Cloud Platform (GCP).

In this post, we'll demonstrate how to configure AppScale apps to send and receive messages using the emulator.

Why use Pub/Sub with AppScale?

As we mentioned in the previous post, the benefit of publish-subscribe systems like Pub/Sub is that they facilitate asynchronous messaging among various services. One service can send a message to multiple recipients without having to know who the recipients are, where they are, or how many there are. For distributed platforms like AppScale, this lets apps communicate without limiting your ability to deploy, remove, replicate, or scale them.

AppScale's key strength is that it can run on a number of different platforms. Although you don't have to run your apps in GCP to use Pub/Sub, the service is tied to the platform. With Google's open source emulator, you no longer have to be committed to GCP, AWS, or any other cloud platform to use publish/subscribe-style messaging.

Deploying Pub/Sub-Compatible Apps

To demonstrate Pub/Sub on AppScale, we'll deploy two apps: one that publishes messages to a topic, and one that receives them. Before you begin, make sure you follow the "Setting up the Project" section of our previous post to create a working installation of the Pub/Sub emulator. You should also have a working AppScale installation. The emulator must be accessible over the network by your AppScale nodes, since our apps will need to contact it in order to send and receive messages.

Note on Running Kafka

When running Kafka as part of the emulator setup process, you don't need to start a new ZooKeeper server if you're installing the emulator on an AppScale ZooKeeper node. Instead, you can simply start the Kafka server and use the existing ZooKeeper instance.

After completing the setup process, you should have the emulator running on port 8000. It should also be configured with a project called my-project, a topic called my-topic, and a subscription called subscription-to-my-topic.

In the previous post, the example apps opened persistent connections to the emulator using the gRPC protocol. This protocol isn't currently supported in AppScale, so instead we'll use REST API calls to interact with the messaging service via a gateway service. Since App Engine and AppScale requests are often short-lived, we can use a separate worker script to push messages to subscribers using this gateway.

Deploying the REST API Gateway

The REST API gateway allows App Engine apps to send and receive messages using HTTP calls. This enables apps to interact with the messaging backend without having to open a persistent connection.

To install and run the gateway service, you can follow the installation instructions provided on the gateway's GitHub page. (Note that if you choose to compile a standalone build, you should use Ubuntu 18.04 / Bionic Beaver since its repositories contain supported versions of the required packages.) You can also deploy the gateway using Docker or Kubernetes. In the following instructions we rely on a compiled binary that should run on any x86 Linux system.

When running the gateway, specify the locations of both the Kafka emulator and the target port that the gateway will run on. For example, this command connects to the emulator on port 8000 and exposes the gateway on port 8001:

$ curl -O
$ chmod uog+rx kafka-pubsub-emulator-gateway
$ ./kafka-pubsub-emulator-gateway start --address 8000 --port 8001

Deploying the Receiver App

The first AppScale app we'll create is a Python script that receives Pub/Sub messages. The script simply logs incoming messages to the console. It confirms the authenticity of the message using a token shared with the sender app.

Open a terminal on your AppScale workstation and create a new directory to hold the app's files:

$ mkdir pubsub-receiver
$ cd pubsub-receiver/

Creating the Receiver Script

Create a new file called with the following contents.

import os
import webapp2
import json
import base64

import logging

class PushHandler(webapp2.RequestHandler):
	def post(self):
    	token = os.environ['PUBSUB_VERIFICATION_TOKEN']
    	if self.request.get('token') != token:
        	self.response.write('Invalid token')

    	envelope = json.loads(self.request.body)
    	payload = base64.b64decode(envelope['message']['data'])"Received message: {}".format(payload))

app = webapp2.WSGIApplication([
	('/pubsub/push', PushHandler)

Configuring app.yaml

Next, we need to create an app.yaml file to store the project's configuration. This file also contains a token used to verify the authenticity of incoming messages. This token can be any alphanumeric value of your choice, and will be passed into the app on deployment.

application: pubsub-receiver
runtime: python27
api_version: 1
threadsafe: true

- url: .*


Now, deploy the receiver application to AppScale:

$ sudo -i
# appscale deploy 

You can verify that the app was successfully deployed by running appscale status or by checking the AppScale dashboard.

Deploying a Sender Application

Next, we'll create an app to send messages to the receiver app. This is another Python script that accepts an HTTP POST request and forwards the body of the message to the messaging service.

From the terminal, navigate to the parent directory of your receiver app and create a new folder for the sender project:

$ cd ..
$ mkdir pubsub-sender
$ cd pubsub-sender/

Create a new file called with the following contents:

import os
import webapp2
from import pubsub

class IndexHandler(webapp2.RequestHandler):
	def post(self):
    	client = pubsub.Client()
    	topic = client.topic(os.environ['PUBSUB_TOPIC'])


app = webapp2.WSGIApplication([
  ('/', IndexHandler)

Managing Third-Party Libraries

This script relies on the Google Cloud Pub/Sub Client Libraries. Since these aren't already available in AppScale, we need to copy the libraries to our app directory.

From the app's root directory, create a new folder called lib.

$ mkdir lib

Use pip to download and install the library into the folder:

$ pip install -t lib/ google-cloud-pubsub==0.22.0

Now, create a file named in the project's root folder with the following contents:

from google.appengine.ext import vendor

Configuring app.yaml

The sender's app.yaml file requires several variables including the Pub/Sub emulator URL, the project ID, and the topic ID. It also requires a verification token, which should be identical to the one used in the receiver app.

application: my-project
runtime: python27
api_version: 1
threadsafe: true

- url: .*

  PUBSUB_EMULATOR_HOST: 'localhost:8000'
  PUBSUB_PROJECT: 'my-project'
  PUBSUB_TOPIC: 'my-topic'

- name: webapp2
  version: "2.5.2"

Now, deploy the sender app to AppScale:

$ sudo -i
# appscale deploy 

Deploying th Push Notification Worker

 In order for the receiver app to automatically receive new messages, we need to translate Pub/Sub messages into REST calls. We can do this by using a worker script to maintain a persistent gRPC connection to the emulator, listen for new messages on a subscription, then forward the contents of each message to an AppScale endpoint. This provides the same functionality as the Cloud Pub/Sub push subscription model, but in a way that's compatible with the Pub/Sub emulator.

Start by opening a terminal and creating a new folder to contain the app's project files.

$ mkdir push-worker
$ cd push-worker/

Create a new file called with the following contents:

import argparse
import base64
import logging
import time

import backoff
import grpc
import requests
import yaml
import urllib3

from import pubsub
from requests.exceptions import HTTPError, RequestException

LOG_FORMAT = '%(asctime)s %(levelname)s %(message)s '

SUCCESS_CODES = (102, 200, 201, 202, 204)

@backoff.on_exception(backoff.expo, RequestException)
def make_request(endpoint, data):
	response =, json=data)
	if response.status_code not in SUCCESS_CODES:
    	raise HTTPError('Received response code: {}'.format(response.status_code))

def callback_factory(endpoint):
	def callback(message):
    	size = len('Pushing message to {}. Size: {}'.format(endpoint, size))
    	payload = {
        	"message": {
            	"data": base64.b64encode('utf8'),
    	make_request(endpoint, payload)

	return callback

if __name__ == '__main__':
	parser = argparse.ArgumentParser(
    	description='pushes messages from Kafka topics to HTTP endpoints')
	parser.add_argument('config', help='the push worker configuration file')
	args = parser.parse_args()


	with open(args.config) as config_file:
    	config = yaml.safe_load(config_file)

	channel = grpc.insecure_channel(config['pubsub_endpoint'])
	subscriber = pubsub.SubscriberClient(channel=channel)

	for subscription in config['subscriptions']:
    	subscription_path = '/'.join([
        	'projects', subscription['project_id'],
        	'subscriptions', subscription['subscription_id']])'Subscribing to {}'.format(subscription_path))
    	subscription_function = callback_factory(subscription['endpoint'])
    	subscriber.subscribe(subscription_path, subscription_function)

	while True:

This script requires a number of libraries. The easiest way to install these is to create a Virtual Environment:

$ source env/bin/activate
$ pip install backoff grpcio requests pyyaml urllib3 google-cloud-pubsub

We'll store the parameters for this script in a separate configuration file. Create a new file named config.yaml in the same directory with the following contents:

pubsub_endpoint: localhost:8000
 - project_id: my-project
   subscription_id: subscription-to-my-topic
   endpoint: http:///pubsub/push?token=

The pubsub_endpoint is the URL of your Pub/Sub emulator. If you chose a different name for your project ID or subscription ID, be sure to replace those values here as well. The endpoint is the URL of your receiver app after it's deployed to AppScale. At the end of the endpoint, replace <secret token> with the same token you used for the receiver and sender apps.

Finally, run the script by passing in the configuration file as a parameter.

$ python config.yml

Testing the Deployment

Now that all of the required components have been deployed, you can test your implementation by sending an HTTP POST request to the sender app's endpoint. Encode the contents of your message as JSON in the body of the request.

For example, we'll send a basic "hello world" using curl:

$ curl --data 'Hello world!' http://

You can verify that the message was sent by checking AppScale's logs for the sender app:

# tail /var/log/appscale/app___pubsub-sender_default_v1.log

Jul  12 15:25:45 appscale-image0 Publish took 0.0360200405121 seconds.

Likewise, you can verify that the receiver has received the message by opening the receiver app's logs:

# tail /var/log/appscale/app___pubsub-receiver_default_v1.log

Jul 12 15:25:50 appscale-image0 INFO 	2018-07-13 15:25:50,676] Received message: Hello world!


Pub/Sub is an extremely versatile platform with many practical applications, and Google's emulator makes it possible to run an API-compatible Pub/Sub service on any platform. Instead of relying on the Google Cloud Platform, you can now use Pub/Sub anywhere that you run AppScale.

Google is committed to open source solutions and an open cloud. The Pub/Sub emulator is open source, and so are several projects used by the Pub/Sub team.

We're grateful for Google's commitment and contributions to the open source community and would like to specifically thank our friends at Google Cloud for their help:

  • Kir Titievsky
  • Preston Holmes
  • Vic Iglesias
  • Steve Mansfield
  • Miles Ward

Subscribe to Email Updates

Most Popular

Recent Posts