If you previously used the Java App Engine SDK-based plugin
(com.google.appengine.appengine-gradle
) and want to move to the new
Google Cloud CLI, migrate to the gcloud CLI-based
(com.google.cloud.tools.appengine-gradle
) plugin.
Benefits of the gcloud CLI-based plugin
Upgrading to the new plugin provides the following benefits:
Uses the same authentication credentials as all other gcloud CLI -based commands, which are produced from the standard
gcloud auth login
flow.Supports the App Engine flexible environment.
Updates the local development server automatically as part of the standard gcloud CLI update flow.
Supports deploying App Engine service (cron, queues, dos, dispatch) configurations, independently from your service.
Notable differences
Before you migrate, be aware of these notable differences:
- gcloud CLI dependency
- The old plugin runs without any specific local environment dependencies, besides Java, but the new plugin requires that you have the gcloud CLI installed.
- No Endpoints discovery doc generation
- The new plugin does not generate Endpoints discovery docs, a feature available in a separate plugin. Running your Endpoints backend no longer requires generating this file in a build step as the server now generates it at runtime. You should use the new plugin only if you need to generate client libraries such as for iOS or Android. Learn more about the new plugins by reviewing the Migrating to Endpoints Frameworks for App Engine guide.
- EAR file format no longer supported
- The new plugin no longer supports the EAR file format for running and deploying multiple services at the same time.
- New deployment command
- The old plugin calls the
appcfg
command to deploy applications, while the new plugin deploys using the new gcloud CLI. - JPA/JDO Datanucleus enhancement must be manually configured
- If your project
uses the
gradle-appengine-plugin
’s JPA/JDO Datanucleus enhancement, you must manually configure Datanucleus enhancement after switching to the gcloud CLI-based plugin. See an example from Stackoverflow. - Android Studio is not supported
- You can switch your Android Studio project to use the new plugin, but the Android Studio App Engine development server and deployment support does not work with this new plugin. To run and deploy your app, you have to invoke Gradle directly.
Use of XML configuration files is supported, but not YAML.
Migrating to the new plugin
Remove the old
gradle-appengine-plugin
configuration and imports from yourbuild.gradle
file.Add the new plugin to the
classpath
of yourbuild.gradle
file'sbuildscript
section:buildscript { repositories { mavenCentral() } dependencies { classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1' } }
At the root of your service, run the following command to verify that you can run your app locally:
gradle appengineRun
In your
build.gradle
file'sbuildscript
section, configure your deployment by specifying your project ID and version:appengine { deploy { version = 'v1' project = "your GCP project ID" } }
The new tooling ignores the application and version elements in your
appengine-web.xml
file.At the root of your service, run the following command to verify that you can deploy your application:
gradle appengineDeploy
Migrating EAR based multi-service configurations
The new plugin does not support EAR packaging. Instead, it supports running multiple services locally without any special packaging steps.
To migrate your EAR-based Gradle project:
Pick a primary service that will be responsible for running the rest of the services. You should select your default service, but it can be any of the services that are run together.
In your
appengine
configuration, modify therun.services
entry to include all the services that should be run by the local development server.An example project structure:
../{projectRoot}/ build.gradle settings.gradle (includes default-service & secondary-service) {your-default-service}/build.gradle {includes appengine-gradle-plugin} …. {your-default-service}/src/main/webapp/WEB-INF/appengine-web.xml {your-secondary-service}build.gradle {includes appengine-gradle-plugin} …. {your-secondary-service}/src/main/webapp/WEB-INF/appengine-web.xml
An example
build.gradle
buildscript:appengine { run { // configure the app to point to the right service directories services = [ projectAsService(project), projectAsService(":another-module") ] } } // helper method to obtain correct directory and set up dependencies def getExplodedAppDir(Project serverProject) { // if not 'this' module, then do some setup. if (serverProject != project) { // make sure we evaluate other modules first so we get the right value evaluationDependsOn(serverProject.path) // make sure we build "run" depends on the other modules exploding wars project.tasks.appengineRun.dependsOn serverProject.tasks.explodeWar } return serverProject.tasks.explodeWar.explodedAppDirectory }
App Engine SDK-based vs gcloud CLI-based Gradle commands
The following table shows the different ways you invoke the Gradle plugin, depending on whether you use the App Engine SDK-based Gradle plugin or the gcloud CLI-based Gradle plugin.
Action | App Engine SDK-based | gcloud CLI-based |
---|---|---|
Run the app locally | appengine:devserver |
appengineRun |
Deploy a new app, version, or service. | appengine:update |
appengineDeploy |
Set the default application version. | appengine:set_default_version |
gcloud app services set-traffic or gcloud app versions migrate |
Update application cron jobs. | appengine:update_cron |
appengineDeployCron |
Update the application dispatch configuration. | appengine:update_dispatch |
appengineDeployDispatch |
Update application DoS protection configuration. | appengine:update_dos |
appengineDeployDos |
Update application task queue definitions. | appengine:update_queues |
appengineDeployQueue |
Update Datastore Indexes. | appengine:update_indexes |
appengineDeployIndex |
Delete unused indexes from application. | appengine:vacuum_indexes |
gcloud datastore indexes cleanup |
Start the specified module version. | appengine:start_module_version |
gcloud app versions start |
Stop the specified module version. | appengine:stop_module_version |
gcloud app versions stop |
Rollback an in-progress update. | appengine:rollback |
gcloud app versions start, gcloud app versions stop |
What's next
- Now that you have migrated to the new plugin successfully, you can test and deploy your application.