Migration zum gcloud-CLI-basierten Gradle-Plug-in

Wenn Sie zuvor das Java App Engine SDK-basierte Plug-in (com.google.appengine.appengine-gradle) verwendet haben und zur neuen Google Cloud CLI wechseln möchten, migrieren Sie zum gcloud CLI-basierten Plug-In (com.google.cloud.tools.appengine-gradle).

Vorteile des gcloud CLI-basierten Plug-ins

Ein Upgrade auf das neue Plug-in bietet folgende Vorteile:

  • Verwendung derselben Anmeldedaten für die Authentifizierung wie bei allen anderen gcloud CLI-basierten Befehlen, die im Rahmen des standardmäßigengcloud auth login-Ablaufs erstellt werden.

  • Unterstützung der flexiblen App Engine-Umgebung

  • Automatische Aktualisierung des lokalen Entwicklungsservers im Rahmen des standardmäßigen gcloud CLI-Aktualisierungsablaufs.

  • Unterstützung der Bereitstellung von Konfigurationen für App Engine-Dienste (cron, queues, dos, dispatch) unabhängig von Ihrem Dienst

Wichtige Unterschiede

Berücksichtigen Sie vor der Migration folgende wichtige Unterschiede:

Abhängigkeit von gcloud CLI
Mit Ausnahme von Java wird das alte Plug-in ohne spezifische lokale Umgebungsabhängigkeiten ausgeführt. Allerdings erfordert das neue Plug-in die Installation der gcloud CLI.
Keine Generierung von Endpoints-Discovery-Dokumenten
Das neue Plug-in generiert keine Endpoints-Discovery-Dokumente. Dieses Feature ist in einem separaten Plug-in verfügbar. Zur Ausführung des Endpoints-Back-Ends muss diese Datei nicht mehr in einem Build-Schritt generiert werden. Dies übernimmt der Server zur Laufzeit. Sie sollten das neue Plug-in nur verwenden, wenn Sie Clientbibliotheken generieren müssen, etwa für iOS oder Android. Weitere Informationen zu den neuen Plug-ins finden Sie in der Anleitung Zu Endpoints Frameworks für App Engine migrieren.
Das EAR-Dateiformat wird nicht mehr unterstützt
Das EAR-Dateiformat zum gleichzeitigen Ausführen und Bereitstellen mehrerer Dienste wird im neuen Plug-in nicht mehr unterstützt.
Neuer Bereitstellungsbefehl
Im alten Plug-in muss zur Bereitstellung von Anwendungen der Befehl appcfg aufgerufen werden. Im neuen Plug-in erfolgt dies über die neue gcloud CLI.
JPA/JDO-DataNucleus-Erweiterung muss manuell konfiguriert werden
Wenn in Ihrem Projekt die JPA/JDO-Datanucleus-Erweiterung von gradle-appengine-plugin verwendet wird, müssen Sie die Datanucleus-Erweiterung nach dem Wechsel zum gcloud CLI-basierten Plug-in manuell konfigurieren. Siehe Stackoverflow-Beispiel.
Android Studio wird nicht unterstützt
Sie können Ihr Android Studio-Projekt auf die Verwendung des neuen Plug-ins umstellen, allerdings funktionieren der App Engine-Entwicklungsserver für Android Studio und die Bereitstellungsunterstützung nicht mit dem neuen Plug-in. Sie müssen Gradle direkt aufrufen, um Ihre Anwendung auszuführen und bereitzustellen.

Die Verwendung von XML-Konfigurationsdateien wird unterstützt, jedoch nicht YAML.

Zum neuen Plug-in migrieren

  1. Entfernen Sie die alte gradle-appengine-plugin-Konfiguration und die Importe aus der build.gradle-Datei.

  2. Fügen Sie das neue Plug-in in den classpath des Abschnitts buildscript Ihrer build.gradle-Datei ein:

    buildscript {
    repositories {
        mavenCentral()
    }

    dependencies {
        classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.0.1'
    }
}

  3. Führen Sie im Stammverzeichnis Ihres Dienstes folgenden Befehl aus, um zu prüfen, ob Sie Ihre Anwendung lokal ausführen können:

    gradle appengineRun

  4. Konfigurieren Sie im Abschnitt buildscript der Datei build.gradle Ihre Bereitstellung. Geben Sie dazu Ihre Projekt-ID und Version an:

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

    Das neue Tool ignoriert die Anwendungs- und Versionselemente in der Datei appengine-web.xml.

  5. Führen Sie im Stammverzeichnis Ihres Dienstes folgenden Befehl aus, um zu prüfen, ob Sie Ihre Anwendung bereitstellen können:

    gradle appengineDeploy

EAR-basierte Konfigurationen für mehrere Dienste migrieren

Das neue Plug-in unterstützt keine EAR-Paketerstellung. Stattdessen wird die lokale Ausführung mehrerer Dienste ohne spezielle Paketerstellungsschritte unterstützt.

So migrieren Sie Ihr EAR-basiertes Gradle-Projekt:

  1. Wählen Sie einen primären Dienst aus, der für die Ausführung der übrigen Dienste zuständig ist. Sie sollten Ihren Standarddienst auswählen, es kann aber auch jeder andere Dienst sein, der zusammen mit den anderen ausgeführt wird.

  2. Ändern Sie in der appengine-Konfiguration den Eintrag run.services dahingehend, dass alle Dienste eingeschlossen sind, die vom lokalen Entwicklungsserver ausgeführt werden sollen.

    Eine Beispielprojektstruktur:

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

    Ein Beispiel für ein build.gradle-Build-Skript:

    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-basierte und gcloud-CLI-basierte Gradle-Befehle im Vergleich

Die folgende Tabelle zeigt verschiedene Möglichkeiten zum Aufrufen des Gradle-Plug-ins, je nachdem, ob Sie das App Engine SDK-basierte Gradle-Plug-in oder das gcloud CLI-basierte Gradle-Plug-in verwenden.

Aktion App Engine SDK-basiert gcloud CLI-basiert
Anwendung lokal ausführen appengine:devserver appengineRun
Stellt neue Anwendung, neue Version oder neuen Dienst bereit. appengine:update appengineDeploy
Legt die Standardversion der Anwendung fest. appengine:set_default_version gcloud app services set-traffic oder gcloud app versions migrate
Aktualisiert die Cronjobs der Anwendung. appengine:update_cron appengineDeployCron
Aktualisiert die Weiterleitungskonfiguration der Anwendung. appengine:update_dispatch appengineDeployDispatch
Aktualisiert die DoS-Schutzkonfiguration der Anwendung. appengine:update_dos appengineDeployDos
Aktualisiert Aufgabenwarteschlangen-Definitionen der Anwendung. appengine:update_queues appengineDeployQueue
Aktualisiert Datenspeicherindexe. appengine:update_indexes appengineDeployIndex
Löscht nicht verwendete Indizes aus der Anwendung. appengine:vacuum_indexes Bereinigung von gcloud-Datenspeicherindexen
Startet die angegebene Modulversion. appengine:start_module_version gcloud app versions start
Stoppt die angegebene Modulversion. appengine:stop_module_version gcloud app versions stop
Führt für ein laufendes Update ein Rollback aus. appengine:rollback gcloud app versions start, gcloud app versions stop

Weitere Informationen