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 Google Cloud SDK, you must migrate to the new Google 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 install the Google Cloud SDK.
No Cloud Endpoints discovery doc generation
The new plugin does not generate Cloud Endpoints discovery docs, a feature available in a separate plugin. Running your Cloud 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 XML configuration files is supported, but not YAML.

Migrating to the new plugin

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>1.3.1</version>
                <configuration>
                    <project>your-project-name-goes-here</project>
                    <version>1</version>
                </configuration>
            </plugin>
           ….
        </plugins>
    </build>
    
  2. Specify your target GCP project ID and service 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 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, do the following:

  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>1.3.1</version>
        <configuration>
            <deploy.project>your-project-name</deploy.project>
            <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 appengine:run
    
  3. After verifying that your default service is running all the services locally, completely remove your EAR package.

To deploy all your services with one Maven command, add the appengine-maven-plugin to your parent pom.xml and call mvn appengine:deploy from your multi-service project's root directory.

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 Google Cloud SDK-based
Run the app locally appengine:devserver appengine:run
Deploy a new app, version, or service. appengine:update appengine:deploy
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:deploy
Delete unused indexes from application. appengine:vacuum_indexes appengine:deployIndex
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
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.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

App Engine standard environment for Java