Migrating to the gcloud CLI-based Gradle plugin

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

1. Remove the old gradle-appengine-plugin configuration and imports from your build.gradle file.

2. Add the new plugin to the classpath of your build.gradle file's buildscript section:

   buildscript {
       repositories {
           mavenCentral()
       }
   
       dependencies {
           classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
       }
   }
   

3. At the root of your service, run the following command to verify that you can run your app locally:

   gradle appengineRun
   

4. In your build.gradle file's buildscript 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.

5. 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:

1. 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.

2. In your appengine configuration, modify the run.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.