Programming Google App Engine with Python (2015)
Chapter 20. Deploying and Managing Applications
Uploading your application to App Engine is as easy as clicking a button or running a command. All your application’s code, configuration, and static files are sent to App Engine, and seconds later your new app is running.
Easy deployment is one of App Engine’s most useful features. You don’t have to worry about which servers have which software, how servers connect to services, or whether machines need to be rebooted or processes restarted. Other than your developer account, there are no database passwords to remember, no secret keys to generate, and no need to administer and troubleshoot individual machines. Your application exists as a single logical entity, and running it on large-scale infrastructure is as easy as running it on your local computer.
App Engine includes features for testing a new version of an app before making it public, reverting to a previous version quickly in case of a problem, and migrating the datastore and service configuration for the app from one version to another. These features let you control how quickly changes are applied to your application: you can make a new version public immediately to fix small bugs, or you can test a new version for a while before making it the version everyone sees.
Service configuration is shared across all versions of an app, including datastore indexes, task queues, and scheduled tasks. When you upload the app, the service configuration files on your computer are uploaded as well, and take effect immediately for all app versions. You can also upload each configuration file separately. This is especially useful for datastore indexes, as new indexes based on existing entities take time to build before they are ready to serve datastore queries.
Notice that service configuration is separate from the application configuration, which includes URL mappings, runtime environment selection, and inbound service activation. Application configuration is bound to a specific app version.
App Engine provides rich facilities for inspecting the performance of an app while it is serving live traffic. Most of these features are available in the Cloud Console, including analytic graphs of traffic and resource usage, and browsable request and message logs. You can also use the Console to inspect and make one-off changes to datastore entities.
You also use the Cloud Console to perform maintenance tasks, such as giving other developers access to the Console, changing settings, and setting up a billing account.
In this chapter, we discuss how to upload a new app, how to update an existing app, and how to use App Engine’s versioning feature to test a new version of an app on App Engine while your users continue to use the previous version. We look at how to migrate the datastore and service configuration from one version to another. We also look at features of the SDK and the Cloud Console for inspecting, troubleshooting, and analyzing how your live application is running. And finally, we discuss other application maintenance tasks, billing, and where to get more information.
Uploading an Application
We introduced uploading an application way back in Chapter 2, but let’s begin with a brief review.
You can upload the app with the AppCfg command-line tool from the SDK. The tool takes the update action and a path to your application root directory (the directory containing the app.yaml file):
appcfg.py update clock
The upload tool determines the application ID from the appropriate configuration file. This is the application element in the app.yaml file.
The tool also uses this file to determine the version ID to use for this upload, from the version element. If App Engine does not yet have a version of this app with this ID, then it creates a new version with the uploaded files. If App Engine does have such a version, then it replaces the existing version. The replacement is total: no remnants of the previous version’s code or static files remain. The new app has only the files present in the project directory on your computer at the time of the upload. Of course, data stored by the services for the app remain, including the datastore, memcache, log data, and enqueued tasks.
The version of the app that is visible on your app’s primary domain name—either app-id.appspot.com or your custom domain—is known as the default version. When you upload your app for the first time, the initial version becomes the default version automatically. If you subsequently upload a version with a different version ID, the original version remains the default until you change the default using the Cloud Console.
Recall from Chapter 3 that each version has its own appspot.com URL that includes the version ID as well as the application ID:
Remember that there are no special protections on the version URLs. If the app does not restrict access by using code or configuration, then anyone who knows an unrestricted URL can access it. If you don’t want a user to be able to access a version other than the default, you can check the Host header in the app and respond accordingly. You can also upload the nondefault version with configuration that restricts all URLs to administrators. Be sure to upload it again with the real configuration before making it the default version.
When you replace an existing version by uploading the app with that version ID, App Engine starts using the uploaded app for requests for that version within seconds of the upload. It is not guaranteed that every request after a particular time will use the new code and static files, but it usually doesn’t take more than a few seconds for the App Master to update all the frontend servers. (It can take longer for apps with many instances and long warmup requests, as App Engine waits for new instances to be ready before diverting traffic from the previous version.) The App Master ensures that all the files are in place on a frontend server before using the new files to handle requests.
If you upload the app with the same version ID as that of the version that’s currently the default, your users will start seeing the updated app within a few seconds of uploading. This is fine for small, low-risk changes that don’t depend on changes to your data schemas or datastore indexes.
For larger changes, it’s better to upload the app with a new version ID (in the application configuration file), test the app with the version URL, then switch the default version to direct traffic to the new version. To switch the default version, go to the Cloud Console, Compute, App Engine, then select the Versions panel. Select the radio button next to the desired version, and then click the “Make default” button. This is shown in Figure 20-1.
Figure 20-1. The Versions panel in the Cloud Console
App Engine can host up to 60 different version IDs per app at one time, across all modules. You can delete unused versions from the Cloud Console by clicking the Delete button on the appropriate row.
Many actions in the Cloud Console refer to a specific version of the app, including usage statistics and the log viewer. You can control which version you’re looking at by selecting it from the drop-down menu in the top-left corner of the screen, next to the application ID. The version ID only appears as a drop-down menu if you have more than one version of the app.
Instead of updating the default version in Cloud Console, you can do this via the appcfg.py set_default_version command. This makes it easy to include this last step in your automated deployment workflows:
appcfg.py set_default_version --application=myapp --version=rel-20141231
Managing Service Configuration
All versions of an application use the same services. Service configuration and application data are shared across all versions of the app.
An app can have several service-related configuration files:
A description of all the required datastore indexes
Configuration for task queues
The schedule for scheduled tasks (cron jobs)
Whenever you upload the app, these configuration files are uploaded from your computer to the services and take effect for the entire app, replacing any configuration that was once there. This is true regardless of whether the app version ID is new or already exists, or whether the version ID is the default.
You can update the configuration for each service without uploading the entire app by using the AppCfg tool. To update just the index configuration, use the update_indexes action, with the project directory (e.g., app-dir):
appcfg.py update_indexes app-dir
To update just the task queue configuration, use update_queues:
appcfg.py update_queues app-dir
And to update just the pending task schedule, use update_cron:
appcfg.py update_cron app-dir
App Engine Settings
There are various App Engine–specific settings for projects that are important but don’t justify their own entry in the sidebar nav. You can find these in the Settings panel, under Compute, App Engine. This panel has multiple tabs to further organize these settings.
Under the Application Settings tab, you’ll find your daily budget. This is where you set the maximum daily expenditure that you want to allow for the application. If the app ends up consuming resources whose cost is covered by the full amount, App Engine stops serving the app to avoid charging you more than you’re willing to spend. This is a safety catch. Once you have an idea of how much your app’s resource usage costs during a typical day, it’s best to add a significant amount to this for your budget to accommodate unexpected traffic.
The “Google login cookie expiration” time is the amount of time a user signed in with a Google account will remain signed in. If the user signs in to your app, he will not have to sign in again from the computer he is using until the expiration time elapses.
The “Google authentication” setting refers to how Google account authentication works for apps running on a Google Apps domain. When set to “Google Accounts API,” all Google users can sign in, and it’s up to the app to decide which user is authorized to perform certain actions. When set to “Google Apps domain,” only Google accounts on the domain are allowed to sign in, and other domain account management policies apply.
This is also where you set the amount of log data to retain for the app. If you retain more than the default 1 GB, you may be billed for additional storage. See Chapter 19.
The Settings panel also provides the Custom Domains tab, which you can use for setting up a domain name for the app. (Refer back to “Domain Names”.)
When you register an application ID, you become a developer for the application automatically. You can invite other people to be developers for the application from the Permissions section of the Cloud Console. (This is a project-wide panel, under the project name.)
To invite a developer, click the Add Member button, then enter the person’s email address in the dialog that opens. You can select from several levels of access, including ownership, edit-only privileges, or read-only privileges.
App Engine sends an email to the developer inviting her to set up an account. If the email address you invited is for a Google account, the developer can use the existing account to access App Engine, although she must still accept the invitation by clicking on a link in the invitation email message. If the email address does not have a corresponding Google account, the developer can create a Google account for that address by following the instructions in the message. The developer cannot accept the invitation from a Google account with a different address; you must invite the alternative address explicitly.
An invited developer who has not yet accepted the invitation appears in the list with a status of “Pending.” After the developer accepts the invitation, she appears with a status corresponding to her level of access.
You can remove any developer from the list by clicking the Remove button for the developer. The developer loses all access immediately. You can also adjust the permission level from this screen.
Developers with view permissions can see the Console for the project, but cannot make changes or deploy code. Developers with edit permissions can do everything except manage project permissions for other people, billing, and disabling or deleting the app. Edit access includes deploying new versions, changing the default version, accessing logs, and inspecting and tweaking the datastore. All developers, including read-only developers, can access application URLs configured as administrator-only, and are recognized by the Users API as adminsitrators.
Quotas and Billing
The Cloud Console provides a detailed summary of the App Engine resources your project is using via the App Engine “dashboard.” You can locate this dashboard in the sidebar navigation: Compute, App Engine, Dashboard. This handy screen provides a visual overview of your app’s traffic, resource usage, and errors.
The topmost chart displays time-based data over the past 24 hours. You can select from several data sets to view via the drop-down menu, including requests per second, clock time or CPU time per request, bandwidth, errors, and quota denials. You can adjust the period for this chart by clicking on the buttons (such as “6 hr”).
Below the chart is a graph showing how much of the billable quotas have been consumed for the calendar day, and how much of your daily budget has been spent for each quota. A message at the upper-right of the chart indicates how much of the calendar day is remaining. If any of the bars look like they might fill up before the next reset, you may need to increase your budget for that quota to avoid quota denials.
Near the bottom of the dashboard are lists of popular URL paths and URLs that are returning errors. You can click on a URL to view the detailed request logs for that URL path.
The dashboard’s time-based chart and URL traffic lists show data for the version of the app selected by the drop-down menu in the upper-left corner of the screen. When you first sign in to the Console, the default version is selected. To view data for a different version of the app, select it from the drop-down menu.
You can view a more comprehensive chart of how the app is consuming resources with quotas from the Quota Details section of the Cloud Console. This chart shows billable quotas as well as several fixed quotas, such as API calls and service bandwidth. If your app is having quota-denial errors, check this screen for information on how the app is consuming resources.
The resource usage chart on the dashboard and the quota details screen show the total of all resource usage for all versions of the app. All versions of an app share the same budget and quotas.
When your app is ready to outgrow the free quotas, you can set a budget for additional resources. App Engine allocates more resources as needed according to the budget you establish, and you are only billed for the resources actually consumed.
You probably set up a billing account when you created the project. If you need to adjust which account is associated with the project select the Billing & Settings panel in the Cloud Console. The owner of the billing account is solely responsible for setting the budget and paying for resources consumed.
If you have questions not answered by this book, you may find your answers in the official documentation on Google’s website:
The documentation includes complete references for the APIs and tools for the Python runtime environment; a list of frequently asked questions and answers (the FAQ); and a large collection of articles describing best practices, interesting features, and complete working examples.
You may also want to browse the contents of the App Engine libraries as installed by the Cloud SDK. The source code for the Python SDK serves as supplementary documentation, and includes several undocumented (and unsupported) features and extensions. The SDK also includes a set of functional example applications.
All App Engine developers should subscribe to Google’s App Engine downtime mailing list. This low-traffic, announcement-only list is used by the App Engine team to announce scheduled times when services are taken down for maintenance, and also to report the status of unexpected problems:
You can check the current and past health of App Engine and its services by consulting the system status site:
By far the best place to ask questions about Google App Engine is Stack Overflow. Post your question with the google-app-engine tag, and it’ll be seen by the App Engine developer community, as well as the App Engine team at Google. As you learn more, you can answer other people’s questions and build your reputation as an App Engine expert. You can also use Google to search through past answers, which may have what you’re looking for:
If you believe you have found a bug in App Engine, the SDK, or the Cloud Console, or if you have a feature you’d like to request, you can post to the App Engine issue tracker. You can also see features others have requested, and vote for your favorites. (The App Engine team does indeed consider the highly requested features in this list when determining the product road map.)
Google has a general discussion group for App Engine developers and an IRC channel, and also does regular live-streamed video question-and-answer sessions with the team. This page has more information on community resources: