Migrar al complemento de Gradle basado en la CLI de gcloud

Si ya usaste el complemento del SDK de App Engine para Java (com.google.appengine.appengine-gradle) y deseas pasar a la nueva Google Cloud CLI, migra al complemento basado en la CLI de gcloud (com.google.cloud.tools.appengine-gradle).

Beneficios del complemento basado en la CLI de gcloud

La actualización al complemento nuevo brinda estos beneficios:

  • Usa las mismas credenciales de autenticación que usan todos los otros comandos basados en la CLI de gcloud, que se producen a partir del flujo gcloud auth login estándar.

  • Es compatible con el entorno flexible de App Engine.

  • Actualiza de manera automática el servidor de desarrollo local como parte del flujo de actualización estándar de la CLI de gcloud.

  • Admite la implementación de las configuraciones de servicio de App Engine (cron, colas, DoS, envío), de forma independiente de tu servicio.

Diferencias destacadas

Antes de migrar, ten en cuenta estas diferencias importantes:

dependencia de la CLI de gcloud
El complemento anterior se ejecuta sin dependencias específicas del entorno local, además de Java, pero el nuevo requiere que instales la CLI de gcloud.
Sin generación de documentos de descubrimiento de extremos
El complemento nuevo no genera documentos de descubrimiento de Endpoints. Esta característica está disponible en un complemento distinto. La ejecución del backend de extremos ya no requiere la generación de este archivo en un paso de compilación, ya que ahora el servidor lo genera en el entorno de ejecución. Usa el complemento nuevo solo si necesitas generar bibliotecas cliente como las de iOS o Android. Si quieres obtener más información sobre los complementos nuevos, revisa la guía Migra a Endpoints Frameworks para App Engine.
El formato de archivo EAR ya no es compatible
El complemento nuevo ya no admite el formato de archivo EAR para implementar y ejecutar varios servicios a la vez.
Comando de implementación nuevo
El complemento anterior llama al comando appcfg para implementar aplicaciones, mientras que el complemento nuevo implementa con la nueva CLI de gcloud
.
Las mejoras de JPA/JDO de Datanucleus se deben configurar de forma manual
Si tu proyecto usa la mejora Datanucleus de JPA/JDO de gradle-appengine-plugin, debes configurar manualmente la mejora de Datanucleus después de cambiar al complemento basado en la CLI de gcloud. Observa un ejemplo de Stackoverflow.
Android Studio no es compatible
Puedes hacer que tu proyecto de Android Studio use el complemento nuevo, pero el servidor de desarrollo y la asistencia de implementación de App Engine para Android Studio no funcionan con él. Para implementar y ejecutar tu app, debes invocar a Gradle de forma directa.

Se admite el uso de los archivos de configuración XML, pero no los YAML.

Migra al complemento nuevo

  1. Quita la configuración gradle-appengine-plugin anterior y las importaciones del archivo build.gradle.

  2. Agrega el nuevo complemento a la classpath de la sección buildscript del archivo build.gradle:

    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
        }
    }
    
  3. En la raíz de tu servicio, ejecuta el siguiente comando para verificar que puedas ejecutar tu aplicación de manera local:

    gradle appengineRun
    
  4. En la sección buildscript del archivo build.gradle, configura la implementación mediante la especificación del ID del proyecto y la versión:

    appengine {
        deploy {
            version = 'v1'
            project = "your GCP project ID"
        }
    }
    

    Las herramientas nuevas ignoran los elementos de la aplicación y la versión en el archivo appengine-web.xml.

  5. En la raíz de tu servicio, ejecuta el siguiente comando para verificar que puedas implementar tu aplicación:

    gradle appengineDeploy
    

Cómo migrar configuraciones de varios servicios basadas en EAR

El complemento nuevo no admite paquetes de EAR. En su lugar, admite ejecutar varios servicios de forma local sin pasos de empaquetado especiales.

Para migrar tu proyecto Gradle basado en EAR:

  1. Elige un servicio principal que será responsable de ejecutar el resto de los servicios. Deberías seleccionar el servicio predeterminado, pero puede ser cualquiera de los servicios que se ejecutan en conjunto.

  2. En tu configuración appengine, modifica la entrada run.services para incluir todos los servicios que el servidor de desarrollo local debe ejecutar.

    Este es un ejemplo de la estructura del proyecto:

    ../{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
    

    Este es un ejemplo de buildscript build.gradle:

    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
    }
    

Comparación de los comandos basados en el SDK de App Engine y los comandos de Gradle basados en la CLI de gcloud

La siguiente tabla muestra las diferentes formas de invocar el complemento Gradle, según si usas el complemento Gradle basado en el SDK de App Engine o el complemento Gradle basado en la CLI de gcloud.

Acción Basado en el SDK de App Engine Basado en la CLI de gcloud
Ejecuta la app de forma local appengine:devserver appengineRun
Implementar una app, una versión o un servicio nuevo appengine:update appengineDeploy
Configurar la versión de la aplicación predeterminada appengine:set_default_version gcloud app services set-traffic o gcloud app versions migrate
Actualizar los trabajos cron de la aplicación appengine:update_cron appengineDeployCron
Actualiza la configuración de despacho de la aplicación. appengine:update_dispatch appengineDeployDispatch
Actualizar la configuración de protección contra DoS de la aplicación appengine:update_dos appengineDeployDos
Actualizar las definiciones de la lista de tareas en cola de la aplicación appengine:update_queues appengineDeployQueue
Actualizar los índices de Datastore appengine:update_indexes appengineDeployIndex
Borrar los índices sin uso de la aplicación appengine:vacuum_indexes Limpieza de índices de Datastore de gcloud
Inicia la versión especificada del módulo. appengine:start_module_version gcloud app versions start
Finaliza la versión del módulo especificado. appengine:stop_module_version gcloud app versions stop
Revierte una actualización en curso. appengine:rollback gcloud app versions start, gcloud app versions stop

Próximos pasos

  • Ahora que migraste de forma correcta al complemento nuevo, puedes probar y, además, implementar tu aplicación.