Migrating to the Cloud SDK-based Maven plugin

If you are using the Java App Engine SDK-based plugin (com.google.appengine.appengine-maven) and want to move to the new Cloud SDK, migrate to the Cloud SDK-based (com.google.cloud.tools.appengine-maven) plugin.

Benefits of the Cloud SDK-based plugin

Upgrading to the new plugin provides the following benefits:

• Uses the same authentication credentials as all other Cloud SDK -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 Cloud SDK update flow.

• Supports deploying App Engine service (cron, queues, dos, dispatch) configurations, independently from your service.

• Sets up environment variables in appengine-web.xml for local service runs.

• Supports multiple services without requiring EAR packaging.

Notable differences

Before you migrate, be aware of these notable differences:

Cloud SDK dependency

The old plugin runs without any specific local environment dependencies, besides Java, but the new plugin requires that you have the Cloud SDK 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 tasks are no longer included

The new plugin does not support Datanucleus enhancement of any type. If your project uses the Datanucleus JDO or JPA enhancement support from the old plugin, you must configure the 3rd party Datanucleus (JDO instructions, JPA instructions), Maven plugin separately when you migrate.

Use of YAML configuration files is supported, but not XML.

Migrating to the new plugin

Note: You should first add and validate that the new plugin works before you remove the old plugin from your pom.xml file.

To migrate to the new plugin, do the following:

1. Add the Cloud SDK-based plugin to your pom.xml file.

   <build>
       <plugins>
          [...]
             <plugin>
               <groupId>com.google.cloud.tools</groupId>
               <artifactId>appengine-maven-plugin</artifactId>
               <version>2.0.0</version>
               <configuration>
                   <projectId>your-project-ID-goes-here</projectId>
                   <version>1</version>
               </configuration>
           </plugin>
          [...]
       </plugins>
   </build>
   

2. Specify your target Google Cloud Platform project ID and the service and version in the plugin configuration. The new tooling ignores the application and version elements in your appengine-web.xml file.

3. Test your new config by running and deploying your application as follows:

   1. Run the app using the plugin's fully qualified name:

        mvn com.google.cloud.tools:appengine-maven-plugin:run
      

   2. Deploy the app using the plugin's fully qualified name:

        mvn com.google.cloud.tools:appengine-maven-plugin:deploy
      

      Be sure to namespace the plugin goal invocation if you still have the old appengine plugin in your pom.xml.

If you have a more customized configuration, you should find equivalent staging, local run, and deployment flags in the new plugin.

After verifying that everything is working as expected, remove the com.google.appengine appengine-maven-plugin from your pom.xml and the application and version elements from your appengine-web.xml file.

You can now invoke your new plugin’s goals using the shortened notation:

mvn package appengine:deploy

Migrating EAR-based multi-service configurations

With the new plugin, you don't aggregate your services in an EAR package. Instead, you specify a list of services to run from the appengine-maven-plugin configuration of any of your App Engine services.

You can configure these services to run in your default service because all App Engine projects require a default service.

To migrate your EAR-based App Engine project to the new tools:

1. For every context-root in the application.xml of your EAR package, add a service element to your default services appengine-maven-plugin run config. For example:

   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>2.0.0</version>
       <configuration>
           <deploy.projectId>your-project-name</deploy.projectId>
           <deploy.version>your-project-version</deploy.version>
           <services>
               <!-- your default service -->
               <service>${project.build.directory}/${project.name}-${project.version}
               </service>
               <!-- for each service in your EARs application.xml -->
               <service>
                   ${project.parent.basedir}/service-name/target/service-artifact-${project.version}
               </service>
           </services>
       </configuration>
   </plugin>
   

2. Confirm your new config works by running the following command from your default service directory:

   mvn package appengine:run
   

3. After verifying that your default service is running all the services locally, completely remove your EAR package.

If the root directory of your project contains only your services, you can deploy all those services with one Maven command. You must first add the appengine-maven-plugin to your parent pom.xml file and then you can run the mvn appengine:deploy command.

The deployment command iterates through each of your project’s services to locate their configuration files and then deploy each service.

Note: The root directory of your project cannot include other Maven modules, EAR packages, or .jar files that do not define an App Engine service. The deployment command treats those files as services and fails when configuration files are not found.

App Engine SDK-based vs Cloud SDK-based Maven commands

The following table shows the different ways you invoke the Maven plugin, depending on whether you use the App Engine SDK-based Maven plugin or the Cloud SDK-based Maven plugin.

Action	App Engine SDK-based	Cloud SDK-based
Run the app locally	appengine:devserver	appengine:run
Deploy a new app, version, or service.	appengine:update	appengine:deploy or appengine:deployAll
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	appengine:deployCron
Update the application dispatch configuration.	appengine:update_dispatch	appengine:deployDispatch
Update application DoS protection configuration.	appengine:update_dos	appengine:deployDos
Update application task queue definitions.	appengine:update_queues	appengine:deployQueue
Update Datastore Indexes.	appengine:update_indexes	appengine:deployIndex
Delete unused indexes from application.	appengine:vacuum_indexes	gcloud datastore cleanup-indexes
Start the specified version.	appengine:start_module_version	gcloud app versions start
Stop the specified version.	appengine:stop_module_version	gcloud app versions stop
Rollback an in-progress update.	appengine:rollback Note that you can also migrate traffic back to an older version	gcloud app versions start, gcloud app versions stop, or use gcloud app services set-traffic to migrate back to an older version.