Effectuer la migration vers le plug-in Gradle basé sur gcloud CLI

Si vous avez déjà utilisé le plug-in basé sur le SDK Java App Engine (com.google.appengine.appengine-gradle) et que vous souhaitez passer au nouvel outil Google Cloud CLI, migrez vers le plug-in basé sur la CLI gcloud (com.google.cloud.tools.appengine-gradle).

Avantages du plug-in basé sur la CLI gcloud

La mise à niveau vers le nouveau plug-in offre les avantages suivants :

  • Le plug-in utilise les mêmes identifiants d'authentification que toutes les autres commandes basées sur gcloud CLI, qui sont générées à partir du flux gcloud auth login standard.

  • Il est compatible avec l'environnement flexible App Engine.

  • Il met automatiquement à jour le serveur de développement local lors du flux de mise à jour standard de gcloud CLI.

  • Il accepte le déploiement des configurations de services App Engine (Cron, files d'attente, DoS, distribution), indépendamment de votre service.

Différences notables

Avant d'effectuer la migration, veuillez prendre en compte les différences notables suivantes :

Dépendance de gcloud CLI
L'ancien plug-in s'exécute sans aucune dépendance spécifique à l'environnement local, hors Java, mais le nouveau plug-in nécessite l'installation de gcloud CLI.
Aucune génération de documents de découverte Endpoints
Le nouveau plug-in ne génère pas de documents de découverte Endpoints. Cette fonctionnalité est disponible dans un plug-in distinct. L'exécution du backend Endpoints n'exige plus de générer ce fichier lors d'une étape de compilation, car le serveur le génère désormais au moment de l'exécution. Vous ne devez utiliser le nouveau plug-in que si vous devez générer des bibliothèques clientes, comme celles pour iOS ou Android. Pour en savoir plus sur les nouveaux plug-ins, consultez le guide Migrer vers Endpoints Frameworks pour App Engine.
Le format de fichier EAR n'est plus accepté.
Le nouveau plug-in n'accepte plus le format de fichier EAR pour l'exécution et le déploiement de plusieurs services en même temps.
Nouvelle commande de déploiement
L'ancien plug-in appelle la commande appcfg pour déployer des applications, alors que le nouveau plug-in utilise la nouvelle CLI gcloud pour les déploiements.
L'amélioration de JPA/JDO Datanucleus doit être configurée manuellement
Si votre projet utilise l'amélioration JPA/JDO Datanucleus de gradle-appengine-plugin, vous devez configurer manuellement l'amélioration Datanucleus après le passage au plug-in basé sur la CLI gcloud. Consultez un exemple sur Stack Overflow.
Android Studio n'est pas compatible
Vous pouvez indiquer à votre projet Android Studio d'utiliser le nouveau plug-in, mais le serveur de développement et l'assistance de déploiement App Engine d'Android Studio ne fonctionnent pas avec celui-ci. Pour exécuter et déployer votre application, vous devez appeler directement Gradle.

L'utilisation des fichiers de configuration au format XML est acceptée, mais pas au format YAML.

Migrer vers le nouveau plug-in

  1. Supprimez l'ancienne configuration gradle-appengine-plugin et les importations précédentes à partir de votre fichier build.gradle.

  2. Ajoutez le nouveau plug-in au chemin de classe classpath de la section buildscript de votre fichier build.gradle :

    buildscript {
        repositories {
            mavenCentral()
        }
    
        dependencies {
            classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
        }
    }
    
  3. À la racine de votre service, exécutez la commande suivante pour vérifier que vous pouvez exécuter votre application en local :

    gradle appengineRun
    
  4. Dans la section buildscript du fichier build.gradle, configurez le déploiement en spécifiant l'ID de votre projet et sa version :

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

    Le nouvel outil ignore les éléments d'application et de version du fichier appengine-web.xml.

  5. À la racine de votre service, exécutez la commande suivante pour vérifier que vous pouvez déployer votre application :

    gradle appengineDeploy
    

Migrer des configurations multiservices basées sur EAR

Le nouveau plug-in n'est pas compatible avec l'empaquetage EAR. À la place, il accepte l'exécution de plusieurs services en local sans aucune étape de création de package particulière.

Pour migrer un projet Gradle basé sur EAR, procédez comme suit :

  1. Choisissez un service principal qui sera chargé de l'exécution du reste des services. Vous devez sélectionner le service par défaut, mais il peut s'agir de l'un des services exécutés ensemble.

  2. Dans la configuration appengine, modifiez l'entrée run.services afin d'inclure tous les services devant être exécutés par le serveur de développement local.

    Exemple de structure de projet :

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

    Exemple de script de compilation 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
    }
    

Comparaison entre les commandes Gradle basées sur le SDK App Engine et celles basées sur la CLI gcloud

Dans le tableau suivant, vous pouvez découvrir les différentes manières d'appeler le plug-in Gradle, selon que vous utilisez le plug-in Gradle basé sur le SDK App Engine ou le plug-in Gradle basé sur la CLI gcloud.

Action Basée sur le SDK App Engine Basée sur gcloud CLI
Exécuter l'application en local appengine:devserver appengineRun
Déployer une nouvelle application, une nouvelle version ou un nouveau service appengine:update appengineDeploy
Définir la version de l'application par défaut appengine:set_default_version gcloud app services set-traffic ou gcloud app versions migrate
Mettre à jour les tâches Cron de l'application appengine:update_cron appengineDeployCron
Mettre à jour la configuration de distribution de l'application. appengine:update_dispatch appengineDeployDispatch
Mettre à jour la configuration de la protection DoS pour l'application appengine:update_dos appengineDeployDos
Mettre à jour les définitions de la file d'attente de tâches de l'application appengine:update_queues appengineDeployQueue
Mettre à jour les index Datastore appengine:update_indexes appengineDeployIndex
Supprimer les index non utilisés de l'application appengine:vacuum_indexes gcloud datastore indexes cleanup
Lance la version de module spécifiée. appengine:start_module_version gcloud app versions start
Arrêter la version de module spécifiée appengine:stop_module_version gcloud app versions stop
Effectuer un rollback de la mise à jour en cours d'exécution appengine:rollback gcloud app versions start, gcloud app versions stop

Étape suivante

  • Après avoir migré vers le nouveau plug-in, vous pouvez tester et déployer votre application.