You want to migrate your app to App Engine, but there's a problem: the server-side code is tied to a specific operating system and can't easily be ported. Perhaps you're using an aging COM object written in C++ or Visual Basic; or, worse, your source code no longer exists, and only the executable binary remains.
This tutorial describes an architectural pattern for invoking legacy code using App Engine, Compute Engine, and Pub/Sub, and provides an example implementation of the pattern. Though the example implementation focuses on Windows-specific code, you can reuse the pattern outlined here for any legacy code.
- Learn about a simple architectural pattern for invoking legacy code on Google Cloud.
- Download and deploy an example implementation of the architectural pattern.
An architectural pattern for invoking legacy code
The following diagram illustrates an architectural pattern you can use to invoke legacy code from your App Engine app.
This architecture works as follows:
The web client sends a request to the App Engine app, which writes the request to a Pub/Sub topic.
A code wrapper pulls the request from the topic.
The code wrapper invokes the legacy code.
The legacy code returns the result to the wrapper. The wrapper then returns the result to the App Engine app, which returns it to the web client.
An example implementation of the pattern
You can find an implementation of the above pattern at GitHub. This example app takes a string as input, processes the string using the components outlined in the pattern, and returns an all-uppercase version. The app code comprises two main components:
- The App Engine app, which publishes incoming requests to a Pub/Sub topic.
- The code wrapper, which subscribes to the Pub/Sub topic and, when it receives a request, sends the request to some legacy Windows-based code.
In this implementation, the wrapper is a Windows service, written in C#. This wrapper service is configured to run when the instance starts up, and can invoke any script or binary that can be invoked from C#. Both the wrapper service and the invoked binary reside on a Compute Engine instance running Windows Server 2012 R2.
The app's user interface looks similar to this:
If you type the word "mars" and click Submit, the result is as follows:
This tutorial uses the following billable components of Google Cloud:
- A Compute Engine instance with a Windows Server 2012 license
- Pub/Sub services
This example app assumes the following:
- You have a Windows development machine with Virtual Studio 2012 (or later) installed.
- You have an RDP client installed on your development machine.
- You've created a Google Cloud Console project.
- You've installed the App Engine Python SDK.
installed Python 2.7
and added the folder containing the
pythonbinary to your
pip1.4 or later, and added the folder containing the
pipbinary to your
Get the source code
Download the example code here and unzip it. If you prefer, you can clone the GitHub project repository instead by running the following command:
C:\> git clone https://github.com/GoogleCloudPlatform/pubsub-shout-csharp.git
Install the dependencies
In your command-line terminal, navigate to the
folder in your local copy of the
pubsub-shout-csharp repository, and
then run the following:
C:\> pip install -r requirements.txt -t lib
Create a Compute Engine instance
Create the Compute Engine instance that the code wrapper and legacy code will run on:
In the Cloud Console, go to the Create a new instance page.
In the Boot disk section, click Change.
On the Public images tab, select the Windows Server operating system and the 2012 R2 Datacenter Edition version.
Click Save to confirm the boot disk options.
In the Firewalls section, allow HTTP and HTTPS traffic.
In the Project access section, allow full API access to all Google Cloud services in your project.
To reveal advanced options, click Management, security, disks, networking, sole tenancy, and then click the Networking tab.
In the Network tags section, add the tag
rdp-tag. Later in the tutorial, you'll create a firewall rule that allows external RDP access to all instances tagged with this tag.
To begin creating your new instance, click Create .
After you create the instance, add a default Windows user to the instance:
In the Cloud Console, go to the VM instances page.
Click the name of your newly deployed instance.
On the instance page, click the Set Windows password button.
To create the user account on your instance, in the Set new Windows password dialog, add your username and click Set.
Make a note of the provided password and close the dialog.
Next, create a firewall rule to enable RDP access to your instance:
In the Cloud Console, go to the Create a firewall rule page.
Fill out the form as follows:
- Source IP ranges:
- Allowed protocols and ports:
- Target tags:
To create your firewall rule, click Create .
Build and deploy the code wrapper
To build the code wrapper service:
In the Cloud Console, go to the Credentials page.
Click New credentials and select Service account key.
On the Create service account key page, fill out the form as follows:
- Service account: New service account
- Name: A name of your choosing.
- Service account ID: An ID of your choosing.
- Key type: JSON
Click Create. After a few seconds, a JSON key file downloads to your local computer.
On your local machine, create a new environment variable called
GOOGLE_APPLICATION_CREDENTIALSand set it to the absolute path of the JSON key file.
Go to the
windows-csharpfolder in your local copy of the
ShoutService.slnin Visual Studio 2012 or later.
ShoutLib/Constants.cs, set the variable
ProjectIdto your https://console.cloud.google.com/ project ID, and save.
In the Build menu, click Build Solution to build the app.
After building the code wrapper service, copy it to your Compute Engine instance:
Establish a remote desktop connection to the instance you created earlier in the tutorial.
On your local machine, in Windows Explorer, go to the
ShoutService\binfolder under your
Releasefolder from Windows Explorer, and then paste it inside your remote connection window to copy the folder to your instance. The
Releasefolder contains the wrapper and the Shout service.
Next, allow the Windows Service Control Manager to start, stop, and otherwise interact with your service by granting appropriate permissions to LOCAL SERVICE, a predefined Windows user account used by the Service Control Manager:
In Windows Explorer, go to the
Right-click the folder to open the context menu, and then click Properties.
In the Release Properties dialog, click the Security tab.
In the Permissions for Release dialog, click Add.
In the Select Users or Groups dialog, under Enger the object names to select, type
LOCAL SERVICEand then click OK.
In the Permissions for Release dialog, click LOCAL SERVICE.
Under Permissions for LOCAL SERVICE, make sure that the following permissions are enabled:
- Read & execute
- List folder contents
Finally, install the code wrapper service:
On your remote machine, open the command-line terminal as Administrator and navigate to the
Install the code wrapper service:
C:\> C:\Windows\Microsoft.NET\Framework64\v4.0.30319\InstallUtil.exe ShoutService.exe
Deploy the App Engine app
To deploy the App Engine app:
On your local machine, in your command-line terminal, navigate to the
appengine-python-flaskfolder in your local copy of the
Deploy the app.
C:\> appcfg.py -A <your_project_id> -V 1 --oauth2 update .
Authenticate the app when prompted.
- Enable the Pub/Sub API.
To initialize the app, visit the following URL in your web browser:
When you visit this URL, the App Engine app creates a Pub/Sub topic and then subscribes the code wrapper service to the topic.
Congratulations! Your app is now live. Visit
<your_project_id>.appspot.com to see it in action.
After you've finished the Invoking Legacy Code tutorial, you can clean up the resources that you created on Google Cloud so they won't take up quota and you won't be billed for them in the future. The following sections describe how to delete or turn off these resources.
Delete your Google Cloud project
The easiest way to eliminate billing is to delete the project that you created for the tutorial.
To delete the project:
- In the Cloud Console, go to the Manage resources page.
- In the project list, select the project that you want to delete and then click Delete delete.
- In the dialog, type the project ID and then click Shut down to delete the project.
Delete your Compute Engine instance
To delete a Compute Engine instance:
- In the Cloud Console, go to the VM Instances page.
- Click the checkbox for the instance you want to delete.
- Click Delete delete to delete the instance.
- Try out other Google Cloud features for yourself. Have a look at our tutorials.